Discord SDK

The discord module is exposed on the global scope within the Pylon runtime.

See the Discord SDK section of our Documentation site for an in-depth walk-through of our Discord SDK!

Event-Based Runtime

Events are executed as they are received from the Discord Gateway. You can register event handlers within the Pylon runtime to act upon new messages, guild members, reactions, and much more. Event handlers are expected to be Promises, which may kick off or await additional async tasks.

See discord.on for a list of events and their respective payloads.

Fetching Data

Pylon keeps an in-memory cache of Discord-related objects (guilds, members, channels, messages, etc) to reduce the amount of external calls made to the Discord API when requesting data. As events are received from the gateway, this cache is updated to reflect the latest state-of-the-world at all times.

Most data objects in the Discord SDK have a handful of async functions to fetch data on related objects. If an object is not found, null is typically returned.

Example: A simple `!test` command that fetches and returns miscellaneous data.

const commands = new discord.command.CommandGroup({
  defaultPrefix: '!'
});

commands.raw('test', async (message) => {
// Get the author of the message
const user = message.author;

// Fetch the guild this message was sent in
const guild = await message.getGuild();

 // Get the channel the message was sent in, note the 'await' keyword
 const channel = await message.getChannel();

 // Fetch role data from the guild for all the roles the user has assigned
 const roles = await Promise.all(
   message.member.roles.map((roleId) => guild.getRole(roleId))
 );

 // Construct a list of role names, separated by new lines
 const roleNames = roles
   .map((role) => {
     if (!role) return;
     return ` - ${role.name}`;
   })
   .join('\n');

 // Reply with some data we found
 await message.reply(
   `You are ${user.toMention()} sending a message in ${channel.toMention()}. You have the following roles:\n${roleNames}`
 );
});

Making Discord API requests

Pylon abstracts API requests into simple functions on data objects, you cannot make Discord API requests directly. If a request is rate-limited, it will delay promise resolution until it is able to execute.

const COOL_ROLE_ID = '421726263504229715';
discord.on('MESSAGE_CREATE', async (message) => {
  // We only care about messages sent in a guild by users
  if (!(message instanceof discord.GuildMemberMessage)) {
    return;
  }

  // A very !cool command.
  if (message.content !== "!cool") {
    return;
  }

  // Do some things with the member
  await message.member.addRole(COOL_ROLE_ID);
  await message.member.edit({ nick: "Mr. Cool" });

  // Respond
  await message.reply("You are now Mr. Cool!");
})

Index

Namespaces

Enumerations

Interfaces

Type aliases

Snowflake

Events

Functions

Type aliases

Snowflake

Snowflake: string

Unique identifiers assigned to most Discord objects. You can read more about Snowflakes and how Discord uses them on the Discord docs.

You can copy IDs directly from the Discord app if you have Developer Mode enabled.

Example: Fetching channel data with a Channel ID (snowflake) manually.

const someChannel = await discord.getChannel("640648987937865738");

Events

on

on(event: MESSAGE_CREATE | "MESSAGE_CREATE", handler: function): void
Fired when new messages are sent in any channel the current bot can read.

Example: Log all messages to the developer console, and respond to "foo" with "bar".
```
discord.on("MESSAGE_CREATE", async (message) => {
  console.log(message);

  if (message.content === "foo") {
    await message.reply("bar");
  }
});
```
Note: If you want to create commands, please make use of the command handlers found in discord.command.

Note: MESSAGE_CREATE events will not be fired for messages sent by the bot itself.
Parameters
- event: MESSAGE_CREATE | "MESSAGE_CREATE"
- handler: function
  - - (message: AnyMessage) => Promise<unknown>
    - Parameters
      - message: AnyMessage
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_UPDATE | "MESSAGE_UPDATE", handler: function): void
Fired when a message is edited or otherwise updated.

Note: This event is fired for messages containing embedded links when the unfurl is complete. In this case, the new message object contains the unfurled embed. If you want to see if a user edited a message's content, diff the Message.content property.

Parameters
- event: MESSAGE_UPDATE | "MESSAGE_UPDATE"
- handler: function
  - - (message: AnyMessage, oldMessage: AnyMessage | null) => Promise<unknown>
    - Parameters
      - message: AnyMessage
      - oldMessage: AnyMessage | null
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_DELETE | "MESSAGE_DELETE", handler: function): void
Fired when a message is deleted from a channel.

If the message data pre-deletion was cached, it will be returned as the second parameter to the handler.

Parameters
- event: MESSAGE_DELETE | "MESSAGE_DELETE"
- handler: function
  - - (event: IMessageDelete, oldMessage: AnyMessage | null) => Promise<unknown>
    - Parameters
      - event: IMessageDelete
      - oldMessage: AnyMessage | null
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_DELETE_BULK | "MESSAGE_DELETE_BULK", handler: function): void
Fired when a message is deleted from a channel.

If the message data pre-deletion was cached, it will be returned as the second parameter to the handler.

Parameters
- event: MESSAGE_DELETE_BULK | "MESSAGE_DELETE_BULK"
- handler: function
  - - (event: IMessageDeleteBulk) => Promise<unknown>
    - Parameters
      - event: IMessageDeleteBulk
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_REACTION_ADD | "MESSAGE_REACTION_ADD", handler: function): void
Fired when a reaction is added to a message.

Parameters
- event: MESSAGE_REACTION_ADD | "MESSAGE_REACTION_ADD"
- handler: function
  - - (event: IMessageReactionAdd) => Promise<unknown>
    - Parameters
      - event: IMessageReactionAdd
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_REACTION_REMOVE | "MESSAGE_REACTION_REMOVE", handler: function): void
Fired when a user's reaction is removed from a message

Parameters
- event: MESSAGE_REACTION_REMOVE | "MESSAGE_REACTION_REMOVE"
- handler: function
  - - (event: IMessageReactionRemove) => Promise<unknown>
    - Parameters
      - event: IMessageReactionRemove
      Returns Promise<unknown>
Returns void
on(event: MESSAGE_REACTION_REMOVE_ALL | "MESSAGE_REACTION_REMOVE_ALL", handler: function): void
Fired when all reactions on a message are removed at once.

Parameters
- event: MESSAGE_REACTION_REMOVE_ALL | "MESSAGE_REACTION_REMOVE_ALL"
- handler: function
  - - (event: IMessageReactionRemoveAll) => Promise<unknown>
    - Parameters
      - event: IMessageReactionRemoveAll
      Returns Promise<unknown>
Returns void
on(event: GUILD_CREATE | "GUILD_CREATE", handler: function): void
Fired when a bot is invited to a guild, or after the shard serving this guild reconnects to the Discord gateway.

Parameters
- event: GUILD_CREATE | "GUILD_CREATE"
- handler: function
  - - (guild: Guild) => Promise<unknown>
    - Parameters
      - guild: Guild
      Returns Promise<unknown>
Returns void
on(event: GUILD_UPDATE | "GUILD_UPDATE", handler: function): void
Fired when discord.Guild settings are updated, or when a guild's availability changes.

Parameters
- event: GUILD_UPDATE | "GUILD_UPDATE"
- handler: function
  - - (guild: Guild, oldGuild: Guild) => Promise<unknown>
    - Parameters
      - guild: Guild
      - oldGuild: Guild
      Returns Promise<unknown>
Returns void
on(event: GUILD_MEMBER_ADD | "GUILD_MEMBER_ADD", handler: function): void
Fired when a new discord.GuildMember is added to a discord.Guild.

Parameters
- event: GUILD_MEMBER_ADD | "GUILD_MEMBER_ADD"
- handler: function
  - - (member: GuildMember) => Promise<unknown>
    - Parameters
      - member: GuildMember
      Returns Promise<unknown>
Returns void
on(event: GUILD_MEMBER_REMOVE | "GUILD_MEMBER_REMOVE", handler: function): void
Fired when a discord.GuildMember leaves a discord.Guild.

Parameters
- event: GUILD_MEMBER_REMOVE | "GUILD_MEMBER_REMOVE"
- handler: function
  - - (member: IGuildMemberRemove, oldMember: GuildMember) => Promise<unknown>
    - Parameters
      - member: IGuildMemberRemove
      - oldMember: GuildMember
      Returns Promise<unknown>
Returns void
on(event: GUILD_MEMBER_UPDATE | "GUILD_MEMBER_UPDATE", handler: function): void
Fired when one of the following events regarding a discord.GuildMember occur:
- A guild member changes their username, avatar, or discriminator
- A guild member updates their guild nickname
- A role is added or removed from a GuildMember
- The user starts boosting the guild
Parameters
- event: GUILD_MEMBER_UPDATE | "GUILD_MEMBER_UPDATE"
- handler: function
  - - (member: GuildMember, oldMember: GuildMember) => Promise<unknown>
    - Parameters
      - member: GuildMember
      - oldMember: GuildMember
      Returns Promise<unknown>
Returns void
on(event: GUILD_BAN_ADD | "GUILD_BAN_ADD", handler: function): void
Fired when a discord.GuildMember is banned from a discord.Guild.

The discord.GuildBan event parameter will never contain a reason when received via the gateway.

Parameters
- event: GUILD_BAN_ADD | "GUILD_BAN_ADD"
- handler: function
  - - (guildBan: Omit<GuildBan, "reason">) => Promise<unknown>
    - Parameters
      - guildBan: Omit<GuildBan, "reason">
      Returns Promise<unknown>
Returns void
on(event: GUILD_BAN_REMOVE | "GUILD_BAN_REMOVE", handler: function): void
Fired when a discord.GuildMember is unbanned from a discord.Guild.

The discord.GuildBan event parameter will never contain a reason when received via the gateway.

Parameters
- event: GUILD_BAN_REMOVE | "GUILD_BAN_REMOVE"
- handler: function
  - - (guildBan: Omit<GuildBan, "reason">) => Promise<unknown>
    - Parameters
      - guildBan: Omit<GuildBan, "reason">
      Returns Promise<unknown>
Returns void
on(event: GUILD_EMOJIS_UPDATE | "GUILD_EMOJIS_UPDATE", handler: function): void
Fired when the list of discord.Emojis on a guild is updated.

The second parameter in the event contains a structure with the list of emojis previously assigned to this guild.

Parameters
- event: GUILD_EMOJIS_UPDATE | "GUILD_EMOJIS_UPDATE"
- handler: function
  - - (event: IGuildEmojisUpdate, oldEvent: IGuildEmojisUpdate) => Promise<unknown>
    - Parameters
      - event: IGuildEmojisUpdate
      - oldEvent: IGuildEmojisUpdate
      Returns Promise<unknown>
Returns void
on(event: GUILD_INTEGRATIONS_UPDATE | "GUILD_INTEGRATIONS_UPDATE", handler: function): void
Fired when integrations (twitch/youtube subscription sync) are updated for a discord.Guild

Parameters
- event: GUILD_INTEGRATIONS_UPDATE | "GUILD_INTEGRATIONS_UPDATE"
- handler: function
  - - (event: IGuildIntegrationsUpdate) => Promise<unknown>
    - Parameters
      - event: IGuildIntegrationsUpdate
      Returns Promise<unknown>
Returns void
on(event: GUILD_ROLE_CREATE | "GUILD_ROLE_CREATE", handler: function): void
Fired when a discord.Role is created.

Parameters
- event: GUILD_ROLE_CREATE | "GUILD_ROLE_CREATE"
- handler: function
  - - (event: IGuildRoleCreate) => Promise<unknown>
    - Parameters
      - event: IGuildRoleCreate
      Returns Promise<unknown>
Returns void
on(event: GUILD_ROLE_UPDATE | "GUILD_ROLE_UPDATE", handler: function): void
Fired when a discord.Role is created.

Parameters
- event: GUILD_ROLE_UPDATE | "GUILD_ROLE_UPDATE"
- handler: function
  - - (event: IGuildRoleUpdate, oldRole: Role) => Promise<unknown>
    - Parameters
      - event: IGuildRoleUpdate
      - oldRole: Role
      Returns Promise<unknown>
Returns void
on(event: GUILD_ROLE_DELETE | "GUILD_ROLE_DELETE", handler: function): void
Fired when a discord.Role is deleted.

Parameters
- event: GUILD_ROLE_DELETE | "GUILD_ROLE_DELETE"
- handler: function
  - - (event: IGuildRoleDelete, oldRole: Role) => Promise<unknown>
    - Parameters
      - event: IGuildRoleDelete
      - oldRole: Role
      Returns Promise<unknown>
Returns void
on(event: CHANNEL_CREATE | "CHANNEL_CREATE", handler: function): void
Fired when a discord.GuildChannel is created, or a new [[discord.DMChannel]] is opened.

Parameters
- event: CHANNEL_CREATE | "CHANNEL_CREATE"
- handler: function
  - - (channel: AnyChannel) => Promise<unknown>
    - Parameters
      - channel: AnyChannel
      Returns Promise<unknown>
Returns void
on(event: CHANNEL_UPDATE | "CHANNEL_UPDATE", handler: function): void
Fired when a discord.Channel is updated.

Parameters
- event: CHANNEL_UPDATE | "CHANNEL_UPDATE"
- handler: function
  - - (channel: AnyChannel, oldChannel: AnyChannel) => Promise<unknown>
    - Parameters
      - channel: AnyChannel
      - oldChannel: AnyChannel
      Returns Promise<unknown>
Returns void
on(event: CHANNEL_DELETE | "CHANNEL_DELETE", handler: function): void
Fired when a discord.Channel channel is deleted.

Parameters
- event: CHANNEL_DELETE | "CHANNEL_DELETE"
- handler: function
  - - (channel: AnyChannel) => Promise<unknown>
    - Parameters
      - channel: AnyChannel
      Returns Promise<unknown>
Returns void
on(event: CHANNEL_PINS_UPDATE | "CHANNEL_PINS_UPDATE", handler: function): void
Fired when a Message Pin is added or removed from a discord.Channel.

Parameters
- event: CHANNEL_PINS_UPDATE | "CHANNEL_PINS_UPDATE"
- handler: function
  - - (event: IChannelPinsUpdate) => Promise<unknown>
    - Parameters
      - event: IChannelPinsUpdate
      Returns Promise<unknown>
Returns void
on(event: VOICE_STATE_UPDATE | "VOICE_STATE_UPDATE", handler: function): void
Fired when the discord.VoiceState of a discord.GuildMember is updated.

This event is fired when a user connects to voice, switches voice channels, or disconnects from voice. Additionally, this event is fired when a user mutes or deafens, or when server muted/deafened.

Parameters
- event: VOICE_STATE_UPDATE | "VOICE_STATE_UPDATE"
- handler: function
  - - (voiceState: VoiceState, oldVoiceState: VoiceState) => Promise<unknown>
    - Parameters
      - voiceState: VoiceState
      - oldVoiceState: VoiceState
      Returns Promise<unknown>
Returns void
on(event: VOICE_SERVER_UPDATE | "VOICE_SERVER_UPDATE", handler: function): void
Fired when Discord finishes preparing a voice server session for the current bot user.

Note: This SDK currently offers no utilities to send or receive voice data. You can use the token and server address to negotiate the connection yourself.

Parameters
- event: VOICE_SERVER_UPDATE | "VOICE_SERVER_UPDATE"
- handler: function
  - - (event: IVoiceServerUpdate) => Promise<unknown>
    - Parameters
      - event: IVoiceServerUpdate
      Returns Promise<unknown>
Returns void
on(event: TYPING_START | "TYPING_START", handler: function): void
Fired when Discord finishes preparing a voice server session for the current bot user.

Note: This SDK currently offers no utilities to send or receive voice data. You can use the token and server address to negotiate the connection yourself.

Parameters
- event: TYPING_START | "TYPING_START"
- handler: function
  - - (event: ITypingStart) => Promise<unknown>
    - Parameters
      - event: ITypingStart
      Returns Promise<unknown>
Returns void
on(event: WEBHOOKS_UPDATE | "WEBHOOKS_UPDATE", handler: function): void
Fired when Discord finishes preparing a voice server session for the current bot user.

Note: This SDK currently offers no utilities to send or receive voice data. You can use the token and server address to negotiate the connection yourself.

Parameters
- event: WEBHOOKS_UPDATE | "WEBHOOKS_UPDATE"
- handler: function
  - - (event: IWebhooksUpdate) => Promise<unknown>
    - Parameters
      - event: IWebhooksUpdate
      Returns Promise<unknown>
Returns void
on(event: USER_UPDATE | "USER_UPDATE", handler: function): void
Fired when the current bot's discord.User object changes

Parameters
- event: USER_UPDATE | "USER_UPDATE"
- handler: function
  - - (event: User) => Promise<unknown>
    - Parameters
      - event: User
      Returns Promise<unknown>
Returns void

Const registerEventHandler

registerEventHandler: typeof on

Registers a Promise to be resolved when an event of the given discord.Event type is received.

Alias of discord.on.

Note: Event handlers must be statically registered at the start of the script.

Note: Some event handlers pass two parameters to the handlers, usually with a snapshot of the event object before updating the cache. This is useful for finding what changed within objects after on and delete events.

deprecated: Use discord.on instead

Functions

getBotId

getBotId(): Snowflake
Returns the discord.Snowflake ID for the current bot user the deployment is running for.

Returns Snowflake

getBotUser

getBotUser(): Promise<User>
Fetches a discord.User object containing information about the bot user the deployment is running for.

Returns Promise<User>

getChannel

getChannel(channelId: Snowflake): Promise<AnyChannel | null>
Fetches a discord.Channel (or more specific child) object for a given Discord channel id.

Note: You can only fetch channels for the guild your deployment is associated with.

Parameters
- channelId: Snowflake
  
  The channel id (snowflake) you want to fetch channel data for.
Returns Promise<AnyChannel | null>

getGuild

getGuild(guildId: Snowflake): Promise<Guild | null>
Fetches a discord.Guild object for a given Discord server/guild id.

Note: You can only fetch data for the Guild the bot is currently active on.

Parameters
- guildId: Snowflake
  
  The guild id (snowflake) you want to fetch guild data for.
Returns Promise<Guild | null>
getGuild(guildId?: undefined): Promise<Guild>
Fetches a discord.Guild object for the active deployment's guild.

Parameters
- Optional guildId: undefined
  
  The guild id (snowflake) you want to fetch guild data for.
Returns Promise<Guild>

getGuildCategory

getGuildCategory(channelId: Snowflake): Promise<GuildCategory | null>
Fetches a discord.GuildCategory for a given Discord channel id.

If the channel exists, but is not a category channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<GuildCategory | null>

getGuildId

getGuildId(): Snowflake
Returns the discord.Snowflake ID for the discord.Guild this script is active for.

Returns Snowflake

getGuildNewsChannel

getGuildNewsChannel(channelId: Snowflake): Promise<GuildNewsChannel | null>
Fetches a discord.GuildNewsChannel for a given Discord channel id.

If the channel exists, but is not a text channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<GuildNewsChannel | null>

getGuildStageVoiceChannel

getGuildStageVoiceChannel(channelId: Snowflake): Promise<GuildStageVoiceChannel | null>
Fetches a discord.GuildStageVoiceChannel for a given Discord channel id.

If the channel exists, but is not a guild stage voice channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<GuildStageVoiceChannel | null>

getGuildTextChannel

getGuildTextChannel(channelId: Snowflake): Promise<GuildTextChannel | null>
Fetches a discord.GuildTextChannel for a given Discord channel id.

If the channel exists, but is not a guild text text channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<GuildTextChannel | null>

getGuildVoiceChannel

getGuildVoiceChannel(channelId: Snowflake): Promise<GuildVoiceChannel | null>
Fetches a discord.GuildVoiceChannel for a given Discord channel id.

If the channel exists, but is not a guild voice channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<GuildVoiceChannel | null>

getInvite

getInvite(code: string, options?: IGetInviteOptions): Promise<Invite | null>
Fetches a discord.Invite object containing information about an invite on Discord.

Parameters
- code: string
  
  The invite's code (example: 6DbcNPz from https://discord.gg/6DbcNPz)
- Optional options: IGetInviteOptions
Returns Promise<Invite | null>

getTextChannel

getTextChannel(channelId: Snowflake): Promise<ITextChannel | null>
Fetches a discord.ITextChannel for a given Discord channel id.

If the channel exists, but is not a text channel, function will return null.

Parameters
- channelId: Snowflake
Returns Promise<ITextChannel | null>

getUser

getUser(userId: Snowflake): Promise<User | null>
Fetches a discord.User object containing information about a user on Discord.

Parameters
- userId: Snowflake
  
  The user id (snowflake) you want to fetch data for.
Returns Promise<User | null>

Generated using TypeDoc

Results

Namespace

Type

Discord SDK

Event-Based Runtime

Fetching Data

Example: A simple !test command that fetches and returns miscellaneous data.

Making Discord API requests

Index

Namespaces

Enumerations

Classes

Interfaces

Type aliases

Events

Functions

Type aliases

Snowflake

Events

on

Example: Log all messages to the developer console, and respond to "foo" with "bar".

Parameters

event: MESSAGE_CREATE | "MESSAGE_CREATE"

handler: function

Parameters

message: AnyMessage

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_UPDATE | "MESSAGE_UPDATE"

handler: function

Parameters

message: AnyMessage

oldMessage: AnyMessage | null

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_DELETE | "MESSAGE_DELETE"

handler: function

Parameters

event: IMessageDelete

oldMessage: AnyMessage | null

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_DELETE_BULK | "MESSAGE_DELETE_BULK"

handler: function

Parameters

event: IMessageDeleteBulk

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_REACTION_ADD | "MESSAGE_REACTION_ADD"

handler: function

Parameters

event: IMessageReactionAdd

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_REACTION_REMOVE | "MESSAGE_REACTION_REMOVE"

handler: function

Parameters

event: IMessageReactionRemove

Returns Promise<unknown>

Returns void

Parameters

event: MESSAGE_REACTION_REMOVE_ALL | "MESSAGE_REACTION_REMOVE_ALL"

handler: function

Parameters

event: IMessageReactionRemoveAll

Returns Promise<unknown>

Returns void

Parameters

event: GUILD_CREATE | "GUILD_CREATE"

handler: function

Parameters

guild: Guild

Returns Promise<unknown>

Returns void

Parameters

Example: A simple `!test` command that fetches and returns miscellaneous data.