Docs Reference Gateway events Gateway events Every opcode, close code and DispatchEvent event of the gateway protocol, marked with which ones bots receive.
The reference for gateway protocol version v=1. How to connect and handle events is in the Gateway chapter.
Opcodes#
The op field of a GatewayFrame. In JSON it is the full name, e.g. "GATEWAY_OPCODE_DISPATCH".
Opcode Number Direction Frame field GATEWAY_OPCODE_HEARTBEAT1 bot → server heartbeat { lastSeq }GATEWAY_OPCODE_IDENTIFY2 bot → server identify { token, device, capabilities }GATEWAY_OPCODE_RESUME3 bot → server resume { token, sessionId, seq }GATEWAY_OPCODE_PRESENCE_UPDATE4 bot → server setPresence { status, until }GATEWAY_OPCODE_TYPING5 bot → server typing { roomId }GATEWAY_OPCODE_SUBSCRIBE6 bot → server subscribe { roomIds }GATEWAY_OPCODE_RECONNECT7 server → bot reconnect {}GATEWAY_OPCODE_DISPATCH8 server → bot dispatch { <event> }GATEWAY_OPCODE_INVALID_SESSION9 server → bot invalidSession { resumable }GATEWAY_OPCODE_HELLO10 server → bot hello { heartbeatIntervalMs }GATEWAY_OPCODE_HEARTBEAT_ACK11 server → bot heartbeatAck {}
Close codes#
Code Name What a bot should do 4000UNKNOWN_ERRORreconnect, RESUME; with the reason replaced by a new session — don't reconnect 4001UNKNOWN_OPCODEreconnect, RESUME 4002DECODE_ERRORreconnect, RESUME 4003NOT_AUTHENTICATEDreconnect, new IDENTIFY 4004AUTHENTICATION_FAILEDdon't reconnect: the token is wrong 4007INVALID_SEQreconnect, new IDENTIFY 4008RATE_LIMITEDback off, RESUME 4009SESSION_TIMED_OUTreconnect, new IDENTIFY 4010SESSION_REVOKEDdon't reconnect: the token was revoked or the bot deleted 4011SESSION_EVICTEDconcerns browser tabs; bots never see it
Events#
An event is one of the DispatchEvent fields, lowerCamelCase in JSON. The “Bots” column: yes — delivered to a bot by its permissions; conditional — only under the condition described; no — never sent to bots.
Session#
Event Bots Description readyyes the answer to IDENTIFY: sessionId, me, workspaces[], dms[], readStates resumedyes the answer to a successful RESUME: replayed — how many events were replayed readStateUpdateyes the bot's own read marker changed (from another device or via PUT /api/rooms/{id}/read)
Workspaces, members, roles#
Event Bots Description workspaceCreate · workspaceUpdate · workspaceDeleteyes the bot joined a workspace · settings changed · the workspace was deleted or the bot removed workspaceMemberAdd · workspaceMemberUpdate · workspaceMemberRemoveyes members: joined, roles or nickname changed, left workspaceBanAdd · workspaceBanRemoveconditional bans — only with MANAGE_MEMBERS roleCreate · roleUpdate · roleDeleteyes the workspace's roles badgeCreate · badgeUpdate · badgeDeleteyes the badge library workspaceAchievementsUpdateyes the workspace's achievement catalog changed userUpdate · presenceUpdateyes a member's profile and presence botCreate · botUpdate · botDeleteconditional the workspace's bots — only with MANAGE_BOTS (or to the bot's owner) workspaceAppUpsert · workspaceAppDeleteno workspace web apps — people only workspaceIdentityAccessUpdate— an internal SSO event for people’s sessions; ignore it if it arrives billingUpdateno billing — the workspace owner only
Rooms and messages#
Event Bots Description roomCreate · roomUpdate · roomDelete · roomPermissionsUpdateyes rooms the bot can see (or stopped seeing) categoryCreate · categoryUpdate · categoryDeleteyes room categories messageCreate · messageUpdate · messageDeleteyes messages of visible rooms and the bot's DMs; a command for the bot carries message.command messageReactionAdd · messageReactionRemoveyes reactions typingStartconditional “is typing” — only in rooms from SUBSCRIBE botCallbackconditional a button press — only to the message's author bot dmCreateyes a new DM with the bot stickerPackCreate · stickerPackUpdate · stickerPackDeleteyes the workspace's sticker packs readReceiptno people's “read” marks — never sent to bots roomNotificationUpdate · workspaceNotificationUpdate · dmStateUpdateno notification settings and DM archive — bots have none
Voice and calls#
Event Bots Description voiceStateUpdateyes who is in which voice room; empty roomId — left voiceStreamStart · voiceStreamStop · voiceCameraStop · voiceMovedyes streams, camera, a member moved voiceDisconnectedyes the bot was disconnected from voice roomRecordingyes a meeting recording in the room started or stopped soundCreate · soundUpdate · soundDeleteyes the workspace's sounds soundPlayconditional only while the bot is in the room's call sipCallUpdateyes a phone call from the room was placed or changed status roomAdmissionRequest · roomAdmissionDecidedconditional a guest waits for admission · a decision was made — to those who decide (INVITE_GUESTS in the room) callRing · callStateno one-to-one calls — not for bots backgroundCreate · backgroundUpdate · backgroundDeleteno* camera backgrounds; bots have no camera — ignore them
* The event is broadcast to the whole workspace and may arrive, but a bot has no use for it.
Calendar#
Event Bots Description eventCreate · eventUpdate · eventDelete · eventRsvpyes meetings the bot organizes and those of visible rooms; outside addresses only if the bot may change the meeting roomEventActive · roomEventEndedyes a meeting in a room started · ended eventReminderno a reminder to an attendee — a bot never attends meetings
Boards and tasks#
Event Bots Description boardCreate · boardUpdate · boardDeleteyes boards — by VIEW_BOARD boardCategoryCreate · boardCategoryUpdate · boardCategoryDeleteyes board categories taskCreate · taskUpdate · taskDelete · taskActivityyes tasks and their journal entries taskChecklistUpdate · taskChecklistDeleteyes task checklists boardRuleUpdate · boardRuleDeleteyes the board's automation rules taskGitLinksUpdateyes a task's Git links taskNoticeconditional a person's task notification — only to the bot they chose
Other#
Event Bots Description notesCreate · notesUpdate · notesDeleteno notes shelves — people only diskItemUpsert · diskItemRemoveno Disk — bots have no access yet
Tip
New events appear without a protocol version change. Skip an unknown dispatch field — that way your bot won't break when the server is updated.
