الرسائل

يرسل البوت رسائله ويعدلها ويحذفها، ويتفاعل، ويثبّت، ومع إدارة الرسائل يحذف رسائل الآخرين.

أرسل رسالة

POST /channels/{target}/messages
{
  "content": "Hello!",
  "embeds": [{ "title": "Rules", "description": "Be kind.", "colour": "#E0195F" }],
  "replies": [{ "id": "01J…", "mention": false }],
  "attachments": ["<file id from the file server>"]
}

الحدود: يسردها GET / لكل سيرفر (افتراضيًا 2000 حرف، و5 مرفقات، و10 تضمينات، و5 ردود، و20 تفاعلًا مختلفًا للرسالة).
عدم التكرار: أرسل الترويسة Idempotency-Key بقيمة فريدة. إذا أُعيد الطلب بالمفتاح نفسه لا تُرسل الرسالة مرتين.
الرسائل الصامتة: flags: 1 يرسل دون إشعارات.
التنكر: يُظهر masquerade: { name, avatar } اسمًا وصورة أخرى على الرسالة (يتطلب Masquerade، ويتطلب colour إدارة الأدوار أيضًا).
المكوّنات: أزرار وقوائم وكتل تخطيط، والبوتات وحدها ترسلها. انظر الأزرار والقوائم والنماذج.
الذكر: <@user id> يذكر مستخدمًا، و<%role id> يذكر دورًا (يتطلب Mention Roles)، و@everyone و@online يتطلبان Mention Everyone. دون الصلاحية تُرفض الرسالة كلها بالخطأ MissingPermission، ولا تُرسل دون الذكر. أما في سيرفر مستضاف ذاتيًا فيه mass_mentions_enabled = false فيُرسل ذكر الأدوار و@everyone و@online دون تنبيه أحد.
روابط القنوات: <#channel id> يعرض رابطًا إلى قناة أو موضوع، ولا ينبّه أحدًا.

الرد

يرد replies على رسائل سابقة، حتى 5. id هو الرسالة، وmention يحدد هل يصل صاحبها تنبيه، وfail_if_not_exists: false يرسل حتى لو اختفت تلك الرسالة.

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/messages" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "content": "Thanks!", "replies": [{ "id": "MESSAGE_ID", "mention": false }] }'

التعديل والحذف

يأخذ PATCH /channels/{target}/messages/{msg} الحقول content وembeds وcomponents. لا يعدّل البوت إلا رسائله. ويحذف DELETE /channels/{target}/messages/{msg} رسالة البوت، أو أي رسالة مع إدارة الرسائل. لا يرسل التعديل تنبيهًا جديدًا أبدًا.

التضمينات

التضمين بطاقة تحت الرسالة. يتطلب إرسالها صلاحية Send Embeds.

الحقل	المعنى
`title`	العنوان
`description`	نص بصيغة Markdown
`url`	العنوان الذي يشير إليه الرابط
`colour`	لون CSS، مثل `#E0195F`
`icon_url`	صورة صغيرة بجانب العنوان
`media`	معرّف ملف رفعته، يظهر صورة
`image_url`	عنوان صورة كبيرة
`thumbnail_url`	عنوان صورة صغيرة في الجانب
`author`	`name` و`url` و`icon_url`
`fields`	حتى 25، لكل منها `name` و`value` و`inline`
`footer`	`text` و`icon_url`
`timestamp`	تاريخ يظهر في الأسفل

الحقول والحدود الدقيقة في المرجع أدناه.

المرفقات

تشير الرسالة إلى الملفات بمعرّفاتها. ارفع أولًا ثم أرسل. يصلح المعرّف مرة واحدة: يجيب الاستخدام الثاني بـ404 NotFound. يتطلب الإرسال Upload Files. أما الملف الذي أعطاه شخص لبوتك عبر خيار Attachment في أمر، فقد استُخدم في ذلك الأمر؛ انظر أوامر الشرطة المائلة.

curl -X POST "https://cdn.zrzur.com/attachments" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -F "[email protected];type=text/csv"
# answer: { "id": "FILE_ID" }

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/messages" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "content": "Here it is", "attachments": ["FILE_ID"] }'

انظر الملفات للأحجام والأنواع.

اقرأ الرسائل

يعيد GET /channels/{target}/messages خمسين رسالة، أو حتى 100 مع limit. تتطلب القراءة رؤية القناة وقراءة الرسائل السابقة.

معامل الاستعلام	المعنى
`limit`	من 1 إلى 100. الافتراضي 50
`before`	معرّف رسالة: الرسائل الأقدم منها فقط
`after`	معرّف رسالة: الرسائل الأحدث منها فقط
`sort`	`Latest` (الافتراضي، الأحدث أولًا) أو `Oldest` (الأقدم أولًا). ويجيب `Relevance` بـ`InvalidOperation`
`nearby`	معرّف رسالة: الرسائل حولها ومعها هي. ويُتجاهل `before` و`after` و`sort`
`include_users`	`true` يضيف الكتّاب

الجواب قائمة رسائل. ومع include_users=true يصير كائنًا: { "messages": [...], "users": [...], "members": [...] }. ولا يوجد members إلا في قنوات السيرفرات.

لتلحق بما فاتك بعد إعادة الاتصال، اطلب ما بعد آخر رسالة لديك (after) مع sort=Oldest: تصلك الرسائل التالية بالترتيب. أما بالترتيب الافتراضي فتصلك الأحدث، وتبقى فجوة في الوسط. كرر بمعرّف آخر رسالة وصلتك حتى يعود أقل من limit.

curl "https://api.zrzur.com/channels/CHANNEL_ID/messages?after=LAST_SEEN_ID&sort=Oldest&limit=100" \
  -H "x-bot-token: YOUR_BOT_TOKEN"

البحث النصي للأشخاص فقط، وتحصل البوتات على IsBot، لأنه سيتيح لها قراءة ما تخفيه نيّات الاتصال. تستطيع البوتات سرد الرسائل المثبتة (انظر التثبيت والتفاعلات). وصندوق الإشارات للأشخاص فقط أيضًا.

الحذف الجماعي

يحذف DELETE /channels/{target}/messages/bulk حتى 100 رسالة دفعة واحدة. لا تُحذف جماعيًا الرسائل الأقدم من أسبوع، فاحذفها واحدة واحدة.

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

يفتح GET /users/{target}/dm قناة الرسائل الخاصة مع مستخدم أو يعيدها. وتعتمد قدرة البوت على الكتابة هناك على إعدادات خصوصية الشخص وحظره، انظر المستخدمون والأعضاء.

المرجع

`PUT /channels/{target}/ack/{message}`

Acknowledge Message. Lets the server and all other clients know that we've seen this message id in this channel.

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

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

`GET /channels/{target}/messages`

Fetch Messages. Fetch multiple messages.

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

`POST /channels/{target}/messages`

Send Message. Sends a message to the given channel.

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

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

Delete Message. Delete a message you've sent or one you have permission to delete.

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

`GET /channels/{target}/messages/{msg}`

Fetch Message. Retrieves a message by its id.

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

`PATCH /channels/{target}/messages/{msg}`

Edit Message. Edits a message that you've previously sent.

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

`DELETE /channels/{target}/messages/{msg}/pin`

Unpins a message. Unpins a message by its id.

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

`POST /channels/{target}/messages/{msg}/pin`

Pins a message. Pins a message by its id.

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

`GET /channels/{target}/messages/{msg}/polls/answers/{answer}/voters`

Fetch Poll Voters. People who chose an answer, oldest vote first, a page at a time (up to 100, default 50; pass the last id as after for the next page). Anyone who can read the message can see them.

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

`DELETE /channels/{target}/messages/{msg}/polls/answers/{answer}/votes/@me`

Remove a Poll Vote. Take back your choice of an answer of the poll in this message. Returns the poll with the new counts and your choice.

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

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

`PUT /channels/{target}/messages/{msg}/polls/answers/{answer}/votes/@me`

Vote on a Poll. Choose an answer of the poll in this message. On a single-choice poll it replaces your earlier choice; on a multiple-choice poll it is added to it. Needs React. Returns the poll with the new counts and your choice.

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

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

`POST /channels/{target}/messages/{msg}/polls/end`

End a Poll. Close the poll in this message now: votes stop, the results are final and a "poll ended" reply is posted. The author can end their own poll; anyone else needs Manage Messages.

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

`POST /channels/{target}/messages/forward`

Forward Message. Sends a copy of a message from another channel into this one, with its text, files and rich embeds, and a note of where it came from. You need to be able to read the original (view the channel and read its history) and to send here, with the same rules as any message you send (files need Upload Files, rich embeds need Send Embeds). A message from a mature channel goes only into another mature channel. A forwarded copy notifies nobody it mentions. A poll is forwarded as text: its question and answers, without votes.

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

الصلاحيات: Channel:ViewChannel, Channel:ReadMessageHistory, Channel:SendMessage, Channel:UploadFiles, Channel:SendEmbeds · حد المعدل: messaging, 10 / 10 s

`POST /channels/{target}/search`

Search for Messages. This route searches for messages within the given parameters: words, authors, a mentioned user, what a message has (link, file, image, video, embed, sound), a time window by id or date, and pinned. Every filter given must match. Bots may only list pinned messages (pinned: true): searching text would let a bot read messages its intents hide.

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

`POST /channels/{target}/typing`

Start Typing. Show that you are typing in a channel. Clients hide it again after a few seconds or when your message arrives. For bots without a gateway connection; connected clients send BeginTyping instead.

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

`POST /servers/{target}/messages/search`

Search for Messages in a Server. Searches the server's channels that you may read: you need to view the channel and read its history, and mature channels are for declared adults only. Other channels are left out silently, never reported. Takes the same filters as a channel search, plus channels to search only some of them. Bots may only list pinned messages (pinned: true).

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

التثبيت والتفاعلات

يضيف PUT /channels/{target}/messages/{msg}/reactions/{emoji} تفاعل البوت، ويزيله DELETE على المسار نفسه. يُكتب الرمز التعبيري في المسار بترميز URL (%F0%9F%91%8D لرمز الإعجاب)، أو بمعرّف رمز مخصص. ويثبّت POST /channels/{target}/messages/{msg}/pin رسالة. ويسرد POST /channels/{target}/search مع pinned: true الرسائل المثبتة. أما البحث الآخر فللأشخاص فقط: تحصل البوتات على IsBot، لأنه سيتيح لها قراءة ما تخفيه نيّات الاتصال.

الاستطلاعات

يمكن أن تحمل الرسالة استطلاعًا (poll في الرسالة التي ترسلها: سؤال، ومن إجابتين إلى عشر إجابات، ومدة بالساعات هي 1 أو 4 أو 8 أو 24 أو 72 أو 168 أو 336، واختيار واحد أو متعدد). يتطلب نشره صلاحيتَي إرسال الرسائل وإرسال التضمينات. تُفعَّل الاستطلاعات لكل تنصيب من الخادم على حدة (features.polls في GET /)، وحيث تكون معطّلة يجيب إرسال استطلاع بالخطأ FeatureDisabled. يُظهر poll في الرسالة عدد من اختار كل إجابة، ويسرد poll.me الإجابات التي اختارها القارئ.

لا تُرسَل أسماء المصوّتين إلى الجميع أبدًا: أحداث الاستطلاع (MessagePollVoteAdd وMessagePollVoteRemove وMessagePollEnd) تحمل الأعداد فقط. ويسرد /channels/{target}/messages/{msg}/polls/answers/{answer}/voters (GET) من اختاروا إجابة، صفحةً بعد صفحة، لكل من يستطيع قراءة الرسالة (عرض القناة وقراءة سجل الرسائل)، فالمصوّت ظاهر لكل من يسأل في القناة. لا تستطيع البوتات التصويت (IsBot)، لكنها تقرأ المصوّتين وتُنهي استطلاعاتها (/channels/{target}/messages/{msg}/polls/end, POST). ويُرَدّ على التصويت في استطلاع منتهٍ بـPollEnded.