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.

opnamedirectionNotes
10HELLOserverfirst frame: {"heartbeat_interval": 41250} (ms)
2IDENTIFYbot{"token": "...", "intents": 512, "properties": {...}}; token optional when the header authenticated; intents required
0DISPATCHserveran event, numbered by s; the first is READY
1HEARTBEATbotsend every heartbeat_interval; d may carry the last s
11HEARTBEAT_ACKserveranswer to HEARTBEAT
3PRESENCE_UPDATEbot{"status": "dnd", "activities": [{"name": "chess", "type": 0}]}, see Presence updates
6RESUMEbot{"token": "...", "session_id": "...", "seq": 41} on a new connection
9INVALID_SESSIONserverd: false: the session cannot be resumed; send IDENTIFY on the same connection
7RECONNECTserverreserved; 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

codemeaning
4000session taken over by another connection, or an internal error while starting the session (identify again)
4001, 4002unknown opcode, undecodable frame
4003not authenticated (no IDENTIFY in time)
4004authentication 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
4005already identified
4008rate limited: too many frames, IDENTIFYs, or connections (at most 3 live connections and 6 resumable sessions per bot)
4009session timed out (missed heartbeats)
4013, 4014invalid intents; intents the admin has not allowed for this bot
1009, 1013frame 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.

IntentBitEvents
GUILDS1CHANNELS_UPDATE {}: the channel layout or the bot's access changed, fetch GET /channels again
GUILD_MEMBERS2GUILD_MEMBER_ADD (id, username, display_name, avatar_url), for new members who share a channel with the bot
GUILD_MESSAGES512MESSAGE_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_REACTIONS1024MESSAGE_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:

FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]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_mentionsstring (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
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (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.
forwardForwardRefForward 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_botbooleanIsBot 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_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (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).
noncestring (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)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (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_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle 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
}

Interactions

Something wrong on this page? Tell us.