Discord TypeScript SDK

June 4, 2025 ยท View on GitHub

A type-safe SDK for building Node.js Discord bots and applications with the v10 Discord API.

Summary

Discord HTTP API (Preview): The Discord TypeScript SDK exposes the full capabilities of the v10 API, enabling you to build bots and applications that manage servers, channels, messages, interactions, and more.

The SDK is regularly updated to include the latest changes from the OpenAPI spec at https://github.com/discord/discord-api-spec/blob/main/specs/openapi.json

For more information about the API: Discord Developer Documentation

Table of Contents

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @ryan.blunden/discord-sdk

PNPM

pnpm add @ryan.blunden/discord-sdk

Bun

bun add @ryan.blunden/discord-sdk

Yarn

yarn add @ryan.blunden/discord-sdk zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

Model Context Protocol (MCP) Server

This SDK is also an installable MCP server where the various SDK methods are exposed as tools that can be invoked by AI applications.

Node.js v20 or greater is required to run the MCP server from npm.

Claude installation steps

Add the following server definition to your claude_desktop_config.json file:

{
  "mcpServers": {
    "Discord": {
      "command": "npx",
      "args": [
        "-y", "--package", "@ryan.blunden/discord-sdk",
        "--",
        "mcp", "start",
        "--bot-token", "..."
      ]
    }
  }
}
Cursor installation steps

Create a .cursor/mcp.json file in your project root with the following content:

{
  "mcpServers": {
    "Discord": {
      "command": "npx",
      "args": [
        "-y", "--package", "@ryan.blunden/discord-sdk",
        "--",
        "mcp", "start",
        "--bot-token", "..."
      ]
    }
  }
}

You can also run MCP servers as a standalone binary with no additional dependencies. You must pull these binaries from available Github releases:

curl -L -o mcp-server \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

If the repo is a private repo you must add your Github PAT to download a release -H "Authorization: Bearer {GITHUB_PAT}".

{
  "mcpServers": {
    "Todos": {
      "command": "./DOWNLOAD/PATH/mcp-server",
      "args": [
        "start"
      ]
    }
  }
}

For a full list of server arguments, run:

npx -y --package @ryan.blunden/discord-sdk -- mcp start --help

For a full list of tools, see MCP_SERVER_TOOLS.md.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord({
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  const result = await discord.applications.getMe();

  console.log(result);
}

run();

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

NameTypeSchemeEnvironment Variable
botTokenapiKeyAPI keyDISCORD_BOT_TOKEN

To authenticate with the API the botToken parameter must be set when initializing the SDK client instance. For example:

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord({
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  const result = await discord.applications.getMe();

  console.log(result);
}

run();

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord();

async function run() {
  const result = await discord.applications.uploadAttachment({}, {
    applicationId: "<value>",
    requestBody: {
      file: "<value>",
    },
  });

  console.log(result);
}

run();

Available Resources and Operations

Available methods

applicationCommands

  • list - Fetch all global commands for your application.
  • bulkSet - Takes a list of application commands, overwriting the existing global command list for this application.
  • create - Create a new global command. New global commands will be available in all guilds after 1 hour.
  • get - Fetch a global command for your application.
  • delete - Delete a global command.
  • update - Edit a global command. Updates will be available in all guilds after 1 hour.
  • listGuild - Fetch all guild commands for your application for a specific guild.
  • bulkSetGuild - Takes a list of application commands, overwriting the existing command list for this application for the targeted guild.
  • createGuild - Create a new guild command. New guild commands will be available in the guild immediately.
  • listGuildPermissions - Fetches command permissions for all commands for your application in a guild.
  • getGuild - Fetch a guild command for your application.
  • deleteGuild - Delete a guild command.
  • updateGuild - Edit a guild command. Updates for guild commands will be available immediately.
  • getGuildPermissions - Fetches command permissions for a specific command for your application in a guild.
  • setGuildPermissions - Edits command permissions for a specific command for your application in a guild.

applicationRoleConnectionMetadata

  • list - Returns a list of application role connection metadata objects for the given application.
  • update - Updates and returns a list of application role connection metadata objects for the given application. An application can have a maximum of 5 metadata records.
  • deleteUserConnection - Deletes the application role connection for the user.

applications

  • getMe - Returns the application object associated with the requesting bot user.
  • updateSelf - Edit properties of the app associated with the requesting bot user. Only properties that are passed will be updated. Returns the updated application object on success.
  • get - Returns information about a specific application.
  • update - Updates an application. Returns the updated application object on success.
  • getActivityInstance - Returns a serialized activity instance, if it exists. Useful for preventing unwanted activity sessions.
  • uploadAttachment - Uploads an attachment for an application.
  • getGateway - Returns an object with a single valid WSS URL, which the client can use for connecting to Discord.
  • getBotGateway - Returns an object with the same information as Get Gateway, plus a shards key, containing the recommended number of shards to connect with.
  • getOAuth2Authorization - Returns info about the current authorization.
  • getOAuth2Me - Returns the OAuth2 application object associated with the requesting bot user.
  • getPublicKeys - Returns a list of public keys used for verifying signatures.
  • getOpenIDConnectUserInfo - Returns the user info for the current user.
  • partnerSDKUnmergeProvisionalAccount - Unmerges a provisional account.
  • partnerSDKToken - Gets a token for the partner SDK.

auditLogs

  • list - Returns an audit log object for the guild. Requires the VIEW_AUDIT_LOG permission.

autoModeration

  • listRules - Get a list of all rules currently configured for the guild. Returns a list of auto moderation rule objects for the given guild. This endpoint requires the MANAGE_GUILD permission.
  • createRule - Create a new rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Create Gateway event.
  • getRule - Get a single rule. Returns an auto moderation rule object. This endpoint requires the MANAGE_GUILD permission.
  • deleteRule - Delete a rule. Returns a 204 on success. Fires an Auto Moderation Rule Delete Gateway event.
  • updateRule - Modify an existing rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Update Gateway event.

channels

  • get - Returns a channel object for the given channel ID.
  • delete - Delete a channel, or close a private message. Requires the MANAGE_CHANNELS permission for the guild, or MANAGE_THREADS if the channel is a thread. Returns a channel object on success. Fires a Channel Delete Gateway event (or Thread Delete if the channel was a thread).
  • update - Update a channel's settings. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters.
  • follow - Follow an Announcement Channel to send messages to a target channel. Requires the MANAGE_WEBHOOKS permission in the target channel. Returns a followed channel object. Fires a Webhooks Update Gateway event for the target channel.
  • listInvites - Returns a list of invite objects (with invite metadata) for the channel.
  • createInvite - Create a new invite object for the channel.
  • startThreadFromMessage - Creates a new thread from an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create and a Message Update Gateway event.
  • setPermissionOverwrite - Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Channel Update Gateway event.
  • deletePermissionOverwrite - Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Channel Update Gateway event.
  • listPinnedMessages - Returns all pinned messages in the channel as an array of message objects.
  • pinMessage - Pin a message in a channel. Requires the MANAGE_MESSAGES permission. Returns a 204 empty response on success. Fires a Channel Pins Update Gateway event.
  • unpinMessage - Unpin a message in a channel. Requires the MANAGE_MESSAGES permission. Returns a 204 empty response on success. Fires a Channel Pins Update Gateway event.
  • addGroupDMRecipient - Adds a recipient to a Group DM using their access token.
  • removeGroupDMRecipient - Removes a recipient from a Group DM.
  • listThreadMembers - Returns array of thread member objects that are members of the thread.
  • joinThread - Adds the current user to a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update and a Thread Create Gateway event.
  • leaveThread - Removes the current user from a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.
  • getThreadMember - Returns a thread member object for the specified user if they are a member of the thread, returns a 404 response otherwise.
  • addThreadMember - Adds another member to a thread. Requires the ability to send messages in the thread. Also requires the thread is not archived. Returns a 204 empty response if the member is successfully added or was already a member of the thread. Fires a Thread Members Update Gateway event.
  • removeThreadMember - Removes another member from a thread. Requires the MANAGE_THREADS permission, or the creator of the thread if it is a PRIVATE_THREAD. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.
  • startThread - Creates a new thread that is not connected to an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create Gateway event.
  • listPrivateArchivedThreads - Returns archived threads in the channel that are of type PRIVATE_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires both the READ_MESSAGE_HISTORY and MANAGE_THREADS permissions.
  • listPublicArchivedThreads - Returns archived threads in the channel that are public. When called on a GUILD_TEXT channel, returns threads of type PUBLIC_THREAD. When called on a GUILD_ANNOUNCEMENT channel returns threads of type ANNOUNCEMENT_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires the READ_MESSAGE_HISTORY permission.
  • searchThreads - Search for threads in a channel.
  • triggerTypingIndicator - Post a typing indicator for the specified channel, which expires after 10 seconds. Returns a 204 empty response on success. Fires a Typing Start Gateway event.
  • listJoinedPrivateArchivedThreads - Returns archived threads in the channel that are of type PRIVATE_THREAD, and the user has joined. Threads are ordered by their id, in descending order. Requires the READ_MESSAGE_HISTORY permission.

emoji

  • listApplicationEmojis - Returns an object containing a list of emoji objects for the given application under the items key. Includes a user object for the team member that uploaded the emoji from the app's settings, or for the bot user if uploaded using the API.
  • createApplicationEmoji - Create a new emoji for the application. Returns the new emoji object on success.
  • getApplicationEmoji - Returns an emoji object for the given application and emoji IDs. Includes the user field.
  • deleteApplicationEmoji - Delete the given emoji. Returns 204 No Content on success.
  • updateApplicationEmoji - Modify the given emoji. Returns the updated emoji object on success.
  • listGuildEmojis - Returns a list of emoji objects for the given guild. Includes user fields if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • createGuildEmoji - Create a new emoji for the guild. Requires the CREATE_GUILD_EXPRESSIONS permission. Returns the new emoji object on success. Fires a Guild Emojis Update Gateway event.
  • getGuildEmoji - Returns an emoji object for the given guild and emoji IDs. Includes the user field if the bot has the MANAGE_GUILD_EXPRESSIONS permission, or if the bot created the emoji and has the the CREATE_GUILD_EXPRESSIONS permission.
  • deleteGuildEmoji - Delete the given emoji. For emojis created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other emojis, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns 204 No Content on success. Fires a Guild Emojis Update Gateway event.
  • updateGuildEmoji - Modify the given emoji. For emojis created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other emojis, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns the updated emoji object on success. Fires a Guild Emojis Update Gateway event.

entitlements

  • list - Returns all entitlements for a given app, active and expired.
  • createTest - Creates a test entitlement to a given SKU for a given guild or user. Discord will act as though that user or guild has entitlement to your premium offering. This endpoint returns a partial entitlement object.
  • get - Returns an entitlement.
  • deleteTest - Deletes a currently-active test entitlement. Discord will act as though that user or guild no longer has entitlement to your premium offering. Returns 204 No Content on success.
  • consume - For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed. The entitlement will have consumed: true when using List Entitlements. Returns a 204 No Content on success.

guilds

  • create - Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event.
  • get - Returns the guild object for the given id. If with_counts is set to true, this endpoint will also return approximate_member_count and approximate_presence_count for the guild.
  • delete - Delete a guild permanently. User must be owner. Returns 204 No Content on success. Fires a Guild Delete Gateway event.
  • update - Modify a guild's settings. Requires the MANAGE_GUILD permission. Returns the updated guild object on success. Fires a Guild Update Gateway event.
  • listBans - Returns a list of ban objects for the users banned from this guild. Requires the BAN_MEMBERS permission.
  • getBan - Returns a ban object for the given user or a 404 not found if the ban cannot be found. Requires the BAN_MEMBERS permission.
  • createBan - Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Ban Add Gateway event.
  • removeBan - Remove the ban for a user. Requires the BAN_MEMBERS permissions. Returns a 204 empty response on success. Fires a Guild Ban Remove Gateway event.
  • bulkBan - Ban up to 200 users from a guild, and optionally delete previous messages sent by the banned users. Requires both the BAN_MEMBERS and MANAGE_GUILD permissions. Returns a 200 response on success, including the fields banned_users with the IDs of the banned users and failed_users with IDs that could not be banned or were already banned.
  • listChannels - Returns a list of guild channel objects. Does not include threads.
  • createChannel - Create a new channel object for the guild. Requires the MANAGE_CHANNELS permission. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting MANAGE_ROLES permission in channels is only possible for guild administrators. Returns the new channel object on success. Fires a Channel Create Gateway event.
  • updateChannelPositions - Modify the positions of a set of channel objects for the guild. Requires MANAGE_CHANNELS permission. Returns a 204 empty response on success. Fires multiple Channel Update Gateway events.
  • listIntegrations - Returns a list of integration objects for the guild. Requires the MANAGE_GUILD permission.
  • deleteIntegration - Delete the attached integration object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Delete Gateway events.
  • listInvites - Returns a list of invite objects (with invite metadata) for the guild. Requires the MANAGE_GUILD permission.
  • listMembers - Returns a list of guild member objects that are members of the guild.
  • updateCurrentMember - Modifies the current member in a guild. Returns a 200 with the updated member object on success. Fires a Guild Member Update Gateway event.
  • searchMembers - Returns a list of guild member objects whose username or nickname starts with a provided string.
  • getMember - Returns a guild member object for the specified user.
  • addMember - Adds a user to the guild, provided you have a valid oauth2 access token for the user with the guilds.join scope. Returns a 201 Created with the guild member as the body, or 204 No Content if the user is already a member of the guild. Fires a Guild Member Add Gateway event.
  • removeMember - Remove a member from a guild. Requires KICK_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Member Remove Gateway event.
  • updateMember - Modify attributes of a guild member. Returns a 200 OK with the guild member as the body. Fires a Guild Member Update Gateway event. If the channel_id is set to null, this will force the target user to be disconnected from voice.
  • addMemberRole - Adds a role to a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
  • removeMemberRole - Removes a role from a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
  • setMfaLevel - Modify a guild's MFA level. Requires guild ownership. Returns the updated level on success. Fires a Guild Update Gateway event.
  • getOnboarding - Returns the Onboarding object for the guild.
  • updateOnboarding - Modifies the onboarding configuration of the guild. Returns a 200 with the Onboarding object for the guild. Requires the MANAGE_GUILD and MANAGE_ROLES permissions.
  • getPreview - Returns the guild preview object for the given id. If the user is not in the guild, then the guild must be discoverable.
  • previewPrune - Returns an object with one pruned key indicating the number of members that would be removed in a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions.
  • prune - Begin a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions. Returns an object with one pruned key indicating the number of members that were removed in the prune operation. Fires multiple Guild Member Remove Gateway events.
  • listVoiceRegions - Returns a list of voice region objects for the guild. Unlike the similar /voice route, this returns VIP servers when the guild is VIP-enabled.
  • listRoles - Returns a list of role objects for the guild.
  • createRole - Create a new role for the guild. Requires the MANAGE_ROLES permission. Returns the new role object on success. Fires a Guild Role Create Gateway event. All JSON params are optional.
  • updateRolePositions - Modify the positions of a set of role objects for the guild. Requires the MANAGE_ROLES permission. Returns a list of all of the guild's role objects on success. Fires multiple Guild Role Update Gateway events.
  • getRole - Returns a role object for the specified role.
  • deleteRole - Delete a guild role. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Role Delete Gateway event.
  • updateRole - Modify a guild role. Requires the MANAGE_ROLES permission. Returns the updated role on success. Fires a Guild Role Update Gateway event.
  • listActiveThreads - Returns all active threads in the guild, including public and private threads. Threads are ordered by their id, in descending order.
  • getVanityUrl - Returns a partial invite object for guilds with that feature enabled. Requires the MANAGE_GUILD permission. code will be null if a vanity url for the guild is not set.
  • getWelcomeScreen - Returns the Welcome Screen object for the guild. If the welcome screen is not enabled, the MANAGE_GUILD permission is required.
  • updateWelcomeScreen - Modify the guild's Welcome Screen. Requires the MANAGE_GUILD permission. Returns the updated Welcome Screen object. May fire a Guild Update Gateway event.
  • getWidgetSettings - Returns a guild widget settings object. Requires the MANAGE_GUILD permission.
  • updateWidgetSettings - Modify a guild widget settings object for the guild. All attributes may be passed in with JSON and modified. Requires the MANAGE_GUILD permission. Returns the updated guild widget settings object. Fires a Guild Update Gateway event.
  • getWidget - Returns the widget for the guild. Fires an Invite Create Gateway event when an invite channel is defined and a new Invite is generated.
  • getWidgetPng - Returns a PNG image widget for the guild. Requires no permissions or authentication.

guildScheduledEvents

  • list - Returns a list of guild scheduled event objects for the given guild.
  • create - Create a guild scheduled event in the guild. Returns a guild scheduled event object on success. Fires a Guild Scheduled Event Create Gateway event.
  • get - Get a guild scheduled event. Returns a guild scheduled event object on success.
  • delete - Delete a guild scheduled event. Returns a 204 on success. Fires a Guild Scheduled Event Delete Gateway event.
  • update - Modify a guild scheduled event. Returns the modified guild scheduled event object on success. Fires a Guild Scheduled Event Update Gateway event.
  • getUsers - Get a list of guild scheduled event users subscribed to a guild scheduled event. Returns a list of guild scheduled event user objects on success. Guild member data, if it exists, is included if the with_member query parameter is set.

guildTemplates

  • get - Returns a guild template object for the given code.
  • createGuild - Create a new guild based on a template. Returns a guild object on success. Fires a Guild Create Gateway event.
  • getNewMemberWelcome - Returns the welcome screen object for the guild.
  • list - Returns an array of guild template objects. Requires the MANAGE_GUILD permission.
  • create - Creates a template for the guild. Requires the MANAGE_GUILD permission. Returns the created guild template object on success.
  • sync - Syncs the template to the guild's current state. Requires the MANAGE_GUILD permission. Returns the guild template object on success.
  • delete - Deletes the template. Requires the MANAGE_GUILD permission. Returns the deleted guild template object on success.
  • update - Modifies the template's metadata. Requires the MANAGE_GUILD permission. Returns the guild template object on success.

invites

  • get - Returns an invite object for the given code.
  • delete - Delete an invite. Requires the MANAGE_CHANNELS permission on the channel this invite belongs to, or MANAGE_GUILD to remove any invite across the guild. Returns an invite object on success.

lobbies

  • createOrJoin - Creates a new lobby or joins an existing one. Returns a lobby object on success.
  • create - Creates a new lobby. Returns a lobby object on success.
  • get - Returns the lobby object for the given id.
  • update - Updates a lobby. Returns a lobby object on success.
  • connectToChannel - Connects a lobby to a channel.
  • leave - Removes the current user from the specified lobby. It is safe to call this even if the user is no longer a member of the lobby, but will fail if the lobby does not exist.
  • addMember - Adds a user to a lobby.
  • removeMember - Removes a user from a lobby.
  • sendMessage - Sends a message to the lobby.

messages

  • list - Returns the messages for a channel. If operating on a guild channel, this endpoint requires the VIEW_CHANNEL permission to be present on the current user.
  • createJson - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • createForm - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • createMultipart - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • bulkDelete - Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the MANAGE_MESSAGES permission.
  • get - Returns a specific message in the channel. If operating on a guild channel, this endpoint requires the READ_MESSAGE_HISTORY permission to be present on the current user.
  • delete - Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the MANAGE_MESSAGES permission.
  • updateJson - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • updateForm - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • updateMultipart - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • crosspost - Crosspost a message in an Announcement Channel to following channels. This endpoint requires the SEND_MESSAGES permission, if the current user sent the message, or additionally the MANAGE_MESSAGES permission, for all other messages, to be present for the current user.
  • deleteAllReactions - Deletes all reactions on a message. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
  • listReactionsByEmoji - Get a list of users that reacted with a specific emoji.
  • deleteAllReactionsForEmoji - Deletes all the reactions for a given emoji on a message. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
  • createReaction - Create a reaction for the message. This endpoint requires the READ_MESSAGE_HISTORY permission to be present on the current user.
  • deleteOwnReaction - Delete a reaction the current user has made for the message. Returns a 204 empty response on success.
  • deleteUserReaction - Deletes another user's reaction. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.

polls

  • getAnswerVoters - Get a list of users that voted for a specific answer in a poll.
  • expire - Immediately ends the poll. You cannot end polls from other users. Returns a message object. Fires a Message Update Gateway event.

soundboards

stageInstances

  • create - Creates a new Stage instance associated to a Stage channel. Returns that Stage instance. Fires a Stage Instance Create Gateway event. Requires the user to be a moderator of the Stage channel.
  • get - Gets the stage instance associated with the Stage channel, if it exists.
  • delete - Deletes the Stage instance. Returns 204 No Content. Fires a Stage Instance Delete Gateway event. Requires the user to be a moderator of the Stage channel.
  • update - Updates fields of an existing Stage instance. Returns the updated Stage instance. Fires a Stage Instance Update Gateway event. Requires the user to be a moderator of the Stage channel.

stickers

  • listGuildStickers - Returns an array of sticker objects for the given guild. Includes user fields if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • createGuildSticker - Create a new sticker for the guild. Send a multipart/form-data body. Requires the CREATE_GUILD_EXPRESSIONS permission. Returns the new sticker object on success. Fires a Guild Stickers Update Gateway event.
  • getGuildSticker - Returns a sticker object for the given guild and sticker IDs. Includes the user field if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • deleteGuildSticker - Delete the given sticker. For stickers created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other stickers, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns 204 No Content on success. Fires a Guild Stickers Update Gateway event.
  • updateGuildSticker - Modify the given sticker. For stickers created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other stickers, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns the updated sticker object on success. Fires a Guild Stickers Update Gateway event.
  • listPacks - Returns a list of available sticker packs.
  • getPack - Returns a sticker pack object for the given sticker pack ID.
  • get - Returns a sticker object for the given sticker ID.

users

  • getCurrent - Returns the user object of the requester's account. For OAuth2, this requires the identify scope, which will return the object without an email, and optionally the email scope, which returns the object with an email if the user has one.
  • updateCurrent - Modify the requester's user account settings. Returns a user object on success. Fires a User Update Gateway event.
  • getApplicationRoleConnection - Returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.
  • updateApplicationRoleConnection - Updates and returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.
  • createDM - Create a new DM channel with a user. Returns a DM channel object (if one already exists, it will be returned instead).
  • listConnections - Returns a list of connection objects. Requires the connections OAuth2 scope.
  • listGuilds - Returns a list of partial guild objects the current user is a member of. For OAuth2, requires the guilds scope.
  • leaveGuild - Leave a guild. Returns a 204 empty response on success. Fires a Guild Delete Gateway event and a Guild Member Remove Gateway event.
  • getGuildMember - Returns a guild member object for the current user. Requires the guilds.members.read OAuth2 scope.
  • get - Returns a user object for a given user ID.

voice

  • getCurrentUserState - Returns the current user's voice state in the guild.
  • updateCurrentUserState - Updates the current user's voice state. Returns 204 No Content on success. Fires a Voice State Update Gateway event.
  • getUserState - Returns the specified user's voice state in the guild.
  • updateUserState - Updates another user's voice state. Fires a Voice State Update Gateway event.
  • listRegions - Returns an array of voice region objects that can be used when setting a voice or stage channel's rtc_region.

webhooks

  • listForChannel - Returns a list of channel webhook objects. Requires the MANAGE_WEBHOOKS permission.
  • create - Creates a new webhook and returns a webhook object on success. Requires the MANAGE_WEBHOOKS permission. Fires a Webhooks Update Gateway event.
  • listForGuild - Returns a list of guild webhook objects. Requires the MANAGE_WEBHOOKS permission.
  • get - Returns the new webhook object for the given id.
  • delete - Delete a webhook permanently. Requires the MANAGE_WEBHOOKS permission. Returns a 204 No Content response on success. Fires a Webhooks Update Gateway event.
  • update - Modify a webhook. Requires the MANAGE_WEBHOOKS permission. Returns the updated webhook object on success. Fires a Webhooks Update Gateway event.
  • getWithToken - Same as above, except this call does not require authentication and returns no user in the webhook object.
  • deleteWithToken - Same as above, except this call does not require authentication.
  • updateWithToken - Same as above, except this call does not require authentication, does not accept a channel_id parameter in the body, and does not return a user in the webhook object.
  • executeGithub - Add a new webhook to your GitHub repo (in the repo's settings), and use this endpoint as the "Payload URL."
  • getOriginalMessage - Returns the initial webhook message.
  • deleteOriginalMessage - Deletes the initial webhook message.
  • updateOriginalMessageJson - Edits the initial webhook message.
  • updateOriginalMessageForm - Edits the initial webhook message.
  • updateOriginalMessageMultipart - Edits the initial webhook message.
  • getMessage - Returns a previously-sent webhook message from the same token. Returns a message object on success.
  • deleteMessage - Deletes a message that was created by the webhook. Returns a 204 No Content response on success.
  • updateMessageJson - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • updateMessageForm - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • updateMessageMultipart - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • executeSlack - Refer to Slack's documentation for more information. We do not support Slack's channel, icon_emoji, mrkdwn, or mrkdwn_in properties.

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

Available standalone functions
  • applicationCommandsBulkSet - Takes a list of application commands, overwriting the existing global command list for this application.
  • applicationCommandsBulkSetGuild - Takes a list of application commands, overwriting the existing command list for this application for the targeted guild.
  • applicationCommandsCreate - Create a new global command. New global commands will be available in all guilds after 1 hour.
  • applicationCommandsCreateGuild - Create a new guild command. New guild commands will be available in the guild immediately.
  • applicationCommandsDelete - Delete a global command.
  • applicationCommandsDeleteGuild - Delete a guild command.
  • applicationCommandsGet - Fetch a global command for your application.
  • applicationCommandsGetGuild - Fetch a guild command for your application.
  • applicationCommandsGetGuildPermissions - Fetches command permissions for a specific command for your application in a guild.
  • applicationCommandsList - Fetch all global commands for your application.
  • applicationCommandsListGuild - Fetch all guild commands for your application for a specific guild.
  • applicationCommandsListGuildPermissions - Fetches command permissions for all commands for your application in a guild.
  • applicationCommandsSetGuildPermissions - Edits command permissions for a specific command for your application in a guild.
  • applicationCommandsUpdate - Edit a global command. Updates will be available in all guilds after 1 hour.
  • applicationCommandsUpdateGuild - Edit a guild command. Updates for guild commands will be available immediately.
  • applicationRoleConnectionMetadataDeleteUserConnection - Deletes the application role connection for the user.
  • applicationRoleConnectionMetadataList - Returns a list of application role connection metadata objects for the given application.
  • applicationRoleConnectionMetadataUpdate - Updates and returns a list of application role connection metadata objects for the given application. An application can have a maximum of 5 metadata records.
  • applicationsGet - Returns information about a specific application.
  • applicationsGetActivityInstance - Returns a serialized activity instance, if it exists. Useful for preventing unwanted activity sessions.
  • applicationsGetBotGateway - Returns an object with the same information as Get Gateway, plus a shards key, containing the recommended number of shards to connect with.
  • applicationsGetGateway - Returns an object with a single valid WSS URL, which the client can use for connecting to Discord.
  • applicationsGetMe - Returns the application object associated with the requesting bot user.
  • applicationsGetOAuth2Authorization - Returns info about the current authorization.
  • applicationsGetOAuth2Me - Returns the OAuth2 application object associated with the requesting bot user.
  • applicationsGetOpenIDConnectUserInfo - Returns the user info for the current user.
  • applicationsGetPublicKeys - Returns a list of public keys used for verifying signatures.
  • applicationsPartnerSDKToken - Gets a token for the partner SDK.
  • applicationsPartnerSDKUnmergeProvisionalAccount - Unmerges a provisional account.
  • applicationsUpdate - Updates an application. Returns the updated application object on success.
  • applicationsUpdateSelf - Edit properties of the app associated with the requesting bot user. Only properties that are passed will be updated. Returns the updated application object on success.
  • applicationsUploadAttachment - Uploads an attachment for an application.
  • auditLogsList - Returns an audit log object for the guild. Requires the VIEW_AUDIT_LOG permission.
  • autoModerationCreateRule - Create a new rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Create Gateway event.
  • autoModerationDeleteRule - Delete a rule. Returns a 204 on success. Fires an Auto Moderation Rule Delete Gateway event.
  • autoModerationGetRule - Get a single rule. Returns an auto moderation rule object. This endpoint requires the MANAGE_GUILD permission.
  • autoModerationListRules - Get a list of all rules currently configured for the guild. Returns a list of auto moderation rule objects for the given guild. This endpoint requires the MANAGE_GUILD permission.
  • autoModerationUpdateRule - Modify an existing rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Update Gateway event.
  • channelsAddGroupDMRecipient - Adds a recipient to a Group DM using their access token.
  • channelsAddThreadMember - Adds another member to a thread. Requires the ability to send messages in the thread. Also requires the thread is not archived. Returns a 204 empty response if the member is successfully added or was already a member of the thread. Fires a Thread Members Update Gateway event.
  • channelsCreateInvite - Create a new invite object for the channel.
  • channelsDelete - Delete a channel, or close a private message. Requires the MANAGE_CHANNELS permission for the guild, or MANAGE_THREADS if the channel is a thread. Returns a channel object on success. Fires a Channel Delete Gateway event (or Thread Delete if the channel was a thread).
  • channelsDeletePermissionOverwrite - Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Channel Update Gateway event.
  • channelsFollow - Follow an Announcement Channel to send messages to a target channel. Requires the MANAGE_WEBHOOKS permission in the target channel. Returns a followed channel object. Fires a Webhooks Update Gateway event for the target channel.
  • channelsGet - Returns a channel object for the given channel ID.
  • channelsGetThreadMember - Returns a thread member object for the specified user if they are a member of the thread, returns a 404 response otherwise.
  • channelsJoinThread - Adds the current user to a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update and a Thread Create Gateway event.
  • channelsLeaveThread - Removes the current user from a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.
  • channelsListInvites - Returns a list of invite objects (with invite metadata) for the channel.
  • channelsListJoinedPrivateArchivedThreads - Returns archived threads in the channel that are of type PRIVATE_THREAD, and the user has joined. Threads are ordered by their id, in descending order. Requires the READ_MESSAGE_HISTORY permission.
  • channelsListPinnedMessages - Returns all pinned messages in the channel as an array of message objects.
  • channelsListPrivateArchivedThreads - Returns archived threads in the channel that are of type PRIVATE_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires both the READ_MESSAGE_HISTORY and MANAGE_THREADS permissions.
  • channelsListPublicArchivedThreads - Returns archived threads in the channel that are public. When called on a GUILD_TEXT channel, returns threads of type PUBLIC_THREAD. When called on a GUILD_ANNOUNCEMENT channel returns threads of type ANNOUNCEMENT_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires the READ_MESSAGE_HISTORY permission.
  • channelsListThreadMembers - Returns array of thread member objects that are members of the thread.
  • channelsPinMessage - Pin a message in a channel. Requires the MANAGE_MESSAGES permission. Returns a 204 empty response on success. Fires a Channel Pins Update Gateway event.
  • channelsRemoveGroupDMRecipient - Removes a recipient from a Group DM.
  • channelsRemoveThreadMember - Removes another member from a thread. Requires the MANAGE_THREADS permission, or the creator of the thread if it is a PRIVATE_THREAD. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.
  • channelsSearchThreads - Search for threads in a channel.
  • channelsSetPermissionOverwrite - Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Channel Update Gateway event.
  • channelsStartThread - Creates a new thread that is not connected to an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create Gateway event.
  • channelsStartThreadFromMessage - Creates a new thread from an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create and a Message Update Gateway event.
  • channelsTriggerTypingIndicator - Post a typing indicator for the specified channel, which expires after 10 seconds. Returns a 204 empty response on success. Fires a Typing Start Gateway event.
  • channelsUnpinMessage - Unpin a message in a channel. Requires the MANAGE_MESSAGES permission. Returns a 204 empty response on success. Fires a Channel Pins Update Gateway event.
  • channelsUpdate - Update a channel's settings. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters.
  • emojiCreateApplicationEmoji - Create a new emoji for the application. Returns the new emoji object on success.
  • emojiCreateGuildEmoji - Create a new emoji for the guild. Requires the CREATE_GUILD_EXPRESSIONS permission. Returns the new emoji object on success. Fires a Guild Emojis Update Gateway event.
  • emojiDeleteApplicationEmoji - Delete the given emoji. Returns 204 No Content on success.
  • emojiDeleteGuildEmoji - Delete the given emoji. For emojis created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other emojis, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns 204 No Content on success. Fires a Guild Emojis Update Gateway event.
  • emojiGetApplicationEmoji - Returns an emoji object for the given application and emoji IDs. Includes the user field.
  • emojiGetGuildEmoji - Returns an emoji object for the given guild and emoji IDs. Includes the user field if the bot has the MANAGE_GUILD_EXPRESSIONS permission, or if the bot created the emoji and has the the CREATE_GUILD_EXPRESSIONS permission.
  • emojiListApplicationEmojis - Returns an object containing a list of emoji objects for the given application under the items key. Includes a user object for the team member that uploaded the emoji from the app's settings, or for the bot user if uploaded using the API.
  • emojiListGuildEmojis - Returns a list of emoji objects for the given guild. Includes user fields if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • emojiUpdateApplicationEmoji - Modify the given emoji. Returns the updated emoji object on success.
  • emojiUpdateGuildEmoji - Modify the given emoji. For emojis created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other emojis, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns the updated emoji object on success. Fires a Guild Emojis Update Gateway event.
  • entitlementsConsume - For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed. The entitlement will have consumed: true when using List Entitlements. Returns a 204 No Content on success.
  • entitlementsCreateTest - Creates a test entitlement to a given SKU for a given guild or user. Discord will act as though that user or guild has entitlement to your premium offering. This endpoint returns a partial entitlement object.
  • entitlementsDeleteTest - Deletes a currently-active test entitlement. Discord will act as though that user or guild no longer has entitlement to your premium offering. Returns 204 No Content on success.
  • entitlementsGet - Returns an entitlement.
  • entitlementsList - Returns all entitlements for a given app, active and expired.
  • guildsAddMember - Adds a user to the guild, provided you have a valid oauth2 access token for the user with the guilds.join scope. Returns a 201 Created with the guild member as the body, or 204 No Content if the user is already a member of the guild. Fires a Guild Member Add Gateway event.
  • guildsAddMemberRole - Adds a role to a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
  • guildsBulkBan - Ban up to 200 users from a guild, and optionally delete previous messages sent by the banned users. Requires both the BAN_MEMBERS and MANAGE_GUILD permissions. Returns a 200 response on success, including the fields banned_users with the IDs of the banned users and failed_users with IDs that could not be banned or were already banned.
  • guildScheduledEventsCreate - Create a guild scheduled event in the guild. Returns a guild scheduled event object on success. Fires a Guild Scheduled Event Create Gateway event.
  • guildScheduledEventsDelete - Delete a guild scheduled event. Returns a 204 on success. Fires a Guild Scheduled Event Delete Gateway event.
  • guildScheduledEventsGet - Get a guild scheduled event. Returns a guild scheduled event object on success.
  • guildScheduledEventsGetUsers - Get a list of guild scheduled event users subscribed to a guild scheduled event. Returns a list of guild scheduled event user objects on success. Guild member data, if it exists, is included if the with_member query parameter is set.
  • guildScheduledEventsList - Returns a list of guild scheduled event objects for the given guild.
  • guildScheduledEventsUpdate - Modify a guild scheduled event. Returns the modified guild scheduled event object on success. Fires a Guild Scheduled Event Update Gateway event.
  • guildsCreate - Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event.
  • guildsCreateBan - Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Ban Add Gateway event.
  • guildsCreateChannel - Create a new channel object for the guild. Requires the MANAGE_CHANNELS permission. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting MANAGE_ROLES permission in channels is only possible for guild administrators. Returns the new channel object on success. Fires a Channel Create Gateway event.
  • guildsCreateRole - Create a new role for the guild. Requires the MANAGE_ROLES permission. Returns the new role object on success. Fires a Guild Role Create Gateway event. All JSON params are optional.
  • guildsDelete - Delete a guild permanently. User must be owner. Returns 204 No Content on success. Fires a Guild Delete Gateway event.
  • guildsDeleteIntegration - Delete the attached integration object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Delete Gateway events.
  • guildsDeleteRole - Delete a guild role. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Role Delete Gateway event.
  • guildsGet - Returns the guild object for the given id. If with_counts is set to true, this endpoint will also return approximate_member_count and approximate_presence_count for the guild.
  • guildsGetBan - Returns a ban object for the given user or a 404 not found if the ban cannot be found. Requires the BAN_MEMBERS permission.
  • guildsGetMember - Returns a guild member object for the specified user.
  • guildsGetOnboarding - Returns the Onboarding object for the guild.
  • guildsGetPreview - Returns the guild preview object for the given id. If the user is not in the guild, then the guild must be discoverable.
  • guildsGetRole - Returns a role object for the specified role.
  • guildsGetVanityUrl - Returns a partial invite object for guilds with that feature enabled. Requires the MANAGE_GUILD permission. code will be null if a vanity url for the guild is not set.
  • guildsGetWelcomeScreen - Returns the Welcome Screen object for the guild. If the welcome screen is not enabled, the MANAGE_GUILD permission is required.
  • guildsGetWidget - Returns the widget for the guild. Fires an Invite Create Gateway event when an invite channel is defined and a new Invite is generated.
  • guildsGetWidgetPng - Returns a PNG image widget for the guild. Requires no permissions or authentication.
  • guildsGetWidgetSettings - Returns a guild widget settings object. Requires the MANAGE_GUILD permission.
  • guildsListActiveThreads - Returns all active threads in the guild, including public and private threads. Threads are ordered by their id, in descending order.
  • guildsListBans - Returns a list of ban objects for the users banned from this guild. Requires the BAN_MEMBERS permission.
  • guildsListChannels - Returns a list of guild channel objects. Does not include threads.
  • guildsListIntegrations - Returns a list of integration objects for the guild. Requires the MANAGE_GUILD permission.
  • guildsListInvites - Returns a list of invite objects (with invite metadata) for the guild. Requires the MANAGE_GUILD permission.
  • guildsListMembers - Returns a list of guild member objects that are members of the guild.
  • guildsListRoles - Returns a list of role objects for the guild.
  • guildsListVoiceRegions - Returns a list of voice region objects for the guild. Unlike the similar /voice route, this returns VIP servers when the guild is VIP-enabled.
  • guildsPreviewPrune - Returns an object with one pruned key indicating the number of members that would be removed in a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions.
  • guildsPrune - Begin a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions. Returns an object with one pruned key indicating the number of members that were removed in the prune operation. Fires multiple Guild Member Remove Gateway events.
  • guildsRemoveBan - Remove the ban for a user. Requires the BAN_MEMBERS permissions. Returns a 204 empty response on success. Fires a Guild Ban Remove Gateway event.
  • guildsRemoveMember - Remove a member from a guild. Requires KICK_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Member Remove Gateway event.
  • guildsRemoveMemberRole - Removes a role from a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
  • guildsSearchMembers - Returns a list of guild member objects whose username or nickname starts with a provided string.
  • guildsSetMfaLevel - Modify a guild's MFA level. Requires guild ownership. Returns the updated level on success. Fires a Guild Update Gateway event.
  • guildsUpdate - Modify a guild's settings. Requires the MANAGE_GUILD permission. Returns the updated guild object on success. Fires a Guild Update Gateway event.
  • guildsUpdateChannelPositions - Modify the positions of a set of channel objects for the guild. Requires MANAGE_CHANNELS permission. Returns a 204 empty response on success. Fires multiple Channel Update Gateway events.
  • guildsUpdateCurrentMember - Modifies the current member in a guild. Returns a 200 with the updated member object on success. Fires a Guild Member Update Gateway event.
  • guildsUpdateMember - Modify attributes of a guild member. Returns a 200 OK with the guild member as the body. Fires a Guild Member Update Gateway event. If the channel_id is set to null, this will force the target user to be disconnected from voice.
  • guildsUpdateOnboarding - Modifies the onboarding configuration of the guild. Returns a 200 with the Onboarding object for the guild. Requires the MANAGE_GUILD and MANAGE_ROLES permissions.
  • guildsUpdateRole - Modify a guild role. Requires the MANAGE_ROLES permission. Returns the updated role on success. Fires a Guild Role Update Gateway event.
  • guildsUpdateRolePositions - Modify the positions of a set of role objects for the guild. Requires the MANAGE_ROLES permission. Returns a list of all of the guild's role objects on success. Fires multiple Guild Role Update Gateway events.
  • guildsUpdateWelcomeScreen - Modify the guild's Welcome Screen. Requires the MANAGE_GUILD permission. Returns the updated Welcome Screen object. May fire a Guild Update Gateway event.
  • guildsUpdateWidgetSettings - Modify a guild widget settings object for the guild. All attributes may be passed in with JSON and modified. Requires the MANAGE_GUILD permission. Returns the updated guild widget settings object. Fires a Guild Update Gateway event.
  • guildTemplatesCreate - Creates a template for the guild. Requires the MANAGE_GUILD permission. Returns the created guild template object on success.
  • guildTemplatesCreateGuild - Create a new guild based on a template. Returns a guild object on success. Fires a Guild Create Gateway event.
  • guildTemplatesDelete - Deletes the template. Requires the MANAGE_GUILD permission. Returns the deleted guild template object on success.
  • guildTemplatesGet - Returns a guild template object for the given code.
  • guildTemplatesGetNewMemberWelcome - Returns the welcome screen object for the guild.
  • guildTemplatesList - Returns an array of guild template objects. Requires the MANAGE_GUILD permission.
  • guildTemplatesSync - Syncs the template to the guild's current state. Requires the MANAGE_GUILD permission. Returns the guild template object on success.
  • guildTemplatesUpdate - Modifies the template's metadata. Requires the MANAGE_GUILD permission. Returns the guild template object on success.
  • invitesDelete - Delete an invite. Requires the MANAGE_CHANNELS permission on the channel this invite belongs to, or MANAGE_GUILD to remove any invite across the guild. Returns an invite object on success.
  • invitesGet - Returns an invite object for the given code.
  • lobbiesAddMember - Adds a user to a lobby.
  • lobbiesConnectToChannel - Connects a lobby to a channel.
  • lobbiesCreate - Creates a new lobby. Returns a lobby object on success.
  • lobbiesCreateOrJoin - Creates a new lobby or joins an existing one. Returns a lobby object on success.
  • lobbiesGet - Returns the lobby object for the given id.
  • lobbiesLeave - Removes the current user from the specified lobby. It is safe to call this even if the user is no longer a member of the lobby, but will fail if the lobby does not exist.
  • lobbiesRemoveMember - Removes a user from a lobby.
  • lobbiesSendMessage - Sends a message to the lobby.
  • lobbiesUpdate - Updates a lobby. Returns a lobby object on success.
  • messagesBulkDelete - Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the MANAGE_MESSAGES permission.
  • messagesCreateForm - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • messagesCreateJson - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • messagesCreateMultipart - Post a message to a guild text or DM channel. If operating on a guild channel, this endpoint requires the SEND_MESSAGES permission to be present on the current user.
  • messagesCreateReaction - Create a reaction for the message. This endpoint requires the READ_MESSAGE_HISTORY permission to be present on the current user.
  • messagesCrosspost - Crosspost a message in an Announcement Channel to following channels. This endpoint requires the SEND_MESSAGES permission, if the current user sent the message, or additionally the MANAGE_MESSAGES permission, for all other messages, to be present for the current user.
  • messagesDelete - Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the MANAGE_MESSAGES permission.
  • messagesDeleteAllReactions - Deletes all reactions on a message. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
  • messagesDeleteAllReactionsForEmoji - Deletes all the reactions for a given emoji on a message. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
  • messagesDeleteOwnReaction - Delete a reaction the current user has made for the message. Returns a 204 empty response on success.
  • messagesDeleteUserReaction - Deletes another user's reaction. This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
  • messagesGet - Returns a specific message in the channel. If operating on a guild channel, this endpoint requires the READ_MESSAGE_HISTORY permission to be present on the current user.
  • messagesList - Returns the messages for a channel. If operating on a guild channel, this endpoint requires the VIEW_CHANNEL permission to be present on the current user.
  • messagesListReactionsByEmoji - Get a list of users that reacted with a specific emoji.
  • messagesUpdateForm - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • messagesUpdateJson - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • messagesUpdateMultipart - Edit a previously sent message. The fields content, embeds, and flags can be edited by the original message author. Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
  • pollsExpire - Immediately ends the poll. You cannot end polls from other users. Returns a message object. Fires a Message Update Gateway event.
  • pollsGetAnswerVoters - Get a list of users that voted for a specific answer in a poll.
  • soundboardsCreateGuildSoundboardSound - Create a new soundboard sound for the guild. Returns the new soundboard sound object on success.
  • soundboardsDeleteGuildSoundboardSound - Delete a soundboard sound from a guild. Returns 204 No Content on success.
  • soundboardsGetGuildSoundboardSound - Returns a soundboard sound object for the given guild and sound IDs.
  • soundboardsGetSoundboardDefaultSounds - Returns a list of the default sounds available in the soundboard.
  • soundboardsListGuildSoundboardSounds - Returns a list of soundboard sound objects for the given guild.
  • soundboardsSendSoundboardSound - Sends a soundboard sound to a channel.
  • soundboardsUpdateGuildSoundboardSound - Update a soundboard sound in a guild. Returns the updated soundboard sound object on success.
  • stageInstancesCreate - Creates a new Stage instance associated to a Stage channel. Returns that Stage instance. Fires a Stage Instance Create Gateway event. Requires the user to be a moderator of the Stage channel.
  • stageInstancesDelete - Deletes the Stage instance. Returns 204 No Content. Fires a Stage Instance Delete Gateway event. Requires the user to be a moderator of the Stage channel.
  • stageInstancesGet - Gets the stage instance associated with the Stage channel, if it exists.
  • stageInstancesUpdate - Updates fields of an existing Stage instance. Returns the updated Stage instance. Fires a Stage Instance Update Gateway event. Requires the user to be a moderator of the Stage channel.
  • stickersCreateGuildSticker - Create a new sticker for the guild. Send a multipart/form-data body. Requires the CREATE_GUILD_EXPRESSIONS permission. Returns the new sticker object on success. Fires a Guild Stickers Update Gateway event.
  • stickersDeleteGuildSticker - Delete the given sticker. For stickers created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other stickers, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns 204 No Content on success. Fires a Guild Stickers Update Gateway event.
  • stickersGet - Returns a sticker object for the given sticker ID.
  • stickersGetGuildSticker - Returns a sticker object for the given guild and sticker IDs. Includes the user field if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • stickersGetPack - Returns a sticker pack object for the given sticker pack ID.
  • stickersListGuildStickers - Returns an array of sticker objects for the given guild. Includes user fields if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.
  • stickersListPacks - Returns a list of available sticker packs.
  • stickersUpdateGuildSticker - Modify the given sticker. For stickers created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other stickers, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns the updated sticker object on success. Fires a Guild Stickers Update Gateway event.
  • usersCreateDM - Create a new DM channel with a user. Returns a DM channel object (if one already exists, it will be returned instead).
  • usersGet - Returns a user object for a given user ID.
  • usersGetApplicationRoleConnection - Returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.
  • usersGetCurrent - Returns the user object of the requester's account. For OAuth2, this requires the identify scope, which will return the object without an email, and optionally the email scope, which returns the object with an email if the user has one.
  • usersGetGuildMember - Returns a guild member object for the current user. Requires the guilds.members.read OAuth2 scope.
  • usersLeaveGuild - Leave a guild. Returns a 204 empty response on success. Fires a Guild Delete Gateway event and a Guild Member Remove Gateway event.
  • usersListConnections - Returns a list of connection objects. Requires the connections OAuth2 scope.
  • usersListGuilds - Returns a list of partial guild objects the current user is a member of. For OAuth2, requires the guilds scope.
  • usersUpdateApplicationRoleConnection - Updates and returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.
  • usersUpdateCurrent - Modify the requester's user account settings. Returns a user object on success. Fires a User Update Gateway event.
  • voiceGetCurrentUserState - Returns the current user's voice state in the guild.
  • voiceGetUserState - Returns the specified user's voice state in the guild.
  • voiceListRegions - Returns an array of voice region objects that can be used when setting a voice or stage channel's rtc_region.
  • voiceUpdateCurrentUserState - Updates the current user's voice state. Returns 204 No Content on success. Fires a Voice State Update Gateway event.
  • voiceUpdateUserState - Updates another user's voice state. Fires a Voice State Update Gateway event.
  • webhooksCreate - Creates a new webhook and returns a webhook object on success. Requires the MANAGE_WEBHOOKS permission. Fires a Webhooks Update Gateway event.
  • webhooksDelete - Delete a webhook permanently. Requires the MANAGE_WEBHOOKS permission. Returns a 204 No Content response on success. Fires a Webhooks Update Gateway event.
  • webhooksDeleteMessage - Deletes a message that was created by the webhook. Returns a 204 No Content response on success.
  • webhooksDeleteOriginalMessage - Deletes the initial webhook message.
  • webhooksDeleteWithToken - Same as above, except this call does not require authentication.
  • webhooksExecuteGithub - Add a new webhook to your GitHub repo (in the repo's settings), and use this endpoint as the "Payload URL."
  • webhooksExecuteSlack - Refer to Slack's documentation for more information. We do not support Slack's channel, icon_emoji, mrkdwn, or mrkdwn_in properties.
  • webhooksGet - Returns the new webhook object for the given id.
  • webhooksGetMessage - Returns a previously-sent webhook message from the same token. Returns a message object on success.
  • webhooksGetOriginalMessage - Returns the initial webhook message.
  • webhooksGetWithToken - Same as above, except this call does not require authentication and returns no user in the webhook object.
  • webhooksListForChannel - Returns a list of channel webhook objects. Requires the MANAGE_WEBHOOKS permission.
  • webhooksListForGuild - Returns a list of guild webhook objects. Requires the MANAGE_WEBHOOKS permission.
  • webhooksUpdate - Modify a webhook. Requires the MANAGE_WEBHOOKS permission. Returns the updated webhook object on success. Fires a Webhooks Update Gateway event.
  • webhooksUpdateMessageForm - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • webhooksUpdateMessageJson - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • webhooksUpdateMessageMultipart - Edits a previously-sent webhook message from the same token. Returns a message object on success.
  • webhooksUpdateOriginalMessageForm - Edits the initial webhook message.
  • webhooksUpdateOriginalMessageJson - Edits the initial webhook message.
  • webhooksUpdateOriginalMessageMultipart - Edits the initial webhook message.
  • webhooksUpdateWithToken - Same as above, except this call does not require authentication, does not accept a channel_id parameter in the body, and does not return a user in the webhook object.

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord({
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  const result = await discord.applications.getMe({
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  const result = await discord.applications.getMe();

  console.log(result);
}

run();

Error Handling

This table shows properties which are common on error classes. For full details see error classes.

PropertyTypeDescription
error.namestringError class name eg APIError
error.messagestringError message
error.statusCodenumberHTTP status code eg 404
error.contentTypestringHTTP content type eg application/json
error.bodystringHTTP body. Can be empty string if no body is returned.
error.rawResponseResponseRaw HTTP response. Access to headers and more.
error.data$Optional. Some errors may contain structured data. See Error Classes.

Example

import { Discord } from "@ryan.blunden/discord-sdk";
import * as errors from "@ryan.blunden/discord-sdk/models/errors";

const discord = new Discord({
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  try {
    const result = await discord.applications.getMe();

    console.log(result);
  } catch (error) {
    // Depending on the method different errors may be thrown
    if (error instanceof errors.ErrorResponse) {
      console.log(error.message);
      console.log(error.data$.code); // number
      console.log(error.data$.message); // string
      console.log(error.data$.errors); // components.ErrorDetails
    }

    // Fallback error class, if no other more specific error class is matched
    if (error instanceof errors.APIError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.rawResponse.headers);
    }
  }
}

run();

Error Classes

  • ErrorResponse: Errors object returned by the Discord API. Status code 4XX.
  • APIError: The fallback error class, if no other more specific error class is matched.
  • SDKValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. This can also be thrown for invalid method arguments. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.
  • Network errors:
    • ConnectionError: HTTP client was unable to make a request to a server.
    • RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
    • RequestAbortedError: HTTP request was aborted by the client.
    • InvalidRequestError: Any input used to create a request is invalid.
    • UnexpectedClientError: Unrecognised or unexpected error.

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

import { Discord } from "@ryan.blunden/discord-sdk";

const discord = new Discord({
  serverURL: "https://discord.com/api/v10",
  botToken: process.env["DISCORD_BOT_TOKEN"] ?? "",
});

async function run() {
  const result = await discord.applications.getMe();

  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { Discord } from "@ryan.blunden/discord-sdk";
import { HTTPClient } from "@ryan.blunden/discord-sdk/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Discord({ httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

Warning

Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { Discord } from "@ryan.blunden/discord-sdk";

const sdk = new Discord({ debugLogger: console });

You can also enable a default debug logger by setting an environment variable DISCORD_DEBUG to true.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy