القنوات والويب هوك

لكل قناة سيرفر channel_type: "TextChannel": النصية، والصوتية (مع voice)، وقناة الإعلانات، والمنتدى (مع forum)، والموضوع (مع parent وthread). ويرى البوت أيضًا الرسائل الخاصة التي هو طرف فيها (DirectMessage). المجموعات للأشخاص فقط. يسرد مرجع الأحداث الحقول، ويبيّن كيف تميّز الرسالة الخاصة من قناة السيرفر.

تستخدم الأمثلة HTTP مباشرة. أما أسطر الحزمة بعدها فتحتاج إلى الحزمة، وهي غير منشورة بعد؛ انظر الحزم البرمجية.

أنشئ القنوات وغيّرها

ينشئ POST /servers/{server}/channels قناة (يتطلب إدارة القناة). هذه قناة تذاكر للفريق فقط داخل فئة:

curl -X POST "https://api.zrzur.com/servers/SERVER_ID/channels" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "type": "Text", "name": "ticket-0001", "description": "Support ticket", "category": "CATEGORY_ID", "private": true }'

الحقل	المعنى
`type`	`Text` (الافتراضي) أو `Voice` أو `Forum`
`name`	من 1 إلى 32 حرفًا
`description`	حتى 1024 حرفًا
`nsfw`	للبالغين فقط
`announcement`	القنوات النصية: لا ينشر فيها إلا من لديه إدارة الرسائل
`category`	معرّف فئة في هذا السيرفر. تتبع القناة صلاحيات الفئة. والفئة التي ليست في السيرفر تجيب بـ`404 NotFound` ولا يُنشأ شيء
`private`	`true` يمنع رؤية القناة عن `@everyone` في هذه القناة، ولا تتبع القناة صلاحيات فئتها. وتبقى الأدوار التي لها رؤية القناة، في السيرفر أو في هذه القناة، ترى القناة

الجواب هو القناة الجديدة. تأكد أن لأحد أدوار بوتك رؤية القناة، وإلا فلن يستطيع بوتك استخدام قناة خاصة أنشأها. ولتُدخل الفريق أعطِ دوره رؤية القناة فيها عبر PUT /channels/{target}/permissions/{role_id}.

يغيّر PATCH /channels/{target} الاسم أو الوصف أو الوضع البطيء أو علامة البالغين أو الأيقونة.
يحذف DELETE /channels/{target} قناة السيرفر، ويغلق الرسالة الخاصة عند البوت.
يضبط PUT /channels/{target}/permissions/{role_id} و.../default تجاوزات القناة (يتطلب إدارة الصلاحيات). انظر الأدوار والصلاحيات.

لا تقبل قنوات الإعلانات رسائل إلا من أعضاء لديهم إدارة الرسائل.

المواضيع

الموضوع قناة داخل قناة نصية ويستخدم صلاحيات تلك القناة. ابدأه باسم ورسالة أولى:

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/threads" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "Release", "content": "First message" }'

الجواب هو الموضوع: قناة فيها parent. لذلك يكتب فيه POST /channels/{target}/messages. يسردها GET /channels/{target}/threads، ويؤرشف PATCH /channels/{target}/thread موضوعًا أو يقفله.

يبدأ POST /channels/{target}/threads موضوعًا من رسالة (message)، أو برسالة أولى (content)، أو فارغًا (name فقط). تعيد الرسالة الجديدة فتح الموضوع المؤرشف. ويتطلب القفل إدارة الرسائل.

تتبع الرسالة الأولى قواعد كل رسالة يرسلها بوتك:

تأخذ content (حتى 2000 حرف) وembeds وcomponents. وتُتجاهل حقول الرسالة الأخرى، مثل attachments، دون خطأ. تحتاج التضمينات إلى صلاحية إرسال التضمينات. ويبقى منشور المنتدى محتاجًا إلى content.
تسري صلاحية إرسال الرسائل وقواعد الذكر. ذكر دور دون Mention Roles، أو @everyone دون Mention Everyone، يرفض الطلب كله بـ403 MissingPermission، ولا يبقى موضوع. يُنشأ الموضوع أولًا ثم يُزال، فقد يصل بوتك ChannelCreate ثم ChannelDelete له. ابدأ الموضوع دون الذكر، ثم اذكر في رسالة ثانية.
في سيرفر مستضاف ذاتيًا ضبط مشغّله mass_mentions_enabled = false لا يُرفض ذكر الأدوار و@everyone و@online: تُرسل الرسالة ولا يُنبَّه أحد.

يمكن أن تكون بطاقة بأزرار هي الرسالة الأولى في الموضوع:

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/threads" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "ticket-0001", "embeds": [{ "title": "Ticket 0001", "description": "Opened by <@USER_ID>" }], "components": [{ "type": "ActionRow", "components": [{ "type": "Button", "style": "Danger", "label": "Close ticket", "custom_id": "ticket:close" }] }] }'
# answer: { "_id": "THREAD_ID", "channel_type": "TextChannel", "parent": "CHANNEL_ID", ... }

بالحزمة:

const thread = await bot.threads.create(channelId, { name: "Release", content: "First message" });
await bot.messages.send(thread._id, "In the thread");
await bot.threads.list(channelId);
await bot.threads.archive(thread._id);

ثلاث صلاحيات تحدد من يبدأ ومن يكتب. تُقرأ كل منها من القناة الأم مع تجاوزاتها، وتلزم معها صلاحية إرسال الرسائل: CreateThreads لبدء موضوع في قناة نصية، وCreateForumPosts لبدء منشور في منتدى، وSendMessageInThreads للكتابة في المواضيع ومنشورات المنتديات. وبدونها يكون الرد MissingPermission. واستخدام أمر بوت في موضوع يُعدّ كتابة فيه.

يمكن للسيرفر إيقاف المواضيع أو المنتديات عبر threads_disabled وforums_disabled في PATCH /servers/{target}. عندها لا يمكن لأحد إضافة شيء، حتى المالك: تُرد الرسائل والتعديلات والتفاعلات والتثبيت بالخطأ ThreadsDisabled أو ForumsDisabled. ويبقى كل شيء متاحًا للقراءة، ويظل بإمكان الأعضاء حذف رسائلهم وإزالة التفاعلات.

المنتديات

لا يحمل المنتدى إلا منشورات. كل منشور موضوع له عنوان ورسالة أولى وحتى خمسة وسوم. أنشئ منتدى بـ"type": "Forum" في POST /servers/{server}/channels، وانشر فيه:

curl -X POST "https://api.zrzur.com/channels/FORUM_ID/threads" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "How do I start?", "content": "Read the guide.", "tags": ["help"] }'

يحتاج المنشور إلى content، ويجب أن تكون tags من وسوم ذلك المنتدى. بالحزمة:

const forum = await bot.forums.create(serverId, { name: "questions" });
await bot.forums.setTags(forum._id, [{ id: "help", name: "Help" }], { required: true });
await bot.forums.post(forum._id, { title: "How do I start?", content: "Read the guide.", tags: ["help"] });

الدعوات

تنشئ البوتات الدعوات وتديرها كالأشخاص وبالصلاحيات نفسها: دعوة الآخرين للإنشاء، وإدارة السيرفر للسرد والحذف. ولا تنضم بها أبدًا: يجيب ذلك بـIsBot.

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/invites" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "max_uses": 3 }'

يحمل الجواب رمز الدعوة في _id. يسردها GET /servers/{target}/invites، ويحذف DELETE /invites/{target} واحدة. بالحزمة:

const invite = await bot.invites.create(channelId, { max_uses: 3 });
await bot.invites.list(serverId);
await bot.invites.delete(invite._id);

الكتابة

يُظهر POST /channels/{target}/typing عبارة «يكتب…» لبضع ثوانٍ، بحد 5 كل 10 ثوانٍ لكل قناة. ويستخدم bot.typing(channelId) في الحزمة البوابةَ عند الاتصال، وهذا المسار دونه.

الويب هوك

ينشر الويب هوك في قناة واحدة دون اتصال بالبوابة. أنشئه برمز البوت أو في إعدادات السيرفر (يتطلب إدارة الويب هوك). يحمل الجواب token وurl. يظهران مرة واحدة: لا يحفظ السيرفر سوى بصمة، فاحفظهما الآن. لا يمكن إلا استبدال الرمز المفقود.

curl -X POST "https://api.zrzur.com/webhooks/$WEBHOOK_ID/$WEBHOOK_TOKEN?wait=true" \
  -H "content-type: application/json" \
  -d '{"content": "Build finished", "username": "CI"}'

يستطيع أي شخص يملك العنوان النشر، فعامله ككلمة مرور. تبدأ الرموز بـzrzur_wh_ لتجدها أدوات فحص الأسرار إن تسربت. ينشئ POST /webhooks/{webhook_id}/token رمزًا جديدًا، ويتوقف القديم فورًا.

الإرسال

يجيب POST /webhooks/{webhook_id}/{token} بـ204. ومع ?wait=true يعيد الرسالة.

الحقل	المعنى
`content`	حتى 2000 حرف. تحتاج الرسالة إلى واحد على الأقل من `content` و`embeds` و`attachments` و`components`
`username`	الاسم على هذه الرسالة، من 1 إلى 80 حرفًا. تبقى علامة الويب هوك
`avatar_url`	الصورة على هذه الرسالة، عنوان ويب عام. تحمّلها التطبيقات عبر وسيط الوسائط الذي يفحصها
`embeds`	حتى 10، و6000 حرف إجمالًا. يُتجاهل `type`: التضمينات غنية دائمًا
`allowed_mentions`	أي إشارات يحق لها التنبيه. يوقفها `{ "parse": [] }` كلها
`flags`	`4` يخفي معاينة الروابط، و`4096` يرسل دون إشعار
`thread_id`	معامل استعلام: انشر في هذا الموضوع من قناة الويب هوك
`thread_name`	المنتدى: ابدأ موضوعًا بهذا الاسم. يضبط `applied_tags` وسومه. يجيب المنتدى دون أيهما بـ`ForumThreadRequired`

تأخذ التضمينات title (256) وdescription (4096) وurl وcolor (رقم) أو colour (نص CSS) وtimestamp وauthor (الاسم 256) وfooter (النص 2048) وحتى 25 من fields (الاسم 256 والقيمة 1024) وimage.url وthumbnail.url.

لإرسال الملفات استخدم multipart/form-data مع files[0] وfiles[1] وهكذا، وجسم JSON في payload_json. يمر كل ملف بفحوص رفع العضو نفسها. حتى 5 ملفات بحجم 20 ميغابايت، وأشر إلى أحدها من تضمين بـattachment://name.png. يحصل الويب هوك دون Upload Files على 403، ولا تُرسل رسالته ناقصة ملفاتها أبدًا.

لا تنبّه @everyone و@online وإشارات الأدوار الناس إلا إذا كان للويب هوك الصلاحية المناسبة وسمح allowed_mentions بذلك. لا يملك الويب هوك الجديد أيًا منهما، ويُنشر النص مع ذلك. ولا تنبّه التعديلات أحدًا.

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

تعديل الويب هوك

يغيّر PATCH /webhooks/{webhook_id} مع إدارة الويب هوك الاسم والصورة والصلاحيات والقناة، ويقبل X-Audit-Log-Reason. وبالرمز، لا يغيّر PATCH /webhooks/{webhook_id}/{token} سوى الاسم والصورة، ويجيب permissions أو channel_id هناك بـ403. يترك GET بالرمز ذكر من أنشأه. للأسماء من 1 إلى 80 حرفًا، ولا تحمل أحرفًا مخفية ولا تنتحل زرزور أو فريقه أو بوتًا موثقًا.

رسائله الخاصة

تعمل GET وPATCH وDELETE /webhooks/{webhook_id}/{token}/messages/{message_id} على الرسائل التي أرسلها هذا الويب هوك فقط.

يحتاج الويب هوك في الموضوع إلى SendMessageInThreads، وإلى CreateForumPosts لبدء منشور في منتدى. وما تمنعه أدوار منشئه يُمنع عنه أيضًا. وحيث تكون المواضيع أو المنتديات متوقفة لا يمكنه الإرسال أو التعديل، لكن يمكنه حذف رسائله.

الحدود

لكل قناة حتى 15 ويب هوك (TooManyChannelWebhooks) ولكل سيرفر حتى 1000 (TooManyServerWebhooks).

يرسل الويب هوك الواحد 5 رسائل في ثانيتين، وكل ويب هوك قناة واحدة 30 رسالة في الدقيقة. فوق ذلك يكون الجواب 429 مع { "type": "RateLimited", "retry_after": 1200, "global": false } (بالميلي ثانية) والترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset-After وRetry-After. بعد 20 رمزًا خاطئًا في الدقيقة ينتظر العنوان، حتى برمز صحيح.

يقرأ الإشراف الآلي رسائل الويب هوك وتضميناتها، حتى عند التعديل. ويستطيع المشرفون حذفها والإبلاغ عنها كأي رسالة.

صيغ أخرى

يأخذ POST /webhooks/{webhook_id}/{token}/github تسليمات GitHub: اضبط نوع المحتوى على application/json أو form. يعرض commit_comment وcreate وdelete وfork وissue_comment وissues وmember وpublic وpull_request وpull_request_review وpull_request_review_comment وpush وrelease وwatch وcheck_run وcheck_suite وdiscussion وdiscussion_comment وstar. ويجيب كل حدث آخر بـ204.
يأخذ POST /webhooks/{webhook_id}/{token}/slack الحقول text وattachments وblocks وusername وicon_url. ويعيد الرسالة إلا مع ?wait=false.

لا ينبّه شيء من هاتين الصيغتين أحدًا.

المرجع

`GET /channels/{channel_id}/webhooks`

Gets all webhooks. Gets all webhooks inside the channel. Their tokens are not included.

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

`POST /channels/{channel_id}/webhooks`

Creates a webhook. Creates a webhook which 3rd party platforms can use to send messages

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

`DELETE /channels/{group_id}/recipients/{member_id}`

Remove Member from Group. Removes a user from the group.

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

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

`PUT /channels/{group_id}/recipients/{member_id}`

Add Member to Group. Adds another user to the group.

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

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

`DELETE /channels/{target}`

Close Channel. Deletes a server channel, leaves a group or closes a group.

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

`GET /channels/{target}`

Fetch Channel. Fetch channel by its id.

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

`PATCH /channels/{target}`

Edit Channel. Edit a channel object by its id.

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

`POST /channels/{target}/invites`

Create Invite. Creates an invite to this channel. Channel must be a TextChannel.

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

`GET /channels/{target}/members`

Fetch Group Members. Retrieves all users who are part of this group. This may not return full user information if users are not friends but have mutual connections.

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

`PATCH /channels/{target}/thread`

Edit Thread. Rename, archive, reopen or tag a thread: its owner or anyone who can manage messages. Locking (only moderators write) needs Manage Messages.

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

`GET /channels/{target}/threads`

Threads Of A Channel. Active threads (or archived ones with archived=true), newest first, 50 per page (limit up to 100); before is a thread id.

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

`POST /channels/{target}/threads`

Start Thread. Start a thread in a text channel, from a message or with a first message, or a post in a forum (a title, a first message and its tags). Needs Send Messages in the channel, and Create Threads (Create Forum Posts in a forum). Refused with ThreadsDisabled or ForumsDisabled when the server has them switched off.

الصلاحيات: Channel:SendMessage, Channel:CreateForumPosts, Channel:CreateThreads, Channel:ReadMessageHistory · حد المعدل: channels, 15 / 10 s

`POST /channels/create`

Create Group. Create a new group channel.

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

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

`GET /servers/{target}/webhooks`

Gets a server's webhooks. Webhooks of every channel of the server where you have Manage Webhooks, newest first. Their tokens are not included.

الصلاحيات: Channel:ManageWebhooks · حد المعدل: servers, 5 / 10 s

`DELETE /webhooks/{webhook_id}`

Deletes a webhook. Deletes a webhook

الصلاحيات: Channel:ManageWebhooks · حد المعدل: any_dlta, 20 / 10 s

`GET /webhooks/{webhook_id}`

Gets a webhook. Gets a webhook, for those who may manage it. Its token is never included.

الصلاحيات: Channel:ManageWebhooks · حد المعدل: any_dlta, 20 / 10 s

`PATCH /webhooks/{webhook_id}`

Edits a webhook. Edits a webhook: name, avatar, permissions, channel. Moving it needs Manage Webhooks in both channels, within the same server.

الصلاحيات: Channel:ManageWebhooks · حد المعدل: any_dlta, 20 / 10 s