Gateway events¶

A Dispatch reports a change or a command result through the Gateway. It has opcode 0, an event name, and a payload.

Dispatch envelope¶

{
  "op": 0,
  "t": "MESSAGE_CREATE",
  "s": 17,
  "d": { }
}

Ready establishes sequence 1. Live Dispatches advance it by one. Replayed Dispatches keep their original sequence and can have gaps. Resumed carries the session's current sequence without advancing it. The sequence is local to one Gateway session and orders nothing across shards or HTTP operations.

Dispatch delivery¶

Event filtering defines delivery by guild availability, channel visibility, permissions, and session settings. Account-scoped Dispatches go only through the session-level filters, which are the shard filter and the ignored_events list.

Most guild-scoped Dispatches carry a guild_id string, which the Gateway adds to every event it fans out to a guild. Guild Create and Guild Sync identify the guild as id. Guild Counts Update and Channel Member Counts Update have no top-level guild_id, and each entry in their counts array has its own.

The originating session is excluded from a Dispatch only for Message Reaction Add and Message Reaction Remove in a guild channel, and only when the HTTP request supplied a session_id query parameter. That field is removed from the payload. The same field on a direct message reaction is forwarded to every recipient unchanged and excludes nobody. Every other mutation delivers its Dispatch to the acting session like any other eligible session.

A Dispatch is buffered for Resume replay unless it is Guild Sync, Guild Member List Update, or Guild Members Chunk. Those are delivered live and never retained. A single oversized Dispatch is delivered but not retained, as Limits and rate limits describes. Ready is also sent outside the replay buffer.

Dispatch events¶

TEBHOS also sends a set of product-specific events for its own clients. They are listed under TEBHOS client events.

TEBHOS never sends FAVORITE_MEME_CREATE: no route creates a saved meme.

Session and current user¶

READY¶

The initial session state. Sent once after a successful Identify, always with sequence 1.

The payload can also carry channels and read_state_proto, which the TEBHOS clients use to seed their read-state cache. Treat them as internal.

Ready is sent outside the replay buffer, so a Resume never replays it.

A bot session receives Ready as soon as it is identified, with an empty guilds array. Each of its guilds then arrives separately as the session connects to it: one Guild Create per available guild, and one Guild Delete with unavailable: true per unavailable guild. These are ordinary Dispatches, kept in the replay buffer like any other.

Shortly after Ready, every session receives one Call Create for each of its private channels that has an active call.

Guild ready object¶

The same structure appears in Ready, Guild Create, and Guild Sync.

A client that needs the rest of the roster asks for it with Request Guild Members or subscribes to a member list through Lazy Request.

An unavailable guild is reduced to id and unavailable: true, plus unavailable_hidden: true when the guild is hidden.

Inside Ready, each entry in members has its user replaced by {"id": "..."}, and the removed accounts appear in the Ready users array. A Guild Create sent after Ready, including those a bot receives for its guilds, and every Guild Sync have the members with user intact.

Session presence object¶

The first entry always has session_id: "all" and the account's combined status.

WebAuthn credential object¶

RTC region object¶

The array always begins with a synthetic entry whose id is automatic and name is Automatic. Choosing it leaves the region to the server. Every other entry is a region the account can use, ordered by distance from the latitude and longitude in the Identify properties when both parse as numbers, and otherwise by region ID.

RESUMED¶

Sent after a successful Resume has replayed every retained Dispatch above the supplied sequence. The payload is empty apart from an optional timing object for staff accounts. Resumed carries the session's current sequence in s without advancing it.

SESSIONS_REPLACE¶

The account's set of live sessions changed. The payload is a bare JSON array of session presence objects and is always the complete set. Ready sends the initial set as sessions.

AUTH_SESSION_CHANGE¶

The account's login sessions changed in a way other devices must react to.

RATE_LIMITED¶

A Request Guild Members command was refused by the bot full-member-list budget. Delivered to the requesting session alone.

The budget admits one unfiltered member request per bot account and guild every 30,000 ms. Every other command refusal is silent.

USER_UPDATE¶

The current user's account record changed. The payload is the complete user object in its private representation.

USER_SETTINGS_UPDATE¶

The current user's account-wide settings changed. The payload is the complete user settings object.

USER_GUILD_SETTINGS_UPDATE¶

One guild's notification settings changed. The payload is that guild's complete user guild settings object, with user_id added.

USER_NOTE_UPDATE¶

The current user wrote or cleared a private note.

USER_PINNED_DMS_UPDATE¶

The current user's pinned private channel set changed.

channels is always the complete set. Ready sends the initial set as pinned_dms.

USER_CONNECTIONS_UPDATE¶

The current user's external connection set changed.

WEBAUTHN_CREDENTIALS_UPDATE¶

The current user's passkey set changed. The payload is a bare JSON array of WebAuthn credential objects and is always the complete set.

RELATIONSHIP_ADD¶

The current user gained a relationship.

RELATIONSHIP_UPDATE¶

An existing relationship changed. The payload has the same structure as Relationship Add.

RELATIONSHIP_REMOVE¶

A relationship ended.

SAVED_MESSAGE_CREATE¶

The current user saved a message. The payload is the complete message object as that user sees it, with message_id added.

SAVED_MESSAGE_DELETE¶

The current user unsaved a message.

RECENT_MENTION_DELETE¶

The current user removed a message from the recent mention feed.

FAVORITE_MEME_UPDATE¶

One of the current user's saved memes changed. The payload is the complete meme object.

FAVORITE_MEME_DELETE¶

The current user deleted a saved meme.

Guilds and channels¶

GUILD_CREATE¶

A guild became available to the session. The payload is a guild ready object.

roles, channels, emojis, stickers, and voice_states are always complete, and a client replaces its stored lists with them. members is a partial list: add or update those members and keep the rest.

Every session receives Guild Create when a guild becomes available after Ready, for example after joining one or after an unavailable guild recovers. A bot session also receives one for each of its available guilds after Ready, because its Ready carries no guilds.

GUILD_SYNC¶

A session that asked for a sync through Lazy Request receives the guild's full current state again. The payload is a guild ready object, and a client handles it like Guild Create.

TEBHOS sends a sync when a Lazy Request switches the guild between active and passive, and when sync: true names the guild.

GUILD_UPDATE¶

A guild's configuration changed. The payload is the complete guild object with guild_id added.

Guild Update is the only Dispatch an unavailable guild sends.

GUILD_DELETE¶

A guild left the session's visibility, or became unavailable.

Two sources send this event. The Gateway sends {id} when the session leaves the guild, and {id, unavailable: true} when the guild becomes temporarily unreachable. The API additionally sends {guild_id, reason} to the affected user when the guild is deleted, when the user is kicked, and when the user leaves. A client reads the guild from id or guild_id, whichever is present.

Without unavailable, the account is no longer a member, and a client deletes everything it stores for that guild. With unavailable: true, a client keeps the guild as an unavailable entry until a later Guild Create.

GUILD_ROLE_CREATE¶

A role was created in a guild.

GUILD_ROLE_UPDATE¶

Exactly one role record changed.

GUILD_ROLE_UPDATE_BULK¶

One operation changed several roles together, most often a reorder.

GUILD_ROLE_DELETE¶

A role was deleted from a guild.

GUILD_EMOJIS_UPDATE¶

A guild's emojis changed.

A client replaces its stored emojis with this array. TEBHOS sends no per-emoji events.

GUILD_STICKERS_UPDATE¶

A guild's stickers changed.

A client replaces its stored stickers with this array. TEBHOS sends no per-sticker events.

CHANNEL_CREATE¶

A channel became visible to the session, whether newly created or newly permitted. The payload is the complete channel object, with guild_id present for a guild channel.

CHANNEL_UPDATE¶

A visible channel changed. The payload is the complete channel object.

CHANNEL_UPDATE_BULK¶

One operation changed several channels together, most often a reorder.

Each recipient sees only channels it can view. An empty result produces no Dispatch and consumes no sequence number.

CHANNEL_DELETE¶

A channel left the session's visibility, whether deleted or newly hidden. For a guild channel the payload is the channel object as it was before the change, and recipients are the sessions that could see it. When the current user closes or leaves a private channel, the payload is {id, channel_id, type}.

CHANNEL_RECIPIENT_ADD¶

A user joined a group direct message the session belongs to.

CHANNEL_RECIPIENT_REMOVE¶

A user left a group direct message the session belongs to.

WEBHOOKS_UPDATE¶

The webhook set of a guild channel changed. The event carries no webhook data, so a client that needs the new set reads it over the HTTP API.

INVITE_CREATE¶

A guild invite was created. The payload is the complete invite object, the same body GET /invites/{code} returns. It reaches the sessions holding MANAGE_CHANNELS on the invite's channel.

INVITE_DELETE¶

A guild invite was deleted.

Recipients are chosen the same way as for Invite Create.

Members and moderation¶

GUILD_MEMBER_ADD¶

A user became a member of a guild the session is connected to. The payload is the complete guild member object with guild_id added.

GUILD_MEMBER_UPDATE¶

A member's guild state or public user representation changed. The payload is the complete guild member object with guild_id added.

In a guild with more than 250 members, a passive session receives this event only when the subject is its own user.

GUILD_MEMBER_REMOVE¶

A user stopped being a member of a guild the session is connected to.

In a guild with more than 250 members, a passive session receives this event only when the subject is its own user.

GUILD_MEMBERS_CHUNK¶

Answers Request Guild Members for the requesting session.

A request that matches no member still produces one chunk with an empty members array, chunk_index 0, and chunk_count 1. This event is never retained for Resume.

GUILD_MEMBER_LIST_UPDATE¶

A member list the session subscribed to through Lazy Request resyncs the subscriber's ranges.

Member list group object¶

A group whose count is 0 is omitted. The offline group is also omitted once it holds more than 1,000 members, together with its items.

Member list operation object¶

SYNC is the only operation TEBHOS sends. A client MUST ignore an operation it does not recognise.

Member list item object¶

Each item has exactly one of the fields.

GUILD_AUDIT_LOG_ENTRY_CREATE¶

An audit log entry was written. The payload is the audit log entry with guild_id added. Recipients are every session in the guild that holds VIEW_AUDIT_LOG, including the acting session.

GUILD_BAN_ADD¶

A guild ban was created.

GUILD_BAN_REMOVE¶

A guild ban was removed.

PRESENCE_UPDATE¶

One visible presence changed. The payload is a presence object.

A session receives a presence for a friend, for a recipient of a group direct message it belongs to, and for a guild member it subscribed to through the members array of a Lazy Request. A bot session holds no friend or group direct message subscription, so the guild path is the only one that reaches it.

Presence object¶

An account's published status is the highest-precedence status across its live sessions, in the order dnd, online, idle, invisible, and offline when no session is live. A session that selected invisible, and an account with no live session, both publish status: "offline". A session that lost its transport is published as offline 5,000 ms later, even though it stays resumable for 60,000 ms. custom_status is null whenever the published status is offline.

Custom status object¶

PRESENCE_UPDATE_BULK¶

Several visible presences delivered in one Dispatch. A guild sends this only when it leaves the unavailable state, immediately after the Guild Create that restores it.

PASSIVE_UPDATES¶

A passive session in a guild with more than 250 members receives missed changes every 30,000 ms. No event is sent when nothing changed.

Messages and reactions¶

MESSAGE_CREATE¶

A visible message was created. The payload is the complete message object with the fields below added.

Message Create overrides both the passive filter and the ignored_events list when the message mentions the session's user. See Event filtering.

MESSAGE_UPDATE¶

A visible message changed. The payload is the complete current message object. In a guild channel it is extended with guild_id and member.

MESSAGE_DELETE¶

One visible message was deleted.

MESSAGE_DELETE_BULK¶

Several messages in one channel were deleted together.

MESSAGE_ACK¶

The current user's read state advanced for a channel, usually because another of the account's sessions read it.

MESSAGE_REACTION_ADD¶

A user added a reaction to a message.

In a guild channel the session named by the request's session_id is excluded and the field is removed. In a private channel the field is delivered and excludes nobody, so a client MUST tolerate receiving its own reaction back.

Reaction emoji object¶

MESSAGE_REACTION_ADD_MANY¶

With the DEBOUNCE_MESSAGE_REACTIONS session flag, private-channel additions are grouped over 650 ms and delivered together. Each window keeps the latest 512 additions. Guild-channel additions always arrive as individual Message Reaction Add events.

A window covering several messages produces a separate Dispatch for each. When the window closes holding exactly one addition, the session receives a plain Message Reaction Add.

MESSAGE_REACTION_REMOVE¶

One user's reaction was removed from a message. The payload has the same fields as Message Reaction Add, and exclusion works the same way.

MESSAGE_REACTION_REMOVE_ALL¶

Every reaction was removed from a message at once.

MESSAGE_REACTION_REMOVE_EMOJI¶

Every reaction using one emoji was removed from a message.

TYPING_START¶

A visible user began typing in a channel.

In a guild, the typing override set through Lazy Request decides delivery. With no override, a session receives the event when it is active in the guild or when the guild has 250 members or fewer.

CHANNEL_PINS_UPDATE¶

A message was pinned or unpinned.

CHANNEL_PINS_ACK¶

The current user acknowledged a channel's pins. Every session of the account receives it.

Voice and calls¶

VOICE_STATE_UPDATE¶

A participant's voice state changed. The payload is a voice state object. Recipients are the sessions that can view the voice channel, passive sessions included. A channel_id of null means the participant left.

Voice state object¶

VOICE_SERVER_UPDATE¶

The session received or replaced its own voice grant. Delivered to the requesting session alone.

TEBHOS uses LiveKit for voice media. There is no second voice WebSocket, no voice opcode set, and no UDP discovery step. See Voice.

A grant is issued when a connection opens, when it moves to another channel, and when its region changes. Toggling self_mute, self_video, or self_stream produces no new grant.

ENTRANCE_SOUND_PLAY¶

A participant played their entrance sound in a voice channel they are connected to. See Entrance sounds.

Recipients are every other account with a voice state in that channel, once per account. The event reaches all of an account's sessions, so a client filters on channel_id.

CALL_CREATE¶

A private channel call began, or became visible in the session's initial state.

Recipients are every recipient of the channel, whether or not they joined the call. The same set receives Call Update and Call Delete.

CALL_UPDATE¶

The ringing set, participant roster, or region of an active call changed. The Gateway form has the same structure as Call Create without recipients and created_at, and is sent only when the call state visibly changed. A region change made over HTTP also sends an API form with id, call_id, channel_id, initiator_id, livekit_room_name, started_at, region, voice_states, ringing, and message_id.

CALL_DELETE¶

A call ended, or became unavailable.

With unavailable: true, the client keeps the call as an unavailable entry. If it becomes available again, a fresh Call Create includes recipients and created_at.

Count response events¶

GUILD_COUNTS_UPDATE¶

Answers Request Guild Counts for the requesting session.

Guild count entry object¶

CHANNEL_MEMBER_COUNTS_UPDATE¶

Answers Request Channel Member Counts for the requesting session.

Channel count entry object¶

TEBHOS client events¶

The TEBHOS web, desktop, and mobile clients also receive the events below. They drive product features that have no standard event (live rooms, Pro, boosts, categories, cosmetics) or give the clients a faster, smaller signal next to a standard event. Their payloads are shaped for the TEBHOS clients and can change without notice, so a bot SHOULD rely on the standard events above and ignore these. Each is subject to ignored_events.

Resource representation¶

Every resource object named on this page has the representation defined by the HTTP API. A Dispatch payload with a resource object has the same fields, with the guild-scoped events adding guild_id and the message and reaction events adding member.

These reductions are specific to the Gateway. Ready strips user from each relationship and from each guild member and moves those accounts into its users array. The member added to a message event has its own user removed, and the account is in the message's author.