Docs Reference Gateway events La documentación para desarrolladores está disponible en inglés.
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.
