الرد على التفاعلات

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

ما تحتاج إليه

اتصال بوابة يعمل مع نية الاتصال INTERACTIONS، أو عنوان HTTP. تعمل الأوامر في قنوات السيرفرات، وفي رسالة خاصة مع البوت لأوامره العامة التي لا تتطلب صلاحية في سيرفر. وتعمل الأزرار والقوائم والنماذج في تلك الرسالة الخاصة أيضًا، ويغيب عندها server_id وmember.

المهل الزمنية

يحمل الحدث الوقتين في respond_by وexpires_at. اتبع أوقات الحدث لا ساعتك.

إذا كان العمل يستغرق أكثر من لحظة، فرد أولًا بـDeferredMessage. يُظهر ذلك «يفكر» ويمنحك الدقائق الخمس عشرة.

إذا لم يكن بوتك متصلًا عند استخدام الأمر ضاع الحدث، ويرى الشخص الفشل بعد 3 ثوانٍ.

الحدث

{
  "type": "InteractionCreate",
  "interaction": {
    "_id": "01JC0000000000000000000013",
    "version": 1,
    "application_id": "01JC0000000000000000000001",
    "type": "Command",
    "token": "YOUR_INTERACTION_TOKEN",
    "user": { "_id": "01JC0000000000000000000012", "username": "example_user" },
    "member": { "_id": { "server": "01JC0000000000000000000003", "user": "01JC0000000000000000000012" } },
    "server_id": "01JC0000000000000000000003",
    "channel_id": "01JC0000000000000000000004",
    "user_permissions_string": "2276038022144",
    "app_permissions_string": "4398045478879",
    "locale": "ar",
    "command": { "id": "01JC0000000000000000000014", "name": "ping", "type": "ChatInput", "options": [] },
    "respond_by": "2026-11-06T07:04:12.432Z",
    "expires_at": "2026-11-06T07:19:09.432Z"
  }
}

أرقام الصلاحيات أكبر من أن تتسع لها أرقام JavaScript، فاقرأها بصيغة BigInt:

const canTimeout = (BigInt(interaction.user_permissions_string) >> 8n) & 1n;

الرد

أرسل ردًا أولًا واحدًا. لا حاجة إلى ترويسة رمز، فالمسار يحمل الرمز.

curl -X POST "https://api.zrzur.com/interactions/INTERACTION_ID/YOUR_INTERACTION_TOKEN/callback" \
  -H "content-type: application/json" \
  -d '{ "type": "Message", "data": { "content": "Pong!" } }'

يأخذ data الحقول content وembeds وcomponents وephemeral. الرد مرتين يحصل على InteractionAlreadyAcknowledged.

الردود الخاصة

يُظهر "ephemeral": true الرد لذلك الشخص فقط. لا يُخزن أبدًا في القناة، فيختفي عند إعادة التحميل. يُتخذ القرار مرة واحدة: يبقى الرد المؤجل خاصًا بالقدر الذي حددته عند التأجيل.

الردود المؤجلة

# 1. within 3 seconds
curl -X POST "https://api.zrzur.com/interactions/INTERACTION_ID/YOUR_INTERACTION_TOKEN/callback" \
  -H "content-type: application/json" \
  -d '{ "type": "DeferredMessage", "data": { "ephemeral": true } }'

# 2. within 15 minutes
curl -X PATCH "https://api.zrzur.com/interactions/INTERACTION_ID/YOUR_INTERACTION_TOKEN/original" \
  -H "content-type: application/json" \
  -d '{ "content": "Done." }'

رسائل المتابعة

بعد الرد الأول تستطيع إرسال 5 رسائل أخرى للتفاعل نفسه حتى ينتهي الرمز:

curl -X POST "https://api.zrzur.com/interactions/INTERACTION_ID/YOUR_INTERACTION_TOKEN/followups" \
  -H "content-type: application/json" \
  -d '{ "content": "One more thing.", "ephemeral": true }'

يحمل الجواب _id الرسالة الجديدة. لرسالة المتابعة خيار ephemeral الخاص بها، ولا تأتي بعد رد Modal.

الإكمال التلقائي

الخيار ذو "autocomplete": true يطلب من بوتك اقتراحات في أثناء كتابة الشخص. يسمّي command.focused الخيار، وتحمل value النص حتى الآن، بحد 100 حرف.

{
  "type": "AutocompleteResult",
  "choices": [{ "name": "Apricot", "value": "apricot" }]
}

رد بسرعة، فقد ترسل كل ضغطة مفتاح طلبًا. لا يقبل تفاعل Autocomplete إلا هذا الرد، ولا يقبله غيره.

الأخطاء الشائعة

المرجع

GET /applications/{application_id}/commands

List Global Commands. Commands of this application available in every server it is installed in.

حد المعدل: any_dlta, 20 / 10 s

POST /applications/{application_id}/commands

Create Global Command. Register a new command. A command with the same type and name is a conflict.

حد المعدل: any_dlta, 20 / 10 s

PUT /applications/{application_id}/commands

Sync Global Commands. Replace every global command with the given list, matched by type and name. The list is validated as a whole before anything changes.

حد المعدل: any_dlta, 20 / 10 s

DELETE /applications/{application_id}/commands/{command_id}

Delete Global Command.

حد المعدل: any_dlta, 20 / 10 s

GET /applications/{application_id}/commands/{command_id}

Fetch Global Command.

حد المعدل: any_dlta, 20 / 10 s

PATCH /applications/{application_id}/commands/{command_id}

Edit Global Command.

حد المعدل: any_dlta, 20 / 10 s

GET /applications/{application_id}/servers/{server_id}/commands

List Server Commands. Commands of this application limited to one server it is installed in.

حد المعدل: any_dlta, 20 / 10 s

POST /applications/{application_id}/servers/{server_id}/commands

Create Server Command.

حد المعدل: any_dlta, 20 / 10 s

PUT /applications/{application_id}/servers/{server_id}/commands

Sync Server Commands.

حد المعدل: any_dlta, 20 / 10 s

DELETE /applications/{application_id}/servers/{server_id}/commands/{command_id}

Delete Server Command.

حد المعدل: any_dlta, 20 / 10 s

GET /applications/{application_id}/servers/{server_id}/commands/{command_id}

Fetch Server Command.

حد المعدل: any_dlta, 20 / 10 s

PATCH /applications/{application_id}/servers/{server_id}/commands/{command_id}

Edit Server Command.

حد المعدل: any_dlta, 20 / 10 s

DELETE /channels/{target}/messages/{msg}/reactions

Remove All Reactions from Message. Remove your own, someone else's or all of a given reaction. Requires ManageMessages permission.

الصلاحيات: Channel:ManageMessages · حد المعدل: channels, 15 / 10 s

DELETE /channels/{target}/messages/{msg}/reactions/{emoji}

Remove Reaction(s) to Message. Remove your own, someone else's or all of a given reaction. Requires ManageMessages if changing others' reactions.

الصلاحيات: Channel:React, Channel:ManageMessages · حد المعدل: channels, 15 / 10 s

PUT /channels/{target}/messages/{msg}/reactions/{emoji}

Add Reaction to Message. React to a given message.

الصلاحيات: Channel:React · حد المعدل: channels, 15 / 10 s

POST /interactions

Create Interaction. Use an application command, a component on a bot's message, or submit a form the bot opened. The server checks every value and permission, then sends the interaction to the bot only. The answer arrives as InteractionStateUpdate plus a channel message, a message update, EphemeralMessageCreate or InteractionModal, for this user. Sending the same nonce again returns the first interaction.

غير متاح للبوتات.

حد المعدل: interactions, 15 / 10 s

POST /interactions/{interaction_id}/{token}/callback

Respond to Interaction. First answer of the bot, authenticated by the interaction token. It must arrive before respond_by and can only happen once. - Message: reply now; data.ephemeral makes it visible to the invoking user only, and it is never stored as a channel message. - DeferredMessage: show that the bot is working; finish later with PATCH /interactions/<id>/<token>/original before the token expires. - UpdateMessage / DeferredUpdate (components and forms opened from one): change the message the component is on, now or later. - Modal: open a form for the user (not as an answer to a form). - AutocompleteResult (autocomplete only): up to 25 suggestions.

حد المعدل: interaction_callbacks, 10 / 10 s

POST /interactions/{interaction_id}/{token}/followups

Send Follow-up. Another message for the same interaction, after the first answer (or while it is deferred). At most 5 per interaction.

حد المعدل: interaction_callbacks, 10 / 10 s

DELETE /interactions/{interaction_id}/{token}/messages/{message_id}

Delete Interaction Message. Delete the first answer or a follow-up by its message id. For private messages the invoking user's clients receive EphemeralMessageDelete.

حد المعدل: interaction_callbacks, 10 / 10 s

PATCH /interactions/{interaction_id}/{token}/messages/{message_id}

Edit Interaction Message. Edit the first answer or a follow-up by its message id.

حد المعدل: interaction_callbacks, 10 / 10 s

DELETE /interactions/{interaction_id}/{token}/original

Delete Original Response.

حد المعدل: interaction_callbacks, 10 / 10 s

PATCH /interactions/{interaction_id}/{token}/original

Edit Original Response. Finish a deferred interaction, or edit the answer, until the token expires. After UpdateMessage or DeferredUpdate this edits the component's message.

حد المعدل: interaction_callbacks, 10 / 10 s

POST /interactions/autocomplete

Request Autocomplete. Ask the bot for suggestions while the user types into an option with autocomplete. The suggestions arrive as InteractionAutocompleteResult. Clients should wait for a pause in typing and drop answers to older requests.

غير متاح للبوتات.

حد المعدل: interactions_autocomplete, 30 / 10 s

GET /servers/{server_id}/applications

List Server Apps. Apps installed in this server, who installed them and with which permissions.

حد المعدل: servers, 5 / 10 s

DELETE /servers/{server_id}/applications/{application_id}

Uninstall App. Remove an app's bot from the server: its membership, its managed role and its install record go; its server-scoped commands stop showing.

حد المعدل: servers, 5 / 10 s

GET /servers/{server_id}/applications/{application_id}/commands

Fetch App Commands In Server. Every command of an app that works in this server, global and limited to this server, without any filtering: for the people who manage the app's rules. Needs Manage Server.

حد المعدل: servers, 5 / 10 s

PUT /servers/{server_id}/applications/{application_id}/commands/{command_id}/permissions

Edit Command Permissions. Replace the rules for one command in this server; they come before the app's rules. An empty list removes them. Needs Manage Server and Manage Roles; see the module documentation for which rules an editor may write.

حد المعدل: servers, 5 / 10 s

GET /servers/{server_id}/applications/{application_id}/permissions

Fetch Command Permissions. The rules set in this server for an app: the whole app (no command_id) and each command that has its own.

حد المعدل: servers, 5 / 10 s

PUT /servers/{server_id}/applications/{application_id}/permissions

Edit App Permissions. Replace the rules for the whole app in this server. An empty list removes them. Needs Manage Server and Manage Roles; see the module documentation for which rules an editor may write.

حد المعدل: servers, 5 / 10 s

GET /servers/{server_id}/commands

Fetch Server Commands. Commands a member can pick from in this server: those of every bot installed here, global or limited to this server. Commands that need server permissions the member lacks, or that the server's command permission rules keep from them, are left out. With channel, the channel rules count too (a thread or forum post uses its channel's); the channel is checked again when a command is used.

حد المعدل: servers, 5 / 10 s

التالي

• الأزرار والقوائم والنماذج
• ابنِ بوتًا كاملًا