أوامر الشرطة المائلة

سجّل أوامر يكتبها الناس بصيغة /name، مع خيارات وأوامر فرعية وأسماء بلغتهم.

ما تحتاج إليه

رمز بوتك (YOUR_BOT_TOKEN) ومعرّفه (YOUR_BOT_ID). يظهر معرّف البوت في بوابة المطورين، وفي GET /users/@me باسم _id.

عام أو لكل سيرفر

يصل التغيير إلى الناس فورًا في النطاقين. استخدم سيرفر اختبار في أثناء البناء، كي لا يرى الآخرون أوامر غير مكتملة. يجب أن يكون البوت مثبتًا في ذلك السيرفر.

إذا وُجد الاسم نفسه في النطاقين، يرى الناس الأمرين.

التسجيل

يستبدل PUT القائمة كاملة. وهي أسهل طريقة لإبقاء الأوامر متوافقة مع كودك: أرسل قائمتك كلما بدأ البوت. تحتفظ الأوامر غير المتغيرة بمعرّفاتها، وتُحذف الأوامر التي تركتها.

curl -X PUT "https://api.zrzur.com/applications/YOUR_BOT_ID/commands" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '[{ "name": "ping", "description": "Check that the bot is awake" }]'

يضيف POST /applications/{application_id}/commands أمرًا واحدًا، ويغيّر PATCH /applications/{application_id}/commands/{command_id} أمرًا، ويزيل DELETE أمرًا. ودون كود، افتح تطبيقك في بوابة المطورين، تبويب الأوامر: يضيف نموذجٌ الأوامرَ ويغيّرها ويحذفها، مع الخيارات والاختيارات والأسماء بلغات أخرى ومن يحق له استخدامها، ويعرض معاينة. ويأخذ استيراد JSON وتصدير JSON هناك القائمة نفسها التي يأخذها PUT ويعطيانها. والحفظ في البوابة يستبدل القائمة العامة كما يفعل PUT، فالبوت الذي يرسل قائمته عند بدء تشغيله يكتب فوق ما حفظته.

حقول الأمر

يملأ السيرفر _id وapplication_id وversion. تتغير version مع كل تحديث، ويُطلب ممن لديه نسخة أقدم مفتوحة إعادة التحميل.

الحدود

الخيارات

{
  "name": "roll",
  "description": "Roll a die",
  "options": [
    {
      "type": "Integer",
      "name": "sides",
      "description": "How many sides",
      "required": true,
      "min_value": 2,
      "max_value": 100
    }
  ]
}

القواعد التي يفحصها السيرفر عند التسجيل:

• تأتي الخيارات required قبل الاختيارية.
• لا يجتمع choices وautocomplete.
• تبقى الأعداد ضمن 9007199254740991 كي تتسع لها JavaScript.

يفحص السيرفر الخيارات المطلوبة والحدود والاختيارات قبل أن يرى بوتك التفاعل. وقيمة User وRole وChannel وMentionable وAttachment معرّف، ويصل الكائن الكامل في command.resolved تحت users (ومعه members في السيرفر) أو roles أو channels أو attachments، مفهرسًا بذلك المعرّف.

الملفات من خيار

قيمة خيار Attachment معرّف ملف. ويصل الملف في command.resolved.attachments:

{
  "type": "Command",
  "command": {
    "name": "report",
    "options": [{ "name": "file", "type": "Attachment", "value": "FILE_ID" }],
    "resolved": {
      "attachments": {
        "FILE_ID": {
          "_id": "FILE_ID",
          "tag": "attachments",
          "filename": "screenshot.png",
          "content_type": "image/png",
          "size": 48213,
          "metadata": { "type": "Image", "width": 1280, "height": 720 }
        }
      }
    }
  }
}

نزّله من https://cdn.zrzur.com/attachments/FILE_ID/screenshot.png (أي tag ثم المعرّف ثم filename). استخدم الأمرُ المعرّفَ، فلا يصلح في رسالة بوتك: يجيب ذلك بـ404 NotFound. لتنشر الملف أرسل عنوانه، أو نزّله ثم ارفع نسخة منه.

الأوامر الفرعية

اجمع الأفعال تحت اسم واحد: /note add و/note list.

{
  "name": "note",
  "description": "Notes for this server",
  "options": [
    { "type": "SubCommand", "name": "add", "description": "Write a new note" },
    {
      "type": "SubCommandGroup",
      "name": "admin",
      "description": "For moderators",
      "options": [
        { "type": "SubCommand", "name": "clear", "description": "Delete all notes" }
      ]
    }
  ]
}

القواعد:

• يحمل SubCommand خيارات عادية، ولا يحمل SubCommandGroup إلا أوامر فرعية.
• توضع المجموعة في المستوى الأعلى، ولا يتعمق شيء أكثر من مجموعة واحدة.
• لا تختلط الأوامر الفرعية بالخيارات العادية في مستوى واحد.
• يأخذ الأمر الفرعي name وdescription وoptions، ولا شيء آخر.

يصل المسار المختار في الخيارات، والقيم داخله:

{
  "name": "note",
  "options": [
    {
      "name": "add",
      "type": "SubCommand",
      "options": [{ "name": "title", "type": "String", "value": "Hello" }]
    }
  ]
}

الأسماء بلغات أخرى

أعطِ كل نص بحسب اللغة. المفاتيح وسوم لغات: ar وde وpt-BR.

{
  "name": "ping",
  "name_localizations": { "ar": "فحص", "de": "pruefen" },
  "description": "Check that the bot is awake",
  "description_localizations": {
    "ar": "تحقق من أن البوت يعمل",
    "de": "Prüfen, ob der Bot läuft"
  }
}

تأخذ الخيارات والاختيارات الحقول نفسها. تتبع الأسماء المترجمة قواعد name نفسها، فالحروف العربية مسموحة. يحمل التفاعل دائمًا name الأساسي، فتكفي حالة واحدة في كودك لكل أمر. ويحمل أيضًا لغة الشخص في locale، فتستطيع الرد بها.

من يستطيع استخدام الأمر

default_member_permissions رقم: اجمع قيم الصلاحيات التي يحتاج إليها العضو من جدول الصلاحيات. لا يرى الأمر عضو لا يملكها كلها، ويحصل طلبه على MissingPermission. القيمة 256 هي إيقاف الأعضاء مؤقتًا، وإدارة الرسائل (8388608) مع طرد الأعضاء (64) تساوي 8388672. وفي بوابة المطورين تختار الصلاحيات من قائمة بدل ذلك. يبقى على بوتك فحص user_permissions: فقد يغيّر المسؤول الأدوار، والأمر ليس جدار أمان لما يفعله بوتك نفسه.

أوامر القوائم

يُظهر "type": "User" و"type": "Message" أمرًا في قائمة مستخدم أو رسالة. لا وصف لها ولا خيارات، ويجوز في اسمها أحرف كبيرة ومسافات. يصل الهدف في command.target_id.

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

المرجع

المسارات مذكورة في صفحة الرد على التفاعلات.

التالي

• الرد على التفاعلات
• أوامر بخيارات