Thread permissions have been updated and simplified:
- "Use Public Threads" is now "Create Public Threads", which allows users to create threads in a channel, even if they cannot send messages in that channel.
- "Use Private Threads" is now "Create Private Threads", which allows users to create threads in a channel, even if they cannot send messages in that channel.
A new permission has also been added:
- "Send Messages in Threads", which allows users to send a message in a thread. The "Send Messages" permission has no effect in threads: users must have "Send Messages in Threads" to send a message in a thread. This allows for setups where a user can participate in a thread, but cannot send a message in the parent channel (like a thread on an announcement post).
User commands and message commands are now live! These commands appear on context menus for users and messages, with more to come in the future.
Context menu commands are a type of application command. The "Slash Commands" documentation page has been renamed to "Application Commands" and split out by type to show this.
Select Menus are now part of the components API! They're the greatest thing since the invention of buttons yesterday. Select menus allow you to offer users a choice of one or many options in a friendly UI-based way.
Select menus can be used like other message components. Learn all the specifics in the documentation.
Message routes now accept an embeds array in addition to the existing embed field. Bots can now send up to 10 embeds per message, to be consistent with webhook behavior. The existing embed field is considered deprecated and will be removed in the next API version.
Message components are now available with our first two components: a layout-based ActionRow and...buttons!
You can now include buttons on messages sent by your app, whether they're bot messages or responses to interactions. Learn more about message components.
The addition of message components means new fields and response types:
- An optional
componentsfield has been added to the message object - New response types
6and7have been added for interaction responses, valid only for component-based interactions
API v9 is now available.
API v9 includes support for threads, an upcoming feature. Older API versions will not receive any Gateway Events for threads, so it is important to update soon! We've prepared a migration guide to help make the upgrade process very straightforward.
This documentation is being published early so bots can have at least two months to upgrade before threads launch.
Additionally, API v9 also removes the /channels/:id/messages/:id/suppress-embeds route.
Need to keep some of your commands safe from prying eyes, or only available to the right people? Commands now support command permissions!
You can enable or disable a command (guild or global) for a specific user or role in a guild. For now, users will still be able to see the commands, but won't be able to use them.
New routes have been added to support this functionality:
GET Guild Application Command PermissionsGET Application Command PermissionsPUT Application Command Permissions
A default_permission field has also been added to the ApplicationCommand model. This field allows you to disable commands for everyone in a guild by default, if you prefer to make some of your commands an opt-in experience.
There have been reports that sessions have higher frequency of errors when starting if a bot has joined too many guilds (the gateway connection times out). To account for this we have lowered the requirement for large bot sharding down to 150,000 guilds in order to improve reliability.
Changes to interaction response types have been made to support better designs for application commands:
- Type
2Acknowledgehas been deprecated - Type
3ChannelMessagehas been deprecated - Type
5AcknowledgeWithSourcehas been renamed toDeferredChannelMessageWithSource
These deprecated types will be removed and break on April 9, 2021.
Additionally, flags has been documented on InteractionApplicationCommandCallbackData. Setting flags to 64 will make the interaction response ephemeral.
Slash Commands are now supported in DMs with bots. Due to this change, some of the fields on the Interaction object have been made optional. Newly optional fields don't reflect any behavior changes in Slash Commands within guilds; they are to support commands in the context of a DM only.
Permission overwrites in the guild channel creation endpoint are now validated against the permissions your bot has in the guild. Permission overwrites specified in the request body when creating guild channels will now require your bot to also have the permissions being applied. Setting MANAGE_ROLES permission in channel overwrites is only possible for guild administrators or users with MANAGE_ROLES as a permission overwrite in the channel.
Slash Commands are here! There's a lot to cover, so go check out specific documentation under Slash Commands.
Slash Commands include some new features for webhooks as well:
- Webhooks can now update previously-sent messages from the same webhook using Edit Webhook Message and Delete Webhook Message
This PR also documents the application field on the READY gateway event, which is a partial application object containing id and flags.
Inline Replies have been added to our documentation. They behave differently in v6 and v8, so be cautious in your implementation:
- Inline replies are type
19in v8, but remain type0in v6 - You can now add a
message_referenceon message create to create a reply - A new field
referenced_messagehas been added to the Message Object - A new field
replied_userhas been added to the Allowed Mentions Object - Message Create gateway event is guaranteed to have a
referenced_messageif the message created is a reply. Otherwise, that field is not guaranteed.
Stickers are now documented as part of the message object.
The v6 gateway now applies the restrictions for gateway intents. This means the new chunking limitations are now in effect, regardless of intents being used. See Request Guild Members for further details. Additionally, if privileged intents are not enabled in the application dashboard the bot will not receive the events for those intents.
All other intents are always enabled by default unless specified otherwise by the identify payload. We have made a support article to explain some of the changes and resulting issues with more details: Gateway Update FAQ
We've introduced API and Gateway v8! Changes are noted throughout the documentation, and you can also read this commit in our docs repo for a full diff.
The changes are:
- API and Gateway v8 are now available. v6 is still the default for the time being.
- Gateway Intents are now required
- Removed
guild_subscriptionsin identify in favor of Gateway Intents. - All permissions have been converted to strings-serialized numbers. As such,
permissions_new,allow_new, anddeny_newhave been removed - The
gamefield has been removed. If you need a direct replacement, you can instead reference the first element ofactivities - Channel Permission Overwrite
types are now numbers (0 and 1) instead of strings ("role" and "member"). However due to a current technical constraint, they are string-serialized numbers in audit logoptions. embed_enabledandembed_channel_idhave been removed. Usewidget_enabledandwidget_channel_idinstead.- Form body errors have been improved to include more helpful messaging on validation. See more here
- The
Retry-Afterheader value andretry_afterbody value is now based in seconds instead of milliseconds (e.g.123means 123 seconds) - The
X-RateLimit-Precisionheader is no longer respected.X-RateLimit-ResetandX-RateLimit-Reset-Afterare always returned at millisecond precision (e.g.123.456instead of124) - Bots no longer receive Channel Create Gateway Event for DMs
delete-message-daysis no longer available. Usedelete_message_days.- Removed
roles,premium_since, andnickfrom Presence Update Gateway Event - Removed some integration object fields for Discord application integrations
- Removed
include_applicationsfrom Get Guild Integrations. Application integrations are always included. - The following deprecated routes have been removed for better naming conventions:
Removed in favor of /guilds/<guild_id>/widget:
/guilds/<guild_id>/embed
Removed in favor of /guilds/<guild_id>/widget.json:
/servers/<guild_id>/embed.json/servers/<guild_id>/widget.json/guilds/<guild_id>/embed.json
Removed in favor of /guilds/<guild_id>/widget.png:
/guilds/<guild_id>/embed.png
Removed in favor of /channels/<channel_id>/messages/bulk-delete:
/channels/<channel_id>/messages/bulk_delete/
Removed in favor of /invites/<code>/:
/invite/<code>/
Documented permissions_new, allow_new, and deny_new as string-serialized permission bitfields.
The legacy mention behavior for bots is now removed, and granular control of mentions should use the Allowed Mentions API moving forwards.
The Guild Members Chunk gateway event now contains two properties: chunk_index and chunk_count. These values can be used to keep track of how many events you have left to receive in response to a Request Guild Members command.
We've added a way to specify mentions in a more granular form. This change also begins the start of a 60 day deprecation cycle on legacy mention behavior. Read more:
We've added a new endpoint for deleting all reactions of a specific emoji from a message, as well as some new invite and reaction gateway events. Read more:
The Spectate functionality of Rich Presence no longer requires whitelisting or approval.
We've added documentation around a brand new feature: Gateway Intents! Gateway Intents are a great way to specify which events you want to receive from our gateway. Go on, save yourself some bandwidth and CPU usage.
Using Intents will change the behavior of some existing events and commands, so please refer to:
- Guild Create
- Request Guild Members
- Guild Member Add
- Guild Member Remove
- Guild Member Update
- Presence Update
- List Guild Members
Updated our IP discovery message. The old message is deprecated and will be removed in the future.
Fixed a bug from the 2.5.5 release that caused network handshakes to fail, resulting in no networking data being sent. The networking manager and integrated lobby networking should be full operational again after updating.
We've shipped some updates to the GameSDK, including support for Linux as well as the IL2CPP backend system for Unity. These changes also fixed a bug in the SetUserAchievement() method.
Get the latest at the top of the Getting Started documentation. If you're looking for help interacting with the GameSDK or want to report a bug, join us on the official Discord.
News Channels are now changed to Announcement Channels. Developer License owners will continue to get access to them (both existing and new). Underlying channel type (GUILD_NEWS = 5) remains the same.
You can now get more precise rate limit reset times, via a new request header. Check out the rate limits documentation for more information.
You can now use Bot tokens for authorization headers against the HTTP API for Achievements.
Additional information around Teams has been added to both the API and the documentation. The Teams page now includes information about the team and team member objects. Additionally, the Get Current Application Information endpoint now returns a team object if that application belongs to a team. That documentation has also been updated to includes fields that were missing for applications that are games sold on Discord.
Additional information has been documented to support Server Nitro Boosting. This includes the addition of a few message types, as well as some new fields on guilds. Please note that this feature is currently under experimentation, and these fields may be subject to change.
The Discord-RPC implementation of Rich Presence has been deprecated in favor of Discord's new GameSDK. If you're interested in using Rich Presence, please read our SDK Starter Guide and check out the relevant functions in the Activity Manager.
The Invite Object now includes two additional fields, target_user and target_user_type.
Ask to Join no longer requires approval or whitelisting to use. You are welcome to create in-game UI, but all Ask to Join requests are also now handled by the Discord overlay.
There have also been some small additions to the Rich Presence SDK. The previously undocumented UpdateHandlers() function is now documented.
Dispatch documentation around store listings has been removed. Store pages for the Discord Store are now managed entirely within the Developer Portal.
The User object now includes two new additional fields, premium_type and flags. These can be used to know the Nitro status of a user, or determine which HypeSquad house a user is in.
The documentation has been updated to correctly note that the private_channels field in the Ready should be an empty array, as well as the response from /users/@me/channels for a bot user. This change has been in effect for a long time, but the documentation was not updated.
We released server changes that allow guilds to represent an incomplete state of the member list in our clients, which results in inaccurate member lists and online counts over RPC. These fields are now deprecated and will now return an empty members array and an online count of 0 moving forward.
Additional activity and application fields—as well as corresponding object documentation—have been added to the Message object in support of our newly-released Spotify integration and previous Rich Presence enhancements.
The Get Guild Emoji response now also includes a user object if the emoji was added by a user.
The Accept Invite endpoint is deprecated starting today, and will be discontinued on March 23, 2018. The Add Guild Member endpoint should be used in its place.
Additional sharding requirements and information for bots in over 100,000 guilds has been added. This requires a small change in numbers of shards for affected bots. See the documentation for more information.
Rich Presence is now live and available for all developers! Rich Presence allows developers to closely integrate with Discord in a number of new, cool ways like:
- Showing more information about a user's current game in their profile
- Allowing users to post invitations to join their party or spectate their game in chat
- Displaying "Spectate" and "Ask to Join" buttons on users' profiles
For more information, check out our Rich Presence site. To get started on development, read the docs!
API and Gateway versions below v6 are now discontinued after being previously deprecated. Version 6 is now the default API and Gateway version. Attempting to use a version below 6 will result in an error.
Changes have been made throughout the documentation to reflect the addition of channel categories to Discord. These includes an additional field—parent_id—to the base channel object and a new channel category example.
Emoji endpoints have been added to the API. Bots can now manage guild emojis to their robo-hearts' content!
The type field in the activity object for Gateway Status Update and Presence Update payloads is no longer optional when the activity object is not null.
After today, we are changing how default channels function. The "default" channel for a given user is now the channel with the highest position that their permissions allow them to see. New guilds will no longer have a default channel with the same id as the guild. Existing guilds will not have their #general channel id changed. It is possible, if permissions are set in such a way, that a user will not have a default channel in a guild.
We saw a use case in many servers where the previously-default #general channel was being repurposed as an announcement-only, non-writable channel for new members by using bots to clear the entire message history. Now, that channel can simply be deleted and re-created with the desired permissions. This change also allows dynamic default channels for users based on permissions.
We are also rolling out a change in conjunction that will allow Discord to remember your last-visited channel in a guild across sessions. Newly-joined users will be directed to the guild's default channel on first join; existing members will return to whichever channel they last visited.
Audit logs are here! Well, they've been here all along, but now we've got documentation about them. Check it out, but remember: with great power comes great responsibility.