التفاعلات عبر HTTP

استقبل الأوامر والأزرار والنماذج على عنوان HTTPS الخاص بك، دون اتصال بالبوابة.

ما تحتاج إليه

• Node 22 أو أحدث، وعنوان HTTPS عام.
• رمز بوتك (YOUR_BOT_TOKEN) وسر التوقيع (YOUR_SIGNING_SECRET).
• لا نيّات اتصال: تصل التفاعلات أيًا كانت نيّات البوابة.

الخطوات

1. افتح بوتك في بوابة المطورين واختر تفاعلات HTTP. أنشئ سر توقيع وانسخه. يظهر مرة واحدة.
2. شغّل المثال أدناه على سيرفرك، والسر في ZRZUR_SIGNING_SECRET.
3. أدخل عنوانك في النافذة نفسها، واحفظ وأكّد كلمة مرورك. يرسل زرزور أولًا طلبي اختبار بأي ترتيب: طلبًا بتوقيع خاطئ يجب رفضه، وPing موقعًا يجب أن يجاب بـ{"type":"Pong"}. تفعل المكتبة الأمرين عنك.

من الآن لا تستقبل البوابة تفاعلات هذا البوت. أزل العنوان للعودة.

مثال كامل

// A bot without a gateway connection: `/hello` answered over HTTP.
//
//   ZRZUR_BOT_TOKEN=... ZRZUR_SIGNING_SECRET=... PORT=8787 node http-interactions.mjs

import { Client } from "@zrzur/sdk/bot";

const bot = new Client({ apiUrl: process.env.ZRZUR_API_URL });

bot.command("hello", (i) => i.reply(`Hello ${i.user.username}, over HTTP!`));

await bot.loginHttp(process.env.ZRZUR_BOT_TOKEN);
await bot.syncCommands([{ name: "hello", description: "Say hello" }]);
await bot.listen({
  secret: process.env.ZRZUR_SIGNING_SECRET,
  port: Number(process.env.PORT ?? 8787),
});
console.log(`ready as ${bot.user.username}`);

ما يجب أن تراه

ready as <your bot> في الطرفية، ثم Hello <name>, over HTTP! في القناة عندما يستخدم أحدهم /hello.

كيف يبدو الطلب

كل طلب هو POST يحمل JSON نفسه الموجود في interaction داخل InteractionCreate، مع ثلاث ترويسات:

النص الموقّع هو v1:<timestamp>:<raw body>. دون المكتبة:

1. ارفض الطلب بـ401 إذا ابتعد الوقت عن ساعتك أكثر من 300 ثانية.
2. احسب HMAC-SHA256 للنص الموقّع بسرك وقارنه في زمن ثابت (crypto.timingSafeEqual في Node وhmac.compare_digest في Python). لا تقارن أبدًا بـ==.
3. ارفض _id من الجسم الموقّع إذا عالجته في الدقائق العشر الأخيرة: فهذا طلب مسروق أُعيد إرساله. لا تستخدم X-Zrzur-Delivery لذلك: فهو غير موقّع ويستطيع أي أحد تغييره.
4. أجب {"type":"Ping"} بـ{"type":"Pong"}.

لا يصل شيء إلى بوت معطل أو مالكه معلّق، ولا يمكن تغيير عنوانه.

تحقق بهذا المثال. مع السر zrzur_sign_f27c5773e21ddeceaeb5e956dc45c16451f737addd5c0e4472f61060bca9b030 والوقت 1700000000 والجسم {"type":"Ping"} يكون التوقيع v1=928e5ffdc88564103b59f5485a6bfa7e1a633dca64f397396606a314f572c4d3.

كيف ترد

رد خلال 3 ثوانٍ بإحدى طريقتين:

• 202 أو 204 بلا جسم، ثم استدع POST /interactions/{id}/{token}/callback كما مع البوابة. هذا ما تفعله المكتبة.
• 200 بالجسم الذي كنت سترسله إلى ذلك المسار، مثل {"type":"Message","data":{"content":"Hello"}}.

أي حالة أخرى أو انتهاء المهلة أو إعادة توجيه أو جواب يتجاوز 1 ميبيبايت يُفشل التفاعل، ويرى الشخص الفشل. لا تُتبع إعادات التوجيه.

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

يفشل حفظ العنوان بالخطأ SignedDeliveryRejected، ويبيّن reason السبب:

FeatureDisabled يعني أن هذا السيرفر بلا مفتاح توقيع مضبوط، أو مفتاحه أقل من 32 بايتًا. وInvalidOperation يعني أن البوت لا يملك سر توقيع بعد.

التالي

• الرد على التفاعلات
• الأخطاء