Gateway reference
Opcodes, close codes, intents, events and the interaction types. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
Frames and opcodes
Every frame is JSON, {"op": n, "d": ..., "s": seq, "t": "NAME"}; s and t
are only set on dispatches (op 0). Frames from the bot are at most 4096
bytes and 120 a minute.
| op | name | direction | Notes |
|---|---|---|---|
| 10 | HELLO | server | first frame: {"heartbeat_interval": 41250} (ms) |
| 2 | IDENTIFY | bot | {"token": "...", "intents": 512, "properties": {...}}; token optional when the header authenticated; intents required |
| 0 | DISPATCH | server | an event, numbered by s; the first is READY |
| 1 | HEARTBEAT | bot | send every heartbeat_interval; d may carry the last s |
| 11 | HEARTBEAT_ACK | server | answer to HEARTBEAT |
| 3 | PRESENCE_UPDATE | bot | {"status": "dnd", "activities": [{"name": "chess", "type": 0}]}, see Presence updates |
| 6 | RESUME | bot | {"token": "...", "session_id": "...", "seq": 41} on a new connection |
| 9 | INVALID_SESSION | server | d: false: the session cannot be resumed; send IDENTIFY on the same connection |
| 7 | RECONNECT | server | reserved; the server closes instead |
READY carries v, user (id, bot_id, username, handle, bot,
avatar_url), session_id, intents (granted), resume_gateway_url and
heartbeat_interval. username is the bot's name as members see it (its
display name, as it always was); handle is the account's unique name, the
one members type to mention it (@mnema_bot for a bot named Mnema Bot, see
Mentions above; a message's mentions lists the bot's id), so a bot can
find @ plus its handle in a text without the GUILD_MEMBERS intent. GET /users/@me carries both too.
Close codes
| code | meaning |
|---|---|
4000 | session taken over by another connection, or an internal error while starting the session (identify again) |
4001, 4002 | unknown opcode, undecodable frame |
4003 | not authenticated (no IDENTIFY in time) |
4004 | authentication failed: bad, revoked or expired token, bot disabled or deleted. Revoking a token or disabling a bot closes its open connections with this code immediately |
4005 | already identified |
4008 | rate limited: too many frames, IDENTIFYs, or connections (at most 3 live connections and 6 resumable sessions per bot) |
4009 | session timed out (missed heartbeats) |
4013, 4014 | invalid intents; intents the admin has not allowed for this bot |
1009, 1013 | frame too large; the bot reads too slowly (resume) |
These are the bot gateway's codes. The member WebSocket (/api/ws) has codes of
its own: there 4002 means "renew the media connection: reconnect and resume
the call", not an undecodable frame.
Intents and events
IDENTIFY lists the intents the bot wants, by their bit numbers; the
admin sets the intents a bot is allowed to ask for (Bots tab), and asking for
more closes with 4014. Shrinking the allowed intents later closes the
bot's open sessions that asked for more with 4014 as well; the bot reconnects
with fewer intents. Intents choose event classes. Which channels an
event comes from is not an intent: every event is checked, at the moment it
is sent, against what the bot's roles and overwrites let it view, so a bot
never receives an event of a channel it cannot see, a private channel included,
and loses a channel's events the moment its access ends.
| Intent | Bit | Events |
|---|---|---|
GUILDS | 1 | CHANNELS_UPDATE {}: the channel layout or the bot's access changed, fetch GET /channels again |
GUILD_MEMBERS | 2 | GUILD_MEMBER_ADD (id, username, display_name, avatar_url), for new members who share a channel with the bot |
GUILD_MESSAGES | 512 | MESSAGE_CREATE (the message, as in the REST API; it carries the sender's nonce when the sender sent one), MESSAGE_UPDATE (the message: an edit, or a file of it removed by the Owner or by auto-delete, which then has is_deleted), MESSAGE_DELETE (id, channel_id, parent_id) |
GUILD_MESSAGE_REACTIONS | 1024 | MESSAGE_REACTIONS_UPDATE (message_id, channel_id, reactions: the new summary) |
The bot's own messages are dispatched to it as well. Message content is always included. Not offered in v1: typing, other members' presence, voice, member removal.
The message object
MESSAGE_CREATE and MESSAGE_UPDATE carry the message as the REST API returns it:
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them. |
content (required) | string | |
created_at (required) | string (date-time) | |
direct_mentions | string (uuid)[] | DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list. |
display_name (required) | string | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (date-time) | ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock. |
forward | ForwardRef | Forward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward. |
id (required) | string (uuid) | |
is_bot | boolean | IsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message. |
is_edited (required) | boolean | |
is_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (uuid)[] | MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves. |
mentions (required) | string (uuid)[] | Mentions are the users this message mentions (@username, @all, @here). |
nonce | string (uuid) | Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does. |
number (required) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (date-time) | PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone). |
pinned_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title is the required title of a root post in a forum channel (max 100 characters). |
updated_at (required) | string (date-time) | |
user_id (required) | string (uuid) | |
username (required) | string |
Event payloads
READY
The first dispatch after IDENTIFY.
interface Ready {
v: number
user: ReadyUser
session_id: string
/** The intents granted. */
intents: number
resume_gateway_url: string
heartbeat_interval: number
}
interface ReadyUser {
/** The bot's user id: the author of its messages and the id in `mentions`. */
id: string
bot_id: string
/** The bot's name as members see it (its display name). */
username: string
/**
* The account's unique name, the one members mention (@bot-...).
* Servers before 3.1 do not send it: recognise a
* mention of the bot by its id in a message's `mentions` instead.
*/
handle?: string
bot: true
avatar_url?: string
}
RESUMED
After a successful RESUME; no payload.
CHANNELS_UPDATE (GUILDS)
The channel layout or the bot's access changed: fetch GET /channels again. The payload is {}.
GUILD_MEMBER_ADD (GUILD_MEMBERS)
A new member who shares a channel with the bot.
interface MemberAddEvent {
id: string
username: string
display_name: string
avatar_url?: string
}
MESSAGE_CREATE, MESSAGE_UPDATE (GUILD_MESSAGES)
The message as the REST API returns it.
interface Message {
id: string
channel_id: string
user_id: string
username: string
display_name: string
avatar_url?: string
content: string
created_at: string
updated_at: string
number: number
is_edited: boolean
is_pinned: boolean
is_bot?: boolean
is_webhook?: boolean
is_locked?: boolean
is_resolved?: boolean
attachments: Attachment[]
embeds?: Embed[]
components?: MessageComponents
reactions: ReactionSummary[]
mentions: string[]
direct_mentions?: string[]
mention_roles?: string[]
/** The sender's nonce, in MESSAGE_CREATE when the sender sent one. */
nonce?: string
parent_id?: string
reply_count: number
reply_to_id?: string
reply_to?: ReplyPreview
forward?: { forwarded: boolean }
poll?: Poll
pinned_at?: string
pinned_by?: UserRef
last_activity_at?: string
title?: string
tags?: unknown[]
/** 64 on an ephemeral note (in a component interaction's message). */
flags?: number
/**
* When the server deletes a message sent with `lifetime_seconds` (RFC 3339);
* absent on a message without a lifetime. Reads leave such a message out
* once this has passed.
*/
expires_at?: string
}
MESSAGE_DELETE (GUILD_MESSAGES)
A message was deleted.
interface MessageDeleteEvent {
id: string
channel_id: string
parent_id?: string | null
}
MESSAGE_REACTIONS_UPDATE (GUILD_MESSAGE_REACTIONS)
The new reaction summary of a message.
interface ReactionsUpdateEvent {
message_id: string
channel_id: string
reactions: ReactionSummary[]
}
INTERACTION_CREATE (no intent)
A command run, a click or a modal submit.
interface InteractionPayload {
id: string
token: string
type: 2 | 3 | 5
channel_id: string
application_id: string
data: InteractionData
member: InteractionMember
message?: InteractionMessage
}
interface InteractionData {
/** Command id (type 2). */
id?: string
/** Command name (type 2). */
name?: string
options?: CommandOptionValue[]
/** The component's or modal's custom_id (types 3 and 5). */
custom_id?: string
component_type?: number
values?: string[]
resolved?: ResolvedData
/** Modal submit rows (type 5). */
components?: { type: 1; components: SubmittedTextInput[] }[]
}
interface InteractionUser {
id: string
username: string
display_name: string
avatar_url?: string
}