ابدأ ببوتك

خلال عشر دقائق تقريبًا سيكون لديك بوت يجيب عن أمر بالشرطة المائلة في سيرفر الاختبار الخاص بك. تحتاج إلى حساب في زرزور وسيرفر خاص بك وNode.js 22 أو أحدث. لا شيء آخر لتثبيته.

1. أنشئ تطبيقًا

في بوابة المطورين، اختر «تطبيق جديد» ثم أدخل اسمًا واختر «إنشاء». يأتي التطبيق مع حساب بوت. افتح تطبيقاتي

2. انسخ الرمز

يظهر الرمز مرة واحدة بعد إنشاء التطبيق مباشرة. انسخه الآن. من يملك الرمز يتحكم في البوت.

3. ثبّت البوت في سيرفر اختبار

في تبويب «نظرة عامة» لتطبيقك اختر «إضافة إلى سيرفر»، ثم اختر سيرفرًا لديك فيه صلاحية إدارة السيرفر. المزيد عن التثبيت

افعل هذا قبل التشغيل الأول. البوت الذي ليس في السيرفر يحصل على 403 MissingPermission حين يكتب في إحدى قنواته، فيبدو الأمر كأن صلاحية تنقصه. هل البوت في ذلك السيرفر؟

4. لا حاجة إلى مكتبة

يتضمن Node.js 22 كل ما تحتاج إليه: الواجهة مجرد HTTP وWebSocket. لا يمكن تنزيل المكتبة الرسمية @zrzur/sdk بعد. عن حزم التطوير

5. اكتب بوتك الأول

احفظ هذا باسم hello-raw.mjs في مجلد فارغ. إنه يسجل الأمر /hello ويجيب عنه.

// Hello World without any library: Node 22+, fetch and WebSocket only.
//
//   ZRZUR_BOT_TOKEN=YOUR_BOT_TOKEN node hello-raw.mjs

const token = process.env.ZRZUR_BOT_TOKEN;
const api = process.env.ZRZUR_API_URL ?? "https://api.zrzur.com";
const ws = process.env.ZRZUR_WS_URL ?? "wss://events.zrzur.com";

if (!token) {
  console.error("Set ZRZUR_BOT_TOKEN first.");
  process.exit(2);
}

/** An interaction's token is in its path: it must never reach a log */
const masked = (path) =>
  path.replace(/(\/interactions\/[^/]+\/)[^/]+/, "$1***");

async function rest(method, path, body) {
  const response = await fetch(api + path, {
    method,
    headers: {
      "x-bot-token": token,
      ...(body ? { "content-type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!response.ok)
    throw new Error(
      `${method} ${masked(path)}: ${response.status} ${await response.text()}`,
    );
  return response.status === 204 ? null : response.json();
}

// 1. Who am I? A bot's application id is its user id.
const me = await rest("GET", "/users/@me");

// 2. Register the global /hello command (PUT replaces the whole list).
await rest("PUT", `/applications/${me._id}/commands`, [
  { name: "hello", description: "Say hello" },
]);

// 3. Connect to the gateway and answer interactions.
const socket = new WebSocket(`${ws}/?version=1&format=json`);
// intents 33 = SERVERS (1) + INTERACTIONS (32): commands, nothing else
socket.addEventListener("open", () =>
  socket.send(JSON.stringify({ type: "Authenticate", token, intents: 33 })),
);

async function handle(event) {
  if (event.type === "Ready") console.log(`ready as ${me.username}`);
  if (
    event.type === "InteractionCreate" &&
    event.interaction.command?.name === "hello"
  ) {
    const { _id, token: interactionToken } = event.interaction;
    // answer within 3 seconds
    await rest("POST", `/interactions/${_id}/${interactionToken}/callback`, {
      type: "Message",
      data: { content: "Hello from Zrzur!" },
    });
  }
}

socket.addEventListener("message", ({ data }) => {
  const event = JSON.parse(data);
  // several events can arrive together in one Bulk packet
  for (const item of event.type === "Bulk" ? event.v : [event])
    handle(item).catch(console.error);
});

// keep the connection alive
setInterval(
  () => socket.send(JSON.stringify({ type: "Ping", data: Date.now() })),
  20_000,
);

6. شغّله

اضبط الرمز، ثم شغّل البوت:

mkdir my-bot
cd my-bot
# save hello-raw.mjs here, then:
export ZRZUR_BOT_TOKEN=YOUR_BOT_TOKEN
node hello-raw.mjs

حين تظهر كلمة ready في الطرفية، اكتب /hello في قناة من سيرفر الاختبار. سيجيب البوت: Hello from Zrzur!

7. استقبل الأحداث

يحافظ البوت على اتصال WebSocket بالبوابة. وتصل عبره الأوامر ونقرات الأزرار والرسائل الجديدة وتغييرات الأعضاء على شكل أحداث. البوابة

8. ابنِ بوتًا حقيقيًا

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

الخطوات التالية

• أوامر الشرطة المائلة
• الأزرار والقوائم والنماذج
• الأخطاء
• حدود المعدل