Event reference

Every event a bot can receive, with its fields. The samples were recorded from a running server, then ids were replaced.

Events arrive as JSON objects with a type. Fields marked as not always there are left out when empty. A few events carry an object directly, so Message has content next to type.

Other events exist for the Zrzur apps. Bots never receive them, so they are not listed here. GET /gateway/schema has them all.

Bulk

Several events in one packet. v holds them in order. Unpack it and handle each one.

Intent: always · v

Error

The gateway refused you. data.type is an error type. After InvalidSession or MissingIntent the connection closes.

Intent: always · data

Authenticated

The token was accepted. Ready follows.

Intent: always

Ready

Your starting data. Events flow from here on. Fields you have no intent for are left out.

Intent: always · users, servers, channels, members, emojis, voice_states, user_settings, channel_unreads, policy_changes, session_id

Resumed

Your session was resumed. Every missed event you may still see came before this one, in order.

Intent: always

InvalidSession

The session cannot be resumed (resumable is false). Send Authenticate on the same socket and catch up over the API.

Intent: always · resumable

Pong

The answer to your Ping, with the same data.

Intent: always · data

Message

A new message. Without MESSAGE_CONTENT the text, embeds, files and components are removed, unless the bot wrote it, is mentioned, or it is a DM.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · _id, nonce, channel, author, user, member, webhook, content, system, attachments, edited, embeds, mentions, role_mentions, replies, reactions, interactions, components, interaction, masquerade, pinned, forwarded, poll, flags

MessageUpdate

A message changed: data has the new fields, clear the removed ones. Pins arrive here too.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel, data, clear

MessageAppend

The server added embeds to a message, for example a link preview.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel, append

MessageDelete

A message was deleted.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel

MessageReact

Someone added a reaction.

Intent: REACTIONS · id, channel_id, user_id, emoji_id

MessageUnreact

Someone removed their reaction.

Intent: REACTIONS · id, channel_id, user_id, emoji_id

MessageRemoveReaction

All reactions of one emoji were removed.

Intent: REACTIONS · id, channel_id, emoji_id

MessagePollVoteAdd

Someone chose an answer of a poll. answers and total hold the counts after it; who voted is never sent.

Intent: always · id, channel_id, answer_id, answers, total, version

MessagePollVoteRemove

Someone took back their choice of an answer. answers and total hold the counts after it.

Intent: always · id, channel_id, answer_id, answers, total, version

MessagePollEnd

A poll closed, early or when its time ran out. answers and total are the final counts.

Intent: always · id, channel_id, answers, total, version

BulkMessageDelete

Several messages were deleted at once.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · channel, ids

ServerCreate

The bot joined a server: the whole server, its channels, emojis and voice states.

Intent: SERVERS · id, server, channels, emojis, voice_states

ServerUpdate

A server changed: data has the new fields, clear the removed ones.

Intent: SERVERS · id, data, clear

ServerDelete

A server was deleted. Forget everything about it.

Intent: SERVERS · id

ServerMemberUpdate

A member changed: nickname, roles, avatar or timeout. The bot always sees its own.

Intent: SERVER_MEMBERS · id, data, clear

ServerMemberJoin

A member joined. The bot always sees itself join.

Intent: SERVER_MEMBERS · id, user, member

ServerMemberLeave

A member left, was kicked or banned: reason says which. When user is the bot, it left that server.

Intent: SERVER_MEMBERS · id, user, reason

ServerRoleUpdate

A role was created or changed.

Intent: SERVERS · id, role_id, data, clear

ServerRoleDelete

A role was deleted.

Intent: SERVERS · id, role_id

ServerRoleRanksUpdate

The order of the roles changed. ranks lists role ids from the highest down.

Intent: SERVERS · id, ranks

UserUpdate

A user changed their profile. Without PRESENCE status changes are left out.

Intent: always · id, data, clear, event_id

UserPlatformWipe

An account was removed from Zrzur. Delete what you store about that user.

Intent: always · user_id, flags

EmojiCreate

A custom emoji was added.

Intent: SERVERS · _id, parent, creator_id, name, animated, nsfw

EmojiUpdate

A custom emoji changed.

Intent: SERVERS · id, data

EmojiDelete

A custom emoji was deleted.

Intent: SERVERS · id

SoundboardSoundCreate

A sound was added to a server's soundboard.

Intent: always · _id, server, creator_id, name, emoji, duration_ms, volume, library_id

SoundboardSoundUpdate

A soundboard sound changed. The event carries the whole sound.

Intent: always · _id, server, creator_id, name, emoji, duration_ms, volume, library_id

SoundboardSoundDelete

A soundboard sound was removed.

Intent: always · id, server

ChannelCreate

A channel was created, or a DM with the bot was opened. DMs arrive without SERVERS too.

Intent: SERVERS

ChannelUpdate

A channel changed: data has the new fields, clear the removed ones.

Intent: SERVERS · id, data, clear

ChannelDelete

A channel was deleted.

Intent: SERVERS · id

ChannelGroupJoin

Someone joined a group. Bots are in groups only when a person added them.

Intent: always · id, user

ChannelGroupLeave

Someone left a group.

Intent: always · id, user

ChannelStartTyping

Someone started typing.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

ChannelStopTyping

Someone stopped typing.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

WebhookCreate

A webhook was created.

Intent: SERVERS · id, name, avatar, creator_id, channel_id, permissions, token, url, last_used

WebhookUpdate

A webhook changed: data has the new fields, remove the removed ones.

Intent: SERVERS · id, channel_id, data, remove

WebhookDelete

A webhook was deleted.

Intent: SERVERS · id, channel_id

ServerEventCreate

A scheduled server event was created. Sent to those who can see the event's channel, or to the whole server when it takes place elsewhere.

Intent: always · _id, server, creator, title, description, starts_at, ends_at, place, cover, status, repeat, interested_count, previous, time_zone

ServerEventUpdate

A scheduled server event changed, its status included.

Intent: always · event

ServerEventDelete

A scheduled server event is gone, or the bot can no longer see it.

Intent: always · id, server

ServerEventInterest

Someone marked a scheduled server event as interesting, or took the mark back. count is the number after it.

Intent: always · id, server, channel, user, interested, count

VoiceChannelJoin

Someone joined a voice channel.

Intent: VOICE_STATES · id, state

VoiceChannelLeave

Someone left a voice channel.

Intent: VOICE_STATES · id, user

VoiceChannelMove

Someone moved between voice channels.

Intent: VOICE_STATES · user, from, to, state

UserVoiceStateUpdate

Someone's voice state changed, for example muted or sharing a screen.

Intent: VOICE_STATES · id, channel_id, data

UserMoveVoiceChannel

A moderator moved the bot: use token to connect to the new channel on node.

Intent: always · node, from, to, token

StageUpdate

The live state of a stage changed: topic, speakers or raised hands.

Intent: VOICE_STATES · id, data

SoundboardPlay

Someone played a soundboard sound in a voice channel.

Intent: VOICE_STATES · channel_id, sound_id, user

VoiceCallUpdate

A call in a channel started or ended.

Intent: VOICE_STATES · initiator_id, channel_id, started_at, ended

InteractionCreate

Someone used a command, button, select, form or autocomplete of this bot. See Commands and interactions.

Intent: INTERACTIONS · interaction

ApplicationCommandsUpdate

An application changed its commands in this server. Clients use it to reload the list; a bot can ignore it.

Intent: SERVERS · application_id, server_id

Types

The objects named in the tables above. Dates are ISO 8601 text. Ids are 26 characters long.

ValidationProblem

One field that failed validation, for a message in the reader's language

field, rule, min, max

User

User

_id, username, discriminator, display_name, pronouns, avatar, relations, badges, status, flags, privileged, official, official_bot, official_names, bot, style, relationship, online

File

File

_id, tag, filename, metadata, content_type, size, deleted, reported, message_id, user_id, server_id, object_id

Metadata

Metadata associated with a file

Relationship

Relationship entry indicating current status with other user

_id, status

RelationshipStatus

User's relationship with another user (or themselves)

UserStatus

User's active status

text, emoji, expires_at, presence

ISO8601 Timestamp

ISO8601 formatted timestamp

Presence

Presence status

BotInformation

Bot information for if the user is a bot

owner, verified

UserStyle

How a user's name and profile look

theme, name_font, name_colour, decoration, decoration_file, nameplate, nameplate_file, effect, effect_file

Server

Server

_id, owner, name, description, channels, categories, system_messages, roles, default_permissions, icon, banner, flags, nsfw, analytics, discoverable, access, verification_level, invites_paused_until, dms_paused_until, rules_screening_since, supercharge, vanity_invite, rules_channel, stats, lobby, threads_disabled, forums_disabled, events_enabled, default_notifications, approximate_member_count

Category

Channel category

id, title, channels, default_permissions, role_permissions

OverrideField

Representation of a single permission override as it appears on models and in the database

a, d

SystemMessageChannels

System message channel assignments

user_joined, user_left, user_kicked, user_banned

Role

Role

_id, name, permissions, colour, hoist, rank, icon, owner

ServerAccess

Who can become a member of a server. Discover listing is a separate, explicit setting (discoverable) and is only allowed for Open.

ServerVerificationLevel

What members without a role need before they can send messages, react or speak (members with any role, bots and the owner are exempt)

ServerSupercharge

A server's supercharge state, shown on the server

count, level

ServerVanityInvite

A server's custom invite link. While the server is below the level that unlocks it, the link works for 7 days, then pauses; the name stays reserved for the server for 90 days after the drop.

code, channel, claimed_at, below_level_since

ServerStat

A live counter shown at the top of a server's channel list

ServerLobby

A server's welcome page: what the server is about, where to start, common questions and who runs it. Every text is shown as plain text or message Markdown.

enabled, tagline, about, accent, appearance, hide_sections, onboarding, actions, channels, faq, staff_roles, sections, news_channel, intro_channel

LobbyAppearance

Server-specific lobby appearance. Missing values inherit the app theme.

secondary, background, surface, text, banner_height, radius, blend, angle, layout, density, banner_mode, show_greeting, show_member_count, show_chat, show_invite, channel_limit, newcomer_limit

LobbyLayout

LobbyDensity

LobbyBannerMode

LobbyRoleQuestion

Role choices are public opt-ins, not verification or moderation gates.

id, question, description, options

LobbyRoleOption

id, label, role

LobbyAction

A lobby button that opens a channel of the server

label, channel, emoji

LobbyQuestion

A question and its answer (Markdown)

question, answer

LobbySection

A part of the lobby page

ServerNotificationLevel

What a member who never chose a level for a server is notified about

Channel

Channel

VoiceInformation

Voice information for a channel

max_users, stage

ThreadInformation

State of a thread

owner, starter_message, archived, locked, tags, message_count

ForumInformation

Settings of a forum channel

tags, require_tag

ForumTag

A forum tag

id, name, emoji

Member

Server Member

_id, joined_at, nickname, pronouns, avatar, roles, timeout, can_publish, can_receive, accepted_rules_at

MemberCompositeKey

Composite primary key consisting of server and user id

server, user

Emoji

Emoji

_id, parent, creator_id, name, animated, nsfw

EmojiParent

Parent Id of the emoji

ChannelVoiceState

Voice state for a channel

id, participants

UserVoiceState

Voice State information for a user

id, joined_at, is_receiving, is_publishing, screensharing, camera

ChannelUnread

Channel Unread

_id, last_id, mentions

ChannelCompositeKey

Composite primary key consisting of channel and user id

channel, user

PolicyChange

Platform policy change

created_time, effective_time, description, url, translations

Ping

Ping Packet

MessageWebhook

Information about the webhook bundled with Message

name, avatar

SystemMessage

System Event

Embed

Embed

Special

Information about special remote content

LightspeedType

Type of remote Lightspeed.tv content

TwitchType

Type of remote Twitch content

BandcampType

Type of remote Bandcamp content

Image

Image

url, width, height, size

ImageSize

Image positioning and size

Video

Video

url, width, height

EmbedAuthor

Author line of a text embed

name, icon_url, url

EmbedField

Name / value pair of a text embed

name, value, inline

EmbedFooter

Footer of a text embed

text, icon_url

Interactions

Information to guide interactions on this message

reactions, restrict_reactions

ComponentBlock

Block of a message's components or of a form. Tagged so later blocks can be added without breaking old clients, which skip blocks they do not know.

Component

Interactive element: in a row, next to a section, or in a form field

ButtonStyle

Visual style of a button

ComponentRestriction

Who may use a component; empty lists mean anyone who can see the message

users, roles

SelectOption

Entry of a string select, radio group or checkbox group

label, value, description, emoji, default

CommandChannelType

Channel kinds a Channel option may be restricted to

TextInputStyle

Size of a text input

MediaItem

An image shown in a gallery or next to a section. Either a web link (loaded through the media proxy) or a file attached to the same message.

url, attachment, description, spoiler

SeparatorSpacing

Space a separator adds

MessageInteraction

Interaction a bot message answers, shown as "<user> used /<name>"

_id, user, name

InteractionType

Kind of interaction

Masquerade

Name and / or avatar override information

name, avatar, colour

MessageForward

Origin of a forwarded message The forwarded copy keeps the text, files and embeds; this only says where they came from. Readers who can't open the original channel still see the copy, just without a working link back. Direct messages, groups and messages sent under another name name no place.

channel, server, message, sent_at, note

Poll

Poll carried by a message Answers show only how many people chose them; who chose what is read with GET /channels/{target}/messages/{msg}/polls/answers/{answer}/voters.

question, answers, allow_multiselect, expires_at, ended, me, version

PollAnswer

One answer of a poll

id, text, emoji, count

PartialMessage

id, nonce, channel, author, user, member, webhook, content, system, attachments, edited, embeds, mentions, role_mentions, replies, reactions, interactions, components, interaction, masquerade, pinned, forwarded, poll, flags

FieldsMessage

Optional fields on message

AppendMessage

Appended Information

embeds

PollAnswerCount

Vote count of one answer

id, count

PartialServer

id, owner, name, description, channels, categories, system_messages, roles, default_permissions, icon, banner, flags, nsfw, analytics, discoverable, access, verification_level, invites_paused_until, dms_paused_until, rules_screening_since, supercharge, vanity_invite, rules_channel, stats, lobby, threads_disabled, forums_disabled, events_enabled, default_notifications, approximate_member_count

FieldsServer

Optional fields on server object

PartialMember

id, joined_at, nickname, pronouns, avatar, roles, timeout, can_publish, can_receive, accepted_rules_at

FieldsMember

Optional fields on server member object

RemovalIntention

Member removal intention

PartialRole

id, name, permissions, colour, hoist, rank, icon, owner

FieldsRole

Optional fields on server object

PartialUser

id, username, discriminator, display_name, pronouns, avatar, relations, badges, status, flags, privileged, official, official_bot, official_names, bot, style, relationship, online

FieldsUser

Optional fields on user object

PartialEmoji

Partial emoji representation

name

PartialChannel

Partial representation of a channel

name, owner, description, icon, nsfw, active, permissions, role_permissions, member_permissions, default_permissions, last_message_id, voice, slowmode, announcement, permissions_synced, thread, forum

FieldsChannel

Optional fields on channel object

PartialWebhook

id, name, avatar, creator_id, channel_id, permissions, token, url, last_used

FieldsWebhook

Optional fields on webhook object

ServerEventPlace

Where an event takes place

ServerEventStatus

Where an event stands

ServerEventRepeat

How an event repeats. The next occurrence is made when one completes.

ServerEvent

A scheduled server event

_id, server, creator, title, description, starts_at, ends_at, place, cover, status, repeat, interested_count, previous, time_zone

PartialUserVoiceState

id, joined_at, is_receiving, is_publishing, screensharing, camera

StageChange

What changed on a stage (sent as StageUpdate)

topic, speakers_added, speakers_removed, hands_raised, hands_lowered, ended

Interaction

Interaction as delivered to the bot

_id, version, application_id, token, user, member, server_id, channel_id, user_permissions, app_permissions, user_permissions_string, app_permissions_string, locale, command, message_id, message_ephemeral, component, modal, respond_by, expires_at

InteractionCommandData

Which command was used, with the user's values

id, name, version, options, target_id, focused, resolved

ApplicationCommandType

Kind of application command

InteractionDataOption

Option as filled in by the user

name, value, options

CommandOptionType

Kind of command option

InteractionOptionValue

Value a user gave for an option

InteractionResolved

Objects referenced by options and selects, limited to what the invoking user can see

users, members, roles, channels, attachments

InteractionComponentData

Which component was used

custom_id, component_type, values, resolved

InteractionModalData

Submitted form

custom_id, fields, resolved

ModalFieldValue

Value of one form field as submitted by the user

custom_id, value, values, checked

Channels and direct messages

A Message names its channel in channel and has no server field. To know where it was written, look the channel up. Keep the channels from Ready (channels) and from ChannelCreate, change them on ChannelUpdate and drop them on ChannelDelete. For a channel you do not know yet, call GET /channels/{target}.

A message is a direct message when its channel's channel_type is DirectMessage. The person is the id in recipients that is not your bot's.

{
  "channel_type": "DirectMessage",
  "_id": "01J0000000000000000000DM00",
  "active": true,
  "recipients": ["01J00000000000000000000BOT", "01J0000000000000000000USER"],
  "last_message_id": "01J00000000000000000000MSG"
}

When a person opens a direct message with your bot for the first time, ChannelCreate with the DirectMessage arrives, before any message in it. Direct messages and groups reach your bot with or without the SERVERS intent, in Ready and as ChannelCreate. Their messages need DIRECT_MESSAGES.