Ereignisreferenz

Jedes Ereignis, das ein Bot bekommen kann, mit seinen Feldern. Die Beispiele stammen von einem laufenden Server; die IDs wurden ersetzt.

Ereignisse kommen als JSON-Objekte mit type. Felder, die nicht immer da sind, fehlen, wenn sie leer sind. Einige Ereignisse tragen ein Objekt direkt, Message hat also content neben type.

Andere Ereignisse gibt es für die Zrzur-Apps. Bots bekommen sie nie, darum stehen sie hier nicht. GET /gateway/schema enthält sie alle.

Bulk

Mehrere Ereignisse in einem Paket. v enthält sie der Reihe nach. Packe es aus und behandle jedes einzeln.

Intent: always · v

Error

Das Gateway hat dich abgewiesen. data.type ist ein Fehlertyp. Nach InvalidSession oder MissingIntent schließt die Verbindung.

Intent: always · data

Authenticated

Das Token wurde akzeptiert. Ready folgt.

Intent: always

Ready

Deine Startdaten. Ab hier fließen Ereignisse. Felder ohne passenden Intent fehlen.

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

Resumed

Deine Sitzung wurde fortgesetzt. Alle verpassten Ereignisse, die du noch sehen darfst, kamen vorher, der Reihe nach.

Intent: always

InvalidSession

Die Sitzung lässt sich nicht fortsetzen (resumable ist false). Sende Authenticate auf demselben Socket und hole Verpasstes über die API nach.

Intent: always · resumable

Pong

Die Antwort auf dein Ping, mit denselben data.

Intent: always · data

Message

Eine neue Nachricht. Ohne MESSAGE_CONTENT fehlen Text, Embeds, Dateien und Komponenten, außer der Bot hat sie geschrieben, wird erwähnt, oder es ist eine Direktnachricht.

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

Eine Nachricht hat sich geändert: data hat die neuen Felder, clear die entfernten. Auch Anheften kommt hier an.

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

MessageAppend

Der Server hat einer Nachricht Embeds hinzugefügt, etwa eine Linkvorschau.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel, append

MessageDelete

Eine Nachricht wurde gelöscht.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel

MessageReact

Jemand hat eine Reaktion hinzugefügt.

Intent: REACTIONS · id, channel_id, user_id, emoji_id

MessageUnreact

Jemand hat seine Reaktion entfernt.

Intent: REACTIONS · id, channel_id, user_id, emoji_id

MessageRemoveReaction

Alle Reaktionen mit einem Emoji wurden entfernt.

Intent: REACTIONS · id, channel_id, emoji_id

MessagePollVoteAdd

Jemand hat eine Antwort einer Umfrage gewählt. answers und total enthalten die Zahlen danach; wer abgestimmt hat, wird nie gesendet.

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

MessagePollVoteRemove

Jemand hat seine Wahl einer Antwort zurückgenommen. answers und total enthalten die Zahlen danach.

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

MessagePollEnd

Eine Umfrage wurde geschlossen, vorzeitig oder nach Ablauf ihrer Zeit. answers und total sind die Endzahlen.

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

BulkMessageDelete

Mehrere Nachrichten wurden auf einmal gelöscht.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · channel, ids

ServerCreate

Der Bot ist einem Server beigetreten: der ganze Server, seine Kanäle, Emojis und Sprachstatus.

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

ServerUpdate

Ein Server hat sich geändert: data hat die neuen Felder, clear die entfernten.

Intent: SERVERS · id, data, clear

ServerDelete

Ein Server wurde gelöscht. Vergiss alles darüber.

Intent: SERVERS · id

ServerMemberUpdate

Ein Mitglied hat sich geändert: Spitzname, Rollen, Avatar oder Timeout. Eigene Änderungen sieht der Bot immer.

Intent: SERVER_MEMBERS · id, data, clear

ServerMemberJoin

Ein Mitglied ist beigetreten. Den eigenen Beitritt sieht der Bot immer.

Intent: SERVER_MEMBERS · id, user, member

ServerMemberLeave

Ein Mitglied ist gegangen, wurde gekickt oder gebannt: reason sagt, was davon. Ist user der Bot, hat er diesen Server verlassen.

Intent: SERVER_MEMBERS · id, user, reason

ServerRoleUpdate

Eine Rolle wurde erstellt oder geändert.

Intent: SERVERS · id, role_id, data, clear

ServerRoleDelete

Eine Rolle wurde gelöscht.

Intent: SERVERS · id, role_id

ServerRoleRanksUpdate

Die Reihenfolge der Rollen hat sich geändert. ranks listet Rollen-IDs von oben nach unten.

Intent: SERVERS · id, ranks

UserUpdate

Jemand hat sein Profil geändert. Ohne PRESENCE fehlen Statusänderungen.

Intent: always · id, data, clear, event_id

UserPlatformWipe

Ein Konto wurde aus Zrzur entfernt. Lösche, was du über diesen Benutzer speicherst.

Intent: always · user_id, flags

EmojiCreate

Ein eigenes Emoji wurde hinzugefügt.

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

EmojiUpdate

Ein eigenes Emoji hat sich geändert.

Intent: SERVERS · id, data

EmojiDelete

Ein eigenes Emoji wurde gelöscht.

Intent: SERVERS · id

SoundboardSoundCreate

Dem Soundboard eines Servers wurde ein Sound hinzugefügt.

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

SoundboardSoundUpdate

Ein Soundboard-Sound wurde geändert. Das Ereignis enthält den ganzen Sound.

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

SoundboardSoundDelete

Ein Soundboard-Sound wurde entfernt.

Intent: always · id, server

ChannelCreate

Ein Kanal wurde erstellt oder eine Direktnachricht mit dem Bot geöffnet. Direktnachrichten kommen auch ohne SERVERS.

Intent: SERVERS

ChannelUpdate

Ein Kanal hat sich geändert: data hat die neuen Felder, clear die entfernten.

Intent: SERVERS · id, data, clear

ChannelDelete

Ein Kanal wurde gelöscht.

Intent: SERVERS · id

ChannelGroupJoin

Jemand ist einer Gruppe beigetreten. Bots sind nur in Gruppen, wenn eine Person sie hinzugefügt hat.

Intent: always · id, user

ChannelGroupLeave

Jemand hat eine Gruppe verlassen.

Intent: always · id, user

ChannelStartTyping

Jemand hat angefangen zu tippen.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

ChannelStopTyping

Jemand hat aufgehört zu tippen.

Intent: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

WebhookCreate

Ein Webhook wurde erstellt.

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

WebhookUpdate

Ein Webhook hat sich geändert: data hat die neuen Felder, remove die entfernten.

Intent: SERVERS · id, channel_id, data, remove

WebhookDelete

Ein Webhook wurde gelöscht.

Intent: SERVERS · id, channel_id

ServerEventCreate

Ein geplantes Server-Event wurde erstellt. Geht an alle, die den Kanal des Events sehen, oder an den ganzen Server, wenn es woanders stattfindet.

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

ServerEventUpdate

Ein geplantes Server-Event wurde geändert, auch sein Status.

Intent: always · event

ServerEventDelete

Ein geplantes Server-Event ist weg, oder der Bot kann es nicht mehr sehen.

Intent: always · id, server

ServerEventInterest

Jemand hat ein geplantes Server-Event als interessant markiert oder die Markierung entfernt. count ist die Zahl danach.

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

VoiceChannelJoin

Jemand ist einem Sprachkanal beigetreten.

Intent: VOICE_STATES · id, state

VoiceChannelLeave

Jemand hat einen Sprachkanal verlassen.

Intent: VOICE_STATES · id, user

VoiceChannelMove

Jemand ist zwischen Sprachkanälen gewechselt.

Intent: VOICE_STATES · user, from, to, state

UserVoiceStateUpdate

Der Sprachstatus einer Person hat sich geändert, etwa stumm oder Bildschirm geteilt.

Intent: VOICE_STATES · id, channel_id, data

UserMoveVoiceChannel

Eine Moderatorin hat den Bot verschoben: Verbinde dich mit token zum neuen Kanal auf node.

Intent: always · node, from, to, token

StageUpdate

Der Live-Zustand einer Bühne hat sich geändert: Thema, Sprecher oder gehobene Hände.

Intent: VOICE_STATES · id, data

SoundboardPlay

Jemand hat in einem Sprachkanal einen Soundboard-Sound abgespielt.

Intent: VOICE_STATES · channel_id, sound_id, user

VoiceCallUpdate

Ein Anruf in einem Kanal hat begonnen oder geendet.

Intent: VOICE_STATES · initiator_id, channel_id, started_at, ended

InteractionCreate

Jemand hat einen Befehl, Button, ein Menü, Formular oder eine Autovervollständigung dieses Bots benutzt. Siehe Befehle und Interaktionen.

Intent: INTERACTIONS · interaction

ApplicationCommandsUpdate

Eine Anwendung hat ihre Befehle auf diesem Server geändert. Apps laden damit die Liste neu; ein Bot kann es ignorieren.

Intent: SERVERS · application_id, server_id

Typen

Die Objekte aus den Tabellen oben. Daten sind ISO-8601-Text. IDs sind 26 Zeichen lang. Beschreibungen der Typen kommen aus der API und bleiben auf Englisch.

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

Kanäle und Direktnachrichten

Eine Message nennt ihren Kanal in channel und hat kein Feld server. Um zu wissen, wo sie geschrieben wurde, schlage den Kanal nach. Behalte die Kanäle aus Ready (channels) und aus ChannelCreate, ändere sie bei ChannelUpdate und entferne sie bei ChannelDelete. Für einen Kanal, den du noch nicht kennst, rufe GET /channels/{target} auf.

Eine Nachricht ist eine Direktnachricht, wenn der channel_type ihres Kanals DirectMessage ist. Die Person ist die ID in recipients, die nicht die deines Bots ist.

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

Öffnet eine Person zum ersten Mal eine Direktnachricht mit deinem Bot, kommt ChannelCreate mit dem DirectMessage, vor jeder Nachricht darin. Direktnachrichten und Gruppen erreichen deinen Bot mit und ohne den Intent SERVERS, in Ready und als ChannelCreate. Ihre Nachrichten brauchen DIRECT_MESSAGES.