Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Gateway Intents #1307

Merged
merged 15 commits into from
Feb 14, 2020
Merged

Gateway Intents #1307

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
065cc01
WIP Gateway Intent documentation first pass
msciotti Jan 16, 2020
f4978cd
forgot date stuff
msciotti Jan 16, 2020
444bb4e
Spelling error
msciotti Jan 16, 2020
ebe4724
another type
msciotti Jan 16, 2020
fe22fea
<<< to <<
msciotti Jan 16, 2020
2a306d3
typo
msciotti Jan 16, 2020
63f1116
forgot underscore
msciotti Jan 18, 2020
24ce418
Specify close code 4012 and its conditions
msciotti Jan 23, 2020
febc6e9
channel pin updates in DM intent
msciotti Jan 23, 2020
8b67606
guild members intents info
msciotti Feb 14, 2020
9254063
links help too
msciotti Feb 14, 2020
eb88b96
Update Opcodes_and_Status_Codes.md
night Feb 14, 2020
7118d27
Update Gateway.md
night Feb 14, 2020
f2b13eb
Update docs/topics/Gateway.md
night Feb 14, 2020
5c3a603
Changelog
msciotti Feb 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 132 additions & 12 deletions docs/topics/Gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,115 @@ If successful, the gateway will respond by replaying all missed events in order,

If the gateway ever issues a disconnect to your client, it will provide a close event code that you can use to properly handle the disconnection. A full list of these close codes can be found in the [Response Codes](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-close-event-codes) documentation.

## Gateway Intents

> info
> Intents are optionally supported on the v6 gateway. They will become mandatory in a future v7 gateway version.

Maintaining a stateful application can be difficult when it comes to the amount of data you're expected to process, especially at scale. Gateway Intents are a system to help you lower that computational burden.

When [identifying](#DOCS_TOPICS_GATEWAY/identifying) to the gateway, you can specify an `intents` parameter which allows you to conditionally subscribe to pre-defined "intents", groups of events defined by Discord. If you do not specify a certain intent, you will not receive any of the gateway events that are batched into that group. The valid intents are:

### List of Intents

```
GUILDS (1 << 0)
- GUILD_CREATE
- GUILD_DELETE
- GUILD_ROLE_CREATE
- GUILD_ROLE_UPDATE
- GUILD_ROLE_DELETE
- CHANNEL_CREATE
- CHANNEL_UPDATE
- CHANNEL_DELETE
- CHANNEL_PINS_UPDATE

GUILD_MEMBERS (1 << 1)
- GUILD_MEMBER_ADD
- GUILD_MEMBER_UPDATE
- GUILD_MEMBER_REMOVE

GUILD_BANS (1 << 2)
- GUILD_BAN_ADD
- GUILD_BAN_REMOVE

GUILD_EMOJIS (1 << 3)
- GUILD_EMOJIS_UPDATE

GUILD_INTEGRATIONS (1 << 4)
- GUILD_INTEGRATIONS_UPDATE

GUILD_WEBHOOKS (1 << 5)
- WEBHOOKS_UPDATE

GUILD_INVITES (1 << 6)
- INVITE_CREATE
- INVITE_DELETE
msciotti marked this conversation as resolved.
Show resolved Hide resolved

GUILD_VOICE_STATES (1 << 7)
- VOICE_STATE_UPDATE

GUILD_PRESENCES (1 << 8)
- PRESENCE_UPDATE
msciotti marked this conversation as resolved.
Show resolved Hide resolved

GUILD_MESSAGES (1 << 9)
- MESSAGE_CREATE
- MESSAGE_UPDATE
- MESSAGE_DELETE

GUILD_MESSAGE_REACTIONS (1 << 10)
- MESSAGE_REACTION_ADD
- MESSAGE_REACTION_REMOVE
- MESSAGE_REACTION_REMOVE_ALL
- MESSAGE_REACTION_REMOVE_EMOJI
msciotti marked this conversation as resolved.
Show resolved Hide resolved

GUILD_MESSAGE_TYPING (1 << 11)
- TYPING_START

DIRECT_MESSAGES (1 << 12)
- CHANNEL_CREATE
- MESSAGE_CREATE
- MESSAGE_UPDATE
- MESSAGE_DELETE
- CHANNEL_PINS_UPDATE

DIRECT_MESSAGE_REACTIONS (1 << 13)
- MESSAGE_REACTION_ADD
- MESSAGE_REACTION_REMOVE
- MESSAGE_REACTION_REMOVE_ALL
- MESSAGE_REACTION_REMOVE_EMOJI

DIRECT_MESSAGE_TYPING (1 << 14)
- TYPING_START
```

Any [events not defined in an intent](#DOCS_TOPICS_GATEWAY/commands-and-events-gateway-events) are considered "passthrough" and will always be sent to you. If you specify an `intent` value in your `IDENTIFY` payload that is invalid, the socket will close with a [`4012` close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes). An invalid intent value can be one of:

- A miscalculated bit flag
- Specifying a privileged intent for which you have not opted in for your bot
- Specifying a privileged intent for which you have not been whitelisted, and your bot is in more than the current limit for unwhitelisted access

### Privileged Intents

> danger
> As of <date>, Gateway Intents are optional in v6 **except for `GUILD_PRESENCES`**. If you wish to get `PRESENCE_UPDATE` events, you **must** declare the intent. Otherwise, you will no longer receive `PRESENCE_UPDATE` events on the v6 gateway after <date>

> warns
> The current limit for specifying privileged intents without whitelisting is 100 guilds.

Some intents require whitelisting once your bot scales beyond a certain size. Those intents are:

- `GUILD_PRESENCES`

The current limit for specifying these privileged intents without being whitelisted is 100 guilds. That means you may specify the above intents without restriction until you hit the current limit, at which point your bot will not be able to join any more guilds without either being whitelisted or dropping the privileged intents for which you have not been whitelisted.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already mentioned as a warning label above. Perhaps delete the warning label or move it down to here?


In order to specify these intents in your `IDENTIFY` payload, you must first go to your application in the Developer Portal and enable the toggle for the whitelisted intent you wish to use.

> danger
> **Enabling a privileged intent without being whitelisted will limit your bot to joining 100 total guilds until you are whitelisted.** To get whitelisted, please fill out this form: <form_link_goes_here>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There needs to be clarity on the process and criteria of being whitelisted, if the aim is to stop people making massive bots that scrape data to sell then there will obviously be some requirements to be whitelisted because if you just whitelisted everyone who submitted the form then the problem this aims to solve wouldn't be fixed?

Perhaps an extra section within the documentation to cover how to get whitelisted and what requirements need to be fulfilled.


If you no longer wish to use the whitelisted intent, you may uncheck the toggle in the Developer Portal. This will remove the 100 guild limit, and will disallow you from declaring this intent in your `IDENTIFY` payload.

## Rate Limiting

Clients are allowed 120 events every 60 seconds, meaning you can send on average at a rate of up to 2 events per second. Clients who surpass this limit are immediately disconnected from the Gateway, and similarly to the HTTP API, repeat offenders will have their API access revoked. Clients are also limited to one gateway connection per 5 seconds. If you hit this limit, the Gateway will respond with an [Opcode 9 Invalid Session](#DOCS_TOPICS_GATEWAY/invalid-session).
Expand All @@ -191,6 +300,9 @@ For larger bots, client state can grow to be quite large. We recommend only stor

## Guild Subscriptions

> info
> While not deprecated, Guild Subscriptions have been superceded by [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents). You may continue to use guild subscriptions, but we recommend migrating to intents for even better results.
msciotti marked this conversation as resolved.
Show resolved Hide resolved

Presence and typing events get dispatched from guilds that your bot is a member of. For many bots, these events are not useful and can be frequent and expensive to process at scale. Because of this, we allow bots to opt out of guild subscriptions by setting `guild_subscriptions` to `false` when [Identify](#DOCS_TOPICS_GATEWAY/identify)ing.

## Guild Availability
Expand Down Expand Up @@ -296,6 +408,7 @@ Used to trigger the initial handshake with the gateway.
| shard? | array of two integers (shard_id, num_shards) | used for [Guild Sharding](#DOCS_TOPICS_GATEWAY/sharding) | - |
| presence? | [update status](#DOCS_TOPICS_GATEWAY/update-status) object | presence structure for initial presence information | - |
| guild_subscriptions? | boolean | enables dispatching of guild subscription events (presence and typing events) | true |
| intents? | integer | the [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) you wish to receive | - |

###### Identify Connection Properties

Expand Down Expand Up @@ -327,7 +440,10 @@ Used to trigger the initial handshake with the gateway.
"status": "dnd",
"since": 91879201,
"afk": false
}
},
// This intent represents 1 << 0 for GUILDS, 1 << 1 for GUILD_MEMBERS, and 1 << 2 for GUILD_BANS
// This connection will only receive the events defined in those three intents
"intents": 7
}
```

Expand Down Expand Up @@ -630,12 +746,13 @@ Sent when a user is removed from a guild (leave/kick/ban).
Sent when a guild member is updated.

###### Guild Member Update Event Fields
| Field | Type | Description |
| ------------- | ------------------------------------------------- | -------------------------------------------------- |
| guild_id | snowflake | the id of the guild |
| roles | array of snowflakes | user role ids |
| user | a [user](#DOCS_RESOURCES_USER/user-object) object | the user |
| nick | string | nickname of the user in the guild |

| Field | Type | Description |
| ------------- | ------------------------------------------------- | ------------------------------------------------- |
| guild_id | snowflake | the id of the guild |
| roles | array of snowflakes | user role ids |
| user | a [user](#DOCS_RESOURCES_USER/user-object) object | the user |
| nick | string | nickname of the user in the guild |
| premium_since | ?ISO8601 timestamp | when the user used their Nitro boost on the guild |

#### Guild Members Chunk
Expand Down Expand Up @@ -766,6 +883,9 @@ Sent when a user explicitly removes all reactions from a message.

#### Presence Update

> danger
> With the arrival of the [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) system, you _must_ specify the `GUILD_PRESENCES` intent in order to receive Presence Update events on the v6 gateway starting on <date>

A user's presence is their current state on a guild. This event is sent when a user's presence or info, such as name or avatar, is updated.

> warn
Expand Down Expand Up @@ -809,7 +929,7 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat
| application_id? | snowflake | application id for the game |
| details? | ?string | what the player is currently doing |
| state? | ?string | the user's current party status |
| emoji? | ?[emoji](#DOCS_TOPICS_GATEWAY/activity-object-activity-emoji) object | the emoji used for a custom status |
| emoji? | ?[emoji](#DOCS_TOPICS_GATEWAY/activity-object-activity-emoji) object | the emoji used for a custom status |
| party? | [party](#DOCS_TOPICS_GATEWAY/activity-object-activity-party) object | information for the current party of the player |
| assets? | [assets](#DOCS_TOPICS_GATEWAY/activity-object-activity-assets) object | images for the presence and their hover texts |
| secrets? | [secrets](#DOCS_TOPICS_GATEWAY/activity-object-activity-secrets) object | secrets for Rich Presence joining and spectating |
Expand Down Expand Up @@ -1009,11 +1129,11 @@ Returns an object based on the information in [Get Gateway](#DOCS_TOPICS_GATEWAY

###### JSON Response

| Field | Type | Description |
| ------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| url | string | The WSS URL that can be used for connecting to the gateway |
| Field | Type | Description |
| ------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| url | string | The WSS URL that can be used for connecting to the gateway |
| shards | integer | The recommended number of [shards](#DOCS_TOPICS_GATEWAY/sharding) to use when connecting |
| session_start_limit | [session_start_limit](#DOCS_TOPICS_GATEWAY/session-start-limit-object) object | Information on the current session start limit |
| session_start_limit | [session_start_limit](#DOCS_TOPICS_GATEWAY/session-start-limit-object) object | Information on the current session start limit |

###### Example Response

Expand Down
27 changes: 14 additions & 13 deletions docs/topics/Opcodes_and_Status_Codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,20 @@ All gateway events in Discord are tagged with an opcode that denotes the payload

###### Gateway Close Event Codes

| Code | Description | Explanation |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 4000 | unknown error | We're not sure what went wrong. Try reconnecting? |
| 4001 | unknown opcode | You sent an invalid [Gateway opcode](#DOCS_TOPICS_GATEWAY/payloads-and-opcodes) or an invalid payload for an opcode. Don't do that! |
| 4002 | decode error | You sent an invalid [payload](#DOCS_TOPICS_GATEWAY/sending-payloads) to us. Don't do that! |
| 4003 | not authenticated | You sent us a payload prior to [identifying](#DOCS_TOPICS_GATEWAY/identify). |
| 4004 | authentication failed | The account token sent with your [identify payload](#DOCS_TOPICS_GATEWAY/identify) is incorrect. |
| 4005 | already authenticated | You sent more than one identify payload. Don't do that! |
| 4007 | invalid seq | The sequence sent when [resuming](#DOCS_TOPICS_GATEWAY/resume) the session was invalid. Reconnect and start a new session. |
| 4008 | rate limited | Woah nelly! You're sending payloads to us too quickly. Slow it down! |
| 4009 | session timeout | Your session timed out. Reconnect and start a new one. |
| 4010 | invalid shard | You sent us an invalid [shard when identifying](#DOCS_TOPICS_GATEWAY/sharding). |
| 4011 | sharding required | The session would have handled too many guilds - you are required to [shard](#DOCS_TOPICS_GATEWAY/sharding) your connection in order to connect. |
| Code | Description | Explanation |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4000 | unknown error | We're not sure what went wrong. Try reconnecting? |
| 4001 | unknown opcode | You sent an invalid [Gateway opcode](#DOCS_TOPICS_GATEWAY/payloads-and-opcodes) or an invalid payload for an opcode. Don't do that! |
| 4002 | decode error | You sent an invalid [payload](#DOCS_TOPICS_GATEWAY/sending-payloads) to us. Don't do that! |
| 4003 | not authenticated | You sent us a payload prior to [identifying](#DOCS_TOPICS_GATEWAY/identify). |
| 4004 | authentication failed | The account token sent with your [identify payload](#DOCS_TOPICS_GATEWAY/identify) is incorrect. |
| 4005 | already authenticated | You sent more than one identify payload. Don't do that! |
| 4007 | invalid seq | The sequence sent when [resuming](#DOCS_TOPICS_GATEWAY/resume) the session was invalid. Reconnect and start a new session. |
| 4008 | rate limited | Woah nelly! You're sending payloads to us too quickly. Slow it down! |
| 4009 | session timeout | Your session timed out. Reconnect and start a new one. |
| 4010 | invalid shard | You sent us an invalid [shard when identifying](#DOCS_TOPICS_GATEWAY/sharding). |
| 4011 | sharding required | The session would have handled too many guilds - you are required to [shard](#DOCS_TOPICS_GATEWAY/sharding) your connection in order to connect. |
| 4012 | invalid intents | You sent an invalid value for a [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents). You may have incorrectly calculated the bitwise value, or tried to specify an intent that you [have not enabled or are not whitelisted for](#DOCS_TOPICS_GATEWAY/privileged-intents) |

## Voice

Expand Down