مرجع الأحداث

كل حدث يمكن أن يصل إلى البوت مع حقوله. سُجلت النماذج من سيرفر يعمل، ثم استُبدلت المعرّفات.

تصل الأحداث كائنات JSON فيها type. تُحذف الحقول الموسومة بأنها ليست دائمة عندما تكون فارغة. تحمل بعض الأحداث كائنًا مباشرة، فيأتي content في Message بجانب type.

توجد أحداث أخرى لتطبيقات زرزور. لا تصل إلى البوتات أبدًا، لذلك لم تُذكر هنا. وتجدها كلها في GET /gateway/schema.

Bulk

عدة أحداث في حزمة واحدة. يحملها الحقل v بالترتيب. افتحها وعالج كل حدث على حدة.

النية: always · v

Error

رفضتك البوابة. data.type هو نوع الخطأ. يُغلق الاتصال بعد InvalidSession أو MissingIntent.

النية: always · data

Authenticated

قُبل الرمز. يتبعه Ready.

النية: always

Ready

بياناتك الأولية. تبدأ الأحداث بالوصول بعده. تُحذف الحقول التي لا تملك نية اتصال لها.

النية: always · users, servers, channels, members, emojis, voice_states, user_settings, channel_unreads, policy_changes, session_id

Resumed

استُؤنفت جلستك. وصلت قبل هذا الحدث، بالترتيب، كل الأحداث الفائتة التي ما زال يحق لك رؤيتها.

النية: always

InvalidSession

لا يمكن استئناف الجلسة (resumable يساوي false). أرسل Authenticate على المقبس نفسه واستدرك ما فاتك عبر الواجهة البرمجية.

النية: always · resumable

Pong

الرد على Ping الذي أرسلته، ويحمل data نفسها.

النية: always · data

Message

رسالة جديدة. دون MESSAGE_CONTENT يُحذف النص والتضمينات والملفات والمكوّنات، إلا إذا كتبها البوت أو ذُكر فيها أو كانت رسالة خاصة.

النية: 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

تغيرت رسالة: يحمل data الحقول الجديدة وclear الحقول المحذوفة. يصل التثبيت هنا أيضًا.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel, data, clear

MessageAppend

أضاف السيرفر تضمينات إلى رسالة، مثل معاينة رابط.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel, append

MessageDelete

حُذفت رسالة.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · id, channel

MessageReact

أضاف أحدهم تفاعلًا.

النية: REACTIONS · id, channel_id, user_id, emoji_id

MessageUnreact

أزال أحدهم تفاعله.

النية: REACTIONS · id, channel_id, user_id, emoji_id

MessageRemoveReaction

أُزيلت كل التفاعلات برمز تعبيري واحد.

النية: REACTIONS · id, channel_id, emoji_id

MessagePollVoteAdd

اختار أحدهم إجابة في استطلاع. يحمل answers وtotal الأعداد بعد الاختيار، ولا يُرسل اسم المصوّت أبدًا.

النية: always · id, channel_id, answer_id, answers, total, version

MessagePollVoteRemove

تراجع أحدهم عن اختياره لإجابة. يحمل answers وtotal الأعداد بعد ذلك.

النية: always · id, channel_id, answer_id, answers, total, version

MessagePollEnd

أُغلق استطلاع، مبكرًا أو بانتهاء وقته. answers وtotal هما الأعداد النهائية.

النية: always · id, channel_id, answers, total, version

BulkMessageDelete

حُذفت عدة رسائل دفعة واحدة.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · channel, ids

ServerCreate

انضم البوت إلى سيرفر: السيرفر كاملًا وقنواته ورموزه التعبيرية وحالات الصوت فيه.

النية: SERVERS · id, server, channels, emojis, voice_states

ServerUpdate

تغير سيرفر: يحمل data الحقول الجديدة وclear الحقول المحذوفة.

النية: SERVERS · id, data, clear

ServerDelete

حُذف سيرفر. انسَ كل ما يخصه.

النية: SERVERS · id

ServerMemberUpdate

تغير عضو: اللقب أو الأدوار أو الصورة أو المهلة. يرى البوت تغييراته هو دائمًا.

النية: SERVER_MEMBERS · id, data, clear

ServerMemberJoin

انضم عضو. يرى البوت انضمامه هو دائمًا.

النية: SERVER_MEMBERS · id, user, member

ServerMemberLeave

غادر عضو أو طُرد أو حُظر، ويبيّن reason أيها. إذا كان user هو البوت فقد غادر ذلك السيرفر.

النية: SERVER_MEMBERS · id, user, reason

ServerRoleUpdate

أُنشئ دور أو تغير.

النية: SERVERS · id, role_id, data, clear

ServerRoleDelete

حُذف دور.

النية: SERVERS · id, role_id

ServerRoleRanksUpdate

تغير ترتيب الأدوار. يسرد ranks معرّفات الأدوار من الأعلى إلى الأدنى.

النية: SERVERS · id, ranks

UserUpdate

غيّر مستخدم ملفه الشخصي. دون PRESENCE لا تصل تغييرات الحالة.

النية: always · id, data, clear, event_id

UserPlatformWipe

أُزيل حساب من زرزور. احذف ما تخزنه عن هذا المستخدم.

النية: always · user_id, flags

EmojiCreate

أُضيف رمز تعبيري مخصص.

النية: SERVERS · _id, parent, creator_id, name, animated, nsfw

EmojiUpdate

تغير رمز تعبيري مخصص.

النية: SERVERS · id, data

EmojiDelete

حُذف رمز تعبيري مخصص.

النية: SERVERS · id

SoundboardSoundCreate

أُضيف صوت إلى لوحة أصوات سيرفر.

النية: always · _id, server, creator_id, name, emoji, duration_ms, volume, library_id

SoundboardSoundUpdate

تغيّر صوت في لوحة الأصوات. يحمل الحدث الصوت كاملًا.

النية: always · _id, server, creator_id, name, emoji, duration_ms, volume, library_id

SoundboardSoundDelete

حُذف صوت من لوحة الأصوات.

النية: always · id, server

ChannelCreate

أُنشئت قناة، أو فُتحت رسالة خاصة مع البوت. تصل الرسائل الخاصة دون SERVERS أيضًا.

النية: SERVERS

ChannelUpdate

تغيرت قناة: يحمل data الحقول الجديدة وclear الحقول المحذوفة.

النية: SERVERS · id, data, clear

ChannelDelete

حُذفت قناة.

النية: SERVERS · id

ChannelGroupJoin

انضم أحدهم إلى مجموعة. لا يكون البوت في مجموعة إلا إذا أضافه شخص.

النية: always · id, user

ChannelGroupLeave

غادر أحدهم مجموعة.

النية: always · id, user

ChannelStartTyping

بدأ أحدهم الكتابة.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

ChannelStopTyping

توقف أحدهم عن الكتابة.

النية: SERVER_MESSAGES or DIRECT_MESSAGES · id, user

WebhookCreate

أُنشئ ويب هوك.

النية: SERVERS · id, name, avatar, creator_id, channel_id, permissions, token, url, last_used

WebhookUpdate

تغير ويب هوك: يحمل data الحقول الجديدة وremove الحقول المحذوفة.

النية: SERVERS · id, channel_id, data, remove

WebhookDelete

حُذف ويب هوك.

النية: SERVERS · id, channel_id

ServerEventCreate

أُنشئت فعالية مجدولة في سيرفر. يُرسل إلى من يستطيع رؤية قناة الفعالية، أو إلى السيرفر كله إن كانت تُقام في مكان آخر.

النية: always · _id, server, creator, title, description, starts_at, ends_at, place, cover, status, repeat, interested_count, previous, time_zone

ServerEventUpdate

تغيّرت فعالية مجدولة في سيرفر، ويشمل ذلك حالتها.

النية: always · event

ServerEventDelete

زالت فعالية مجدولة، أو لم يعد البوت يستطيع رؤيتها.

النية: always · id, server

ServerEventInterest

أبدى أحدهم اهتمامه بفعالية مجدولة أو تراجع عنه. count هو العدد بعد ذلك.

النية: always · id, server, channel, user, interested, count

VoiceChannelJoin

انضم أحدهم إلى قناة صوتية.

النية: VOICE_STATES · id, state

VoiceChannelLeave

غادر أحدهم قناة صوتية.

النية: VOICE_STATES · id, user

VoiceChannelMove

انتقل أحدهم بين القنوات الصوتية.

النية: VOICE_STATES · user, from, to, state

UserVoiceStateUpdate

تغيرت حالة الصوت لشخص، مثل كتم الصوت أو مشاركة الشاشة.

النية: VOICE_STATES · id, channel_id, data

UserMoveVoiceChannel

نقل مشرف البوت: استخدم token للاتصال بالقناة الجديدة على node.

النية: always · node, from, to, token

StageUpdate

تغيّرت الحالة المباشرة لمنصّة: الموضوع أو المتحدثون أو الأيدي المرفوعة.

النية: VOICE_STATES · id, data

SoundboardPlay

شغّل أحدهم صوتًا من لوحة الأصوات في قناة صوتية.

النية: VOICE_STATES · channel_id, sound_id, user

VoiceCallUpdate

بدأت مكالمة في قناة أو انتهت.

النية: VOICE_STATES · initiator_id, channel_id, started_at, ended

InteractionCreate

استخدم أحدهم أمرًا أو زرًا أو قائمة أو نموذجًا أو إكمالًا تلقائيًا لهذا البوت. انظر صفحة الأوامر والتفاعلات.

النية: INTERACTIONS · interaction

ApplicationCommandsUpdate

غيّر تطبيق أوامره في هذا السيرفر. يستخدمه التطبيق لإعادة تحميل القائمة، ويستطيع البوت تجاهله.

النية: SERVERS · application_id, server_id

الأنواع

الكائنات المذكورة في الجداول أعلاه. التواريخ نص ISO 8601، والمعرّفات بطول 26 حرفًا. أوصاف الأنواع مأخوذة من الواجهة وتبقى بالإنجليزية.

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

القنوات والرسائل الخاصة

تذكر Message قناتها في channel، ولا تحمل حقل server. لتعرف أين كُتبت، ابحث عن القناة. احتفظ بالقنوات الواردة في Ready (channels) وفي ChannelCreate، وحدّثها عند ChannelUpdate، واحذفها عند ChannelDelete. وللقناة التي لا تعرفها بعد استدعِ GET /channels/{target}.

تكون الرسالة خاصة إذا كان channel_type لقناتها DirectMessage. والشخص هو المعرّف في recipients الذي ليس معرّف بوتك.

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

حين يفتح شخص رسالة خاصة مع بوتك أول مرة يصل ChannelCreate ومعه DirectMessage، قبل أي رسالة فيها. تصل الرسائل الخاصة والمجموعات إلى بوتك بنية SERVERS ودونها، في Ready وفي ChannelCreate. أما رسائلها فتحتاج إلى DIRECT_MESSAGES.