discord / discord-api-docs Goto Github PK
View Code? Open in Web Editor NEWOfficial Discord API Documentation
Home Page: https://discord.com/developers/docs/intro
License: Other
Official Discord API Documentation
Home Page: https://discord.com/developers/docs/intro
License: Other
Slack has the ability to attach emotes to chat messages (reactions), could this feature be implemented into discord?
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.
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).
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.
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
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.
The documentation states the Ready event has the following properties:
The ones I receive have the following ones:
Overall a few are missing and too much.
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.
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.
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. |
{
"code": 50014,
"message": "Invalid authentication token"
}
We're disabling read states entirely for bots. This shouldn't break any APIs (yet - read on for more).
TODO: Document this.
It's random, but there's nowhere in the docs that mention the API URL.
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.
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.
position
than their highest role.position
than their highest role, but they can only grant permissions they have to those roles.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.
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.
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
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.
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:
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.
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
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.
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.
Can't find it anywhere.
Plis
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 |
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.
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:
guild_id
and roles
parameter, when username, avatar, status, and game info are global?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
Currently the documentation doesn't mention that the "Guild Channel" resource from the EVENT_GUILD_CREATE
provides channels
.
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...)
MESSAGE_DELETE_BULK
OptimizationDeletes 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, ...]}
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.
In particular, I would point out Modify Current User.
The API portion of message pinning is live (and the client update has rolled out to Canary).
MESSAGE_CREATE
and MESSAGE_UPDATE
now have a pinned
property./api/:channel_id/pins/message_id
./api/:channel_id/pins
to get a list of pinned messages.Although documented, this hasn't been launched yet. This issue is to track the launch of this.
Bot Rate Limits are as follows:
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.
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.
Only two changes here:
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.
heartbeat_interval
field has been removed from the READY/RESUME packet, as it's now in the initial OP_HELLO packet.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.
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?
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;
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.
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:
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.
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).
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.
Something like
{
"type": "ban"
}
That would make it clear whether a user is banned/kicked or left the guild.
Possible types ban|kick|self
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.
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.
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
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.
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.
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
USER.md references connection objects, which are not documented and given a dead link
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.
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.
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.
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).
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)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.