discord / discord-api-docs

Official Discord API Documentation

Discord Official API Documentation

This repo contains the official Discord API documentation, which can be viewed online HERE. Before submitting pull-requests, please remember to fully read the Contributing guidelines.

This repository reflects the Discord API as it is meant to be accessed by third-party applications. It omits features and capabilities that are not generally available, or are not fully supported for third-party usage.

We welcome your contributions!

• Issue tracker: Discord API bugs
• Discussions: Discord API feature and improvement requests
• Pull Requests: See Contributing.md

Markdown Syntax

This repository uses special markdown syntax that helps style the resulting web version of the documentation.

H6 Headings

H6 headings should be used above tables and code blocks to properly label them.

Linking

Links between docs can be achieved by using a hash symbol (#), plus the markdown file name, plus a slash, and finally the dash-separated anchor. For instance, to link to the above H6 heading section:

[Links to README.md H6](#README/h6-headings)

Alert Boxes

Alert boxes are achieved by using a block quote that has one of 'warn', 'danger' or 'info' on the first line.

Need some help?

Here are some Discord servers that can help you out with everything Discord API:

The Official Discord Developers server has plenty of help channels with knowledgeable people and Discord's developers to get you help with something you need, and get updates straight from the developers. However do keep in mind this is a purely on-topic server. If you are looking for a community, join the server below.

The Unofficial Discord API server is a common hangout for library and bot developers alike. It's a great starting point for those looking to dive in and learn bot-creation with the Discord API.

License

Except as otherwise noted, the Discord API Documentation and other content in this repository is licensed under the Creative Commons Attribution-ShareAlike 4.0 License (see LICENSE), and code samples in this repository are licensed under the MIT License (see LICENSE-CODE). These licenses do not grant you rights to use any of Discord’s trademarks or other brand features. Please see the Discord Developer Terms of Service for more information about use of Discord’s brand features and APIs.

discord-api-docs's Issues

[API] MEMBER_KICKED event

It would be convienent if there was a MEMBER_KICKED event to separate people who left at will from people you kicked if they want their bot to know for sure without having to use that bot to do the kicking.

Now another thing is to also add in MEMBER_LEFT which would only be called if they left at their will and will not be called any other time. This would be great as there is a event for bans and unbans why not for kicked/left being just like bans/unbans?

I think this would be more convient for end users and bot makers. I think everyone would benefit from this if it is done. Also it is much easier to know and I dont have to half ass ON_MEMBER_REMOVE and try to get the bans when the bot cant really.
So in a sense it makes it impossible currently to separate kicked from left at will without the bot kicking them itself.

Missing Info: API URL

It's random, but there's nowhere in the docs that mention the API URL.

[API] Voice Channel user limit

You can now set a user limit on a channel by passing user_limit in the request body when creating or updating a channel.

The user limit should be an integer between 0 and 99, where 0 refers to no limit, and every other number less than or equal to 99 refers to the user cap for the channel.

Note: if you have MOVE_MEMBERS permission in a channel, you can bypass the user limit.

[Libraries] Rate limit compliant

We're going to start delisting API libraries that are not properly implementing rate limits. The whole "get 429ed and then retry" method doesn't work that well, as it seems this is incredibly prone to getting the bot in a cascading failure mode that just spams the API server. We don't want to keep having to ban bots every day who are getting stuck in these loops (it's becoming a bit of a problem) - so we are going to start discouraging the use of libraries (either by delisting them - or putting a disclaimer/warning until the author implements this feature properly) that do not properly throttle requests. This means that the client should be aware that it is being rate limited on a given method, and not attempt to send any requests during a period that it should know would be immediately rate limited. Please refer to our new docs on Rate Limiting.

Below is a list of libraries that are known to do queuing/throttling properly:

• Discord.Net
• DiscordSharp
• dscord
• Discordgo
• Discord4J
• Javacord
• JDA
• Discordia
• litcord
• discordie
• discord.io
• discord.js
• Eris
• DiscordPHP
• discord.py
• discordrb
• discord-rs
• DiscordUnity
• disco
• discordcr

Library authors, please comment here letting me know if your lib does implement these properly, and perhaps with a link to the source code so we can take a quick look and make sure it looks right.

Question about doc making

Hello,

First of all I would like to congratulate you for the job you're doing, that's really cool.
I started using discord API for developers and I really like the way you designed it.

I would like to know if you used a specific framework to generate pages like this one : https://discordapp.com/developers/docs/resources/channel

Or it's all self-made ? I've saw you're using React.js, is there any add-on for react to do things like that ?

Thank you,
Best regards

[API] Bot MFA/Two Factor

On June 17th, 2016 - bots will start considering their owner's two factor status on servers with two factor authentication enabled, meaning, they will be unable to perform functions which require "elevated" permissions functions on servers with two-factor authentication enabled until the application owner turns on two factor on their account.

As an example:

Server A turns on two factor. This means that all regular users will be required to enable two factor on their accounts before they can perform functions requiring "elevated" permissions. Bots obviously can't have two factor, so we continue to allow bots to perform these functions on these servers. However, after this change, we will consider the two factor status of the account that owns the bot to check whether to allow the bot to perform these actions on a server with two factor enabled.

If your bot does not require these permissions, or the server does not have two factor on, your bot is unaffected. If the owner account does not have two factor enabled, and the bot tries to perform a function which requires "elevated" permissions, it will not be able to until the owner account turns on 2fa. Other than that, the bot should still be able to do everything else that does not require the "elevated" permissions.

The following are considered "elevated" permissions:

• KICK_MEMBERS
• BAN_MEMBERS
• MANAGE_CHANNELS
• MANAGE_GUILD
• MANAGE_ROLES
• MANAGE_MESSAGES
• ADMINISTRATOR

For more info about how two factor works on Discord, check out the blog post: https://blog.discordapp.com/keeping-discord-safe-and-sound/ and the support article: https://support.discordapp.com/hc/en-us/articles/219576828

X-RateLimit-Reset and Retry-After Ratelimit headers

After hitting the ratelimit a few times through the ratelimit-compliant RequestBuffer in the Discord4J Java API, I visited the docs for ratelimits in search for an answer -- why was I hitting the ratelimit. I found @hydrabolt commenting about the use of X-RateLimit-Reset instead of Retry-After. (#108) As @night doesn't see a need to replace X-RateLimit-Reset with Retry-After, may I politely ask you guys to implement both headers please?

Edit 2: As @satom99 pointed out, although there is a Date header, it would be better to also include the Retry-After header, as recommended on RFC-6585

[OAuth2] Missing documentation for grant type

Looks like there isn't any documentation on which grant type I should use to get a token back from /token with the code received from /authorize.

As tested, offline is not supported, full_stack is not a thing, application is not a thing and authorization_code is not a thing too (invalid grant type).

Denying "Read Messages" Permission doesn't hide channel if granted with a role other than everyone

Permission	Value	Description
READ_MESSAGES	0x00000400	Allows reading messages in a channel. The channel will not appear for users without this permission

is inaccurate. Someone who has had this permission revoked will still have the channel appear if they have any role that is granted this permission.

[API] Missing documentation for user connection objects

USER.md references connection objects, which are not documented and given a dead link

[ReadState] Deprecation for Bots

We're disabling read states entirely for bots. This shouldn't break any APIs (yet - read on for more).

Planned:

• The read state array in the READY packet will return an empty array for bots
• The message_ack endpoint will return 401 if you are trying to ack a message on a bot account.
• Sending messages will no longer implicitly self ack the channel the message was sent in.

Breaking Changes:

• We're going to remove read_state entirely from the ready packet in a few weeks. Update your libraries to not depend on this!

OK Libraries

• Discord.net
• Discord Sharp
• Go - DiscordAPI
• Go - DiscordGo
• Discord4j
• Javacord
• JDA
• Discord.io
• Discord.js
• Discordie
• DiscordPHP
• Discord.py
• Discordrb
• Discord.rs

TODO: Document this.

Voice Data Packet is incorrect

See: https://discordapp.com/developers/docs/topics/voice-connections#voice-data-packet

The voice packet is a 70 byte payload that begins with a 4 byte big-endian packed unsigned integer, which represents the clients 'ssrc'. The rest of the bytes in the payload are Opus audio data.

This is incorrect, it should have the same fields as the nonce fields at the bottom of the page AFAIK.

I'll PR it when I have time if it's not done already.

[API] Add Endpoint to separate kicks from bans for servers when bots cant separate bans due to lack of permissions.

Yes, they can use the on_member_removed event. But it fails if they do not have permsions to get the bans list and ignore it if they are in the list to get the kicks and it proves to be a issue. I would also thing this event is also reiggered when they leave at will so it would be nice if there was a endpoint/event to just get the kicks for any and valid logging to know if they broke any rules of servers or not as not too many people can remember things like that. (yes a bot can do it if they use the bot to kick the person but, whet if they have 1 bot doing the actual kicking and another one logging things to a channel? That would prove this issue and a lack of the API that I believe needs added. (Not to mention makes it easier for noobs to make nice bots similar to BooBot for example).

Ready event wrong properties

The documentation states the Ready event has the following properties:

• v
• user
• private_channels
• guilds
• read_state
• session_id

The ones I receive have the following ones:

• v
• user
• session_id
• relationships
• private_channels
• presences
• heartbeat_interval
• guilds
• [_trace]

Overall a few are missing and too much.

x-ratelimit-remaining is off-by-one

you'll get remaining: 0 twice in a row before you get rate limited, and if you use 1 ticket, it says you have 8 remaining, although you should have 9 left (when total # of tickets is 10)

Clarify what extra fields `EVENT_GUILD_CREATE` is guaranteed to provide

Currently the documentation doesn't mention that the "Guild Channel" resource from the EVENT_GUILD_CREATE provides channels.

API User outline does not include Bot Account differences

In particular, I would point out Modify Current User.

`GUILD_MEMBER_LEAVE` should have a "type" field containing the reason for the member removal

Something like

{
    "type": "ban"
}

That would make it clear whether a user is banned/kicked or left the guild.
Possible types ban|kick|self

[Feature Request] Emotes for text chat

Slack has the ability to attach emotes to chat messages (reactions), could this feature be implemented into discord?

"Bot" Token Type Soon to be Required

Starting Monday, September 5th we will begin requiring token type in Authorization headers. This means for bot users that you must now display the "Bot" token type, similar to "Bearer" for OAuth requests.

Example:

Authorization: Bot MjA5OTExNjI3MjAwMzMxNzc2.CovtgA.m1DGWZi_DhfAQuB-oOyai9UMxgg

Spelling mistake within Topics > Gateway > Events > Guild Integration Update.

The word in bold below is grammatically incorrect and should instead be were

"guild_id |snowflake | id of the guild whose integrations where updated"

pulled from: https://discordapp.com/developers/docs/topics/gateway#guild-integrations-update-event-fields

[API] Guild Members / Breaking Change

The guild members endpoint GET /api/guilds/:guild_id/members endpoint unfortunately must undergo a breaking change.

The offset and limit parameters are being changed to after and limit. Results will now be sorted by user_id, and to paginate through it, you would use the after query parameter, passing it the last user in the previous result returned (pretty much how the messages endpoint works).

Unfortunately this change has to take place to address some architectural issues we're fixing. Apologies for the inconvenience. We expect this change to go out some time next week.

API Error Codes

As part of an ongoing effort to cleanup and make our API more library friendly, we're going to be adding a set of integral error codes that are returned alongside the current message key, within our JSON error responses.

Codes

Code	Description
10001	Unknown Account
10002	Unknown Application
10003	Unknown Channel
10004	Unknown Guild
10005	Unknown Integration
10006	Unknown Invite
10007	Unknown Member
10008	Unknown Message
10009	Unknown Overwrite
10010	Unknown Provider
10011	Unknown Role
10012	Unknown Token
10013	Unknown User
20001	Bots cannot use this endpoint
20002	Only bots can use this endpoint
30001	Maximum number of guilds reached (100)
30002	Maximum number of friends reached (1000)
40001	Unauthorized
50001	Missing Access
50002	Invalid Account Type
50003	Cannot execute action on a DM channel
50004	Embed Disabled
50005	Cannot edit a message authored by another user
50006	Cannot send an empty message
50007	Cannot send messages to this user
50008	Cannot send messages in a voice channel
50009	Channel verification level is too high
50010	OAuth2 application does not have a bot
50011	OAuth2 application limit reached
50012	Invalid OAuth State
50013	Missing Permissions
50014	Invalid authentication token
50015	Note is too long
50016	Provided too few or too many messages to delete. Must provide at least 2 and fewer than 100 messages to delete.

Example

{
  "code": 50014,
  "message": "Invalid authentication token"
}

[Accounts] Removal of Convert Legacy Bot Accounts

7 Days Left to Convert Your Bot

May 1st is coming up, and legacy bot conversions will be removed 0. Make sure that you have converted your legacy bot account to an official bot account. An official bot account is tied to an application created through the "My Applications" page 1 on the developers section. After this is removed, we will start to remove access to public bots that have not converted yet, and you will have to create a new bot account to be able to continue to host the bot.

FAQ

Q: What is a public bot?
A: A public bot is one that uses invite links to be added to a server by giving it an invite link - circumventing the official add bot flow.

Q: What about smaller/private bots? Bots that are hosted on my own user account that I use discord with. Will you ban those?
A: If they become a problem, yes. Be smart and use an official bot account.

Q: What's the difference between a legacy bot account and an official bot account?
A: https://discordapp.com/developers/docs/topics/oauth2#bot-vs-user-accounts

Q: It's may 2nd, and I forgot to convert my bot? Can you convert it for me?
A: No. Make a new account. You've had an entire month to convert it.

[API] Bot message rate limit

Although documented, this hasn't been launched yet. This issue is to track the launch of this.

Bot Rate Limits are as follows:

1. A global 50/10 rate limit (meaning, this is the maximum # of messages a bot can send currently across all of discord).
2. A 5/5 per server rate limit.
3. A 5/5 global DM rate limit.

The rate limit applies to message creation and editing.

If your bot is big enough and is hitting the global rate limit legitimately, reach out to us and we'll increase it.

Should nonce token be interger?

Currently, the nonce token is listed in the documentation as ?interger although the API support a string value. In my opinion, nonce should be string to support more flexible validation from application.

Can I confirm if the token will be enforced into interger in the future?

[API] Bulk delete endpoint

Bots need a way to be able to bulk-delete messages - since the rate limit on the individual message delete limit endpoint breaks the use-case for being able to do swatches of moderation (delete history, purge channels, etc...)

Todo List:

• Bulk Message Delete Endpoint
• Change DELETE to POST - because GCE load balancer doesn't like DELETE with entities.
• Gateway V5 MESSAGE_DELETE_BULK Optimization
• Docs

Bulk Message Delete Endpoint

Deletes a bunch of messages from a given channel. Limited to 100 messages at once, and rate limited to one call per second per server. Will reply with 204 No Content or 429 Too Many Requests. This endpoint will only be accessible by bot users.

POST /api/channels/:channel_id/messages/bulk_delete
{"messages": [123412341234, 123171234123, ...]}

Gateway V5 - MESSAGE_DELETE_BULK Optimization.

Roll out the MESSAGE_DELETE_BULK action type which will tell the client to delete multiple messages from its store. Older clients will have the bulk-delete translated into many MESSAGE_DELETE dispatches, and newer clients will get a single MESSAGE_DELETE_BULK dispatch with a list of message IDs to delete.

The plan is to roll out the API first, and after that, roll out the gateway optimization.

[Gateway] Heartbeat ACK

The gateway will soon reply with a HEARTBEAT_ACK dispatch. You can use this coupled with regular heartbeats to check if the connection is still alive - and to attempt a reconnect/resume if the gateway doesn't respond in a timely manner.

It will be a message with, {"op": 11} in the websocket. It does not have a seq.

Todo

• Deploy
• Document

Obtaining client ID using bot token

I contribute to an open source bot project designed for discord users to run their own (small) customized bot on their personal servers. With the introduction of bot accounts we've had a lot of users come to the support server asking how to get their bot to join a server. We'd like to be able to automatically get the client ID using the auth token so this initial set up process and first server join can be a bit more streamlined for the end user.

Missing Information about Modifying Channels

Apparently, modifying a channel, as followed by https://discordapp.com/developers/docs/resources/channel#modify-channel, apparently requires the NAME field to be defined or else you get a 400 BAD REQUEST. It should either be chaneged or stated on the page that the NAME field is REQUIRED.

[Gateway] Guild Sharding

Guild sharding is coming soon, after we test & deploy it internally.

You'll soon be able to specify a shard in the ready packet. This will cause the gateway to operate in shard mode, which will distribute guilds between each shard. The shard key is a tuple of {shard_id, num_shards}, where shard_id is a number starting at 0 and less than num_shards. num_shards must be a number greater than 1 (having 1 as num_shards is kinda pointless as that's the default mode of operation).

In shard mode, the distribution of guilds is calculated by (guild_id >> 22) % num_shards == shard_id. Guilds that are not on your shard will not appear on the shard list, meaning they will not show up in the guilds object in the ready packet, and that you won't receive any events for guilds not on your shard. DMs will only be sent to shard_id 0. This will make processing of DMs a bit tricky on the bot side, but still possible.

Todo List:

• Actually deploy this - @jhgg
• Add to documentation - @b1naryth1ef #31
• Implement in airhorn.solutions as an example for reference - @b1naryth1ef
• 2500 guild limit per shard (may be higher, but won't be lower) - will come, but will roll this one out later, as bot libs add support for sharding for larger bots. This will be enforced beginning September 30, 2016 October 10, 2016 Jan 3, 2017

[API] New MANAGE_ROLES permission

The old MANAGE_ROLES permission is being deprecated favor of a new one with the value of 1 << 28. The new permission will no longer be a superpower and only let users manage roles with restrictions.

• User can grant roles to other users that are of a lower position than their highest role.
• User can edit roles of a lower position than their highest role, but they can only grant permissions they have to those roles.
• Users can only sort roles lower than their highest role.
• Users can only kick/ban users of with a lower highest role than themselves.

The old MANAGE_ROLES bit will be used as a ADMINISTRATOR permission. It will also bypass any channel overwrites now since you could always just do it by shuffling roles. This permission has no effect on channels.

Roles without colors will also no longer count toward the final color.

TODO:

• Release This
• Document This

Missing GUILD_MEMBER_CHUNK documentation

Can't find it anywhere.

Missing info from READY/RESUME

There are a bit of fields missing from ready packet. Resume logic is not well documented. I think you're encountering these as you go along and build the D client, but, we should track em here to make sure we add them all appropriately.

User Object missing "bot" field in documentation

The User Object table on the below page is missing the new(ish) bot field. I can see the bot field in the user object in the JSON for some bots in my server in the guild create event.

https://discordapp.com/developers/docs/resources/user#user-object

Missing presences field from the Guild resource on GUILD_CREATE event.

Plis

[Gateway] Document WS Close Codes

Document the different potential close codes - what they mean, and what should be done when you receive them.

code	reason
4000	unknown error
4001	unknown opcode
4002	decode error
4003	not authenticated
4004	authentication failed
4005	already authenticated
4006	session not valid
4007	invalid seq
4008	rate limited
4009	session timeout
4010	invalid shard

[API] Add way to get the 'user' object of the person or bot that changes server or channel settings.

I know that some people like to mess up server settings / channel settigns for the fun of it.

without being able to have a bot tell who it is to properly ban them in the act of sabotage of a server's settigns or a server's channel settings.

Why is this needed for gateway v7?

Because anyone can hack into someone's server and litterally screw it up.

Missing link for "Redirect URI(s)" learn more link on application review page

The application review page (https://discordapp.com/developers/applications/me/:app_id) has a missing link in the Redirect URI(s) section that points to https://github.com/vishnevskiy/discord-oauth2-example, which is a 404.

[API] Message Pinning

The API portion of message pinning is live (and the client update has rolled out to Canary).

Gateway Changes

• The MESSAGE_CREATE and MESSAGE_UPDATE now have a pinned property.

API Changes

• New PUT/DELETE to /api/:channel_id/pins/message_id.
• New GET to /api/:channel_id/pins to get a list of pinned messages.
• New error code for pinned messages.
• MANAGE_MESSAGES is the required permission to pin/unpin stuff.
• New API endpoint params to get messages "around" a single message ID.

[API] GET single message.

You can now use:

GET /channels/:channel_id/messages/:message_id to fetch a single message object.

On a guild channel will require the READ_MESSAGE_HISTORY permission.

Checklist:

• deploy
• add to docs #78

Libraries list uses noreferrer

This makes it so we can't see how many people come from the official API site. It would be nice if it came with some referrer information so we can track the traffic stats via GitHub.

Guild verification levels for bots

Today I noticed bots also fall into the guild verification level check (HIGH), making it impossible to send messages if the bot hasn't been on the guild for 10 minutes.

But since bots, to be added, require someone with MANAGE_SERVER permission, I think that they should ignore this verification level, it's simply weird that a bot that was added by an admin can't talk for 10 minutes after being added (And depending on the bot, making it 100% useless during that time).

Gateway Close Event Code 4006 not documented

This commit - 08036ce - removed code 4006 from the websocket close codes.

I would understand if it was removed from the API entirely, but I'm still getting close events (followed by websocket close) with code 4006 a few minutes after connecting, and I have no idea what they are or how to handle them. (The meaning may have changed?)

I am using https://github.com/SpaceManiac/discord-rs version 0.5.0, the latest released version of that library.

Expand information on presence update event

Here's what's in the docs at the moment.

This seems pretty vague, I would appreciate there being some more info on this. For example:

• What exactly is a "User's presence"?
• What conditions cause this event to be fired?
• Why does this event include a guild_id and roles parameter, when username, avatar, status, and game info are global?
• Can this event be a partial?

Extended Get Channel Messages functionality.

At the moment, the get channel messages endpoint is pretty meh; some ideas on how it could be improved for bot developers could be something like;

• limiting by message author, eg. grabbing the last 100 messages in a channel made by a specific user
• limiting by keyword, eg. finding messages that contain a specific keyword or phrase; this could also extend into adding search functionality to the client?

A use case for both of these features would be something like my own bot that handles basic moderation functionality and has a clean command that deletes posts made by the bot in the current channel; at the moment it searches the last 100 messages in a channel for it's own posts, but I feel that it'd be more efficient if the messages returned from the API were the messages made by the bot alone, or messages containing the bots prefix.

[Gateway] Large Bot Session Resuming

Previously resuming was only supported for users in less than 100 guilds. We are going to bump that limit up to bots in up to 2500 guilds per connection. The limit will be that the gateway will be able to replay up to 2500 messages (the calculation is max(100, min(3500, num_guilds * 75))) messages, meaning that if your bot disconnects you will now be able to resume if you do it rather quickly. Looking at a large bot in 2500 guilds, it'd take about 20 seconds to exhaust the message buffer and make the session un-resumable.

If your bot is having connectivity issues, we recommend that you shard so that the bot's gateway connection is in less guilds #17, and thus may have a longer timeframe to resume. Remember, your TCP connection to the gateway may be severed at any time - so it's wise to implement session resuming, so that the connection can recover without having to do a full reconnect. Additionally, if your bot is in too many guilds to resume, it is recommended that you shard so that your bot is under the 2500 per connection cap. Soon, there will be a 2500 guild cap per connection, so sharing for larger bots will be mandatory.

Todo List

• Deploy
• Document

[Gateway] V5 - OP_HELLO

Only two changes here:

1. When connecting to a gateway, it will immediately send an OP_HELLO (opcode = 10), with the following payload:

{"_trace": ["discord-gateway-prd-1-N"], "heartbeat_interval": 45}

The client should start heartbeating right away, to keep the connection alive while the session is started.

2. The heartbeat_interval field has been removed from the READY/RESUME packet, as it's now in the initial OP_HELLO packet.

Todo:

• deploy
• document

[Gateway] VOICE_STATE_UPDATE

Voice State Update

Looks like there was a bug in last night's deploy that's preventing bots from disconnecting from voice. We'll fix it with a hotfix tonight.

Token keep changing.

Me and my friend HyperCoder have experienced that the token of our bots keep changing even though we haven't pressed "generate a new token"
I have been pressing saved all the time but when I go and check if the token haven't changed but it still continues. Here is a gif of the issue.

https://gyazo.com/079f66350a6b4cec31ac9a1d3673edca