Zalo (Bot API) - قناة دردشة

Zalo هو تطبيق مراسلة يركز على فيتنام؛ يتيح Bot API الخاص به لـ Gateway تشغيل بوت للمحادثات الفردية. إنه مناسب تماماً للدعم أو الإشعارات حيث تريد توجيهاً حتمياً إلى Zalo.

مكون إضافي مطلوب

Zalo يأتي كمكون إضافي وليس مجمعاً مع التثبيت الأساسي.

• التثبيت عبر CLI: openclaw plugins install @openclaw/zalo
• أو اختر Zalo أثناء الإعداد وقم بتأكيد مطالبة التثبيت

الإعداد السريع (للمبتدئين)

1. تثبيت مكون Zalo الإضافي:

   openclaw plugins install @openclaw/zalo

2. تعيين الرمز:

   Env: ZALO_BOT_TOKEN=...

   أو config: channels.zalo.botToken: "..."

3. إعادة تشغيل Gateway (أو إنهاء الإعداد).
4. الوصول للرسائل المباشرة هو pairing افتراضياً؛ وافق على رمز الاقتران عند أول اتصال.

التكوين البسيط

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

ما هو Zalo؟

• قناة Zalo Bot API مملوكة لـ Gateway.
• التوجيه الحتمي: الردود تعود إلى Zalo؛ النموذج لا يختار القنوات أبداً.
• الرسائل المباشرة تشارك جلسة الوكيل الرئيسية.
• المجموعات غير مدعومة حالياً (وثائق Zalo تقول "قريباً").

الإعداد (المسار السريع)

1) إنشاء رمز بوت (منصة Zalo Bot)

• اذهب إلى bot.zaloplatforms.com وقم بتسجيل الدخول.
• أنشئ بوت جديد وقم بتكوين إعداداته.
• انسخ رمز البوت (تنسيق: 12345689:abc-xyz).

2) تكوين الرمز (env أو config)

مثال:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

خيار Env: ZALO_BOT_TOKEN=... (يعمل للحساب الافتراضي فقط).

دعم متعدد الحسابات: استخدم channels.zalo.accounts مع رموز لكل حساب واسم اختياري.

• إعادة تشغيل Gateway. يبدأ Zalo عند حل الرمز (env أو config).
• الوصول للرسائل المباشرة يُعيّن افتراضياً على pairing. وافق على الرمز عند أول اتصال بالبوت.

كيف يعمل (السلوك)

• يتم تطبيع الرسائل الواردة في مظروف القناة المشتركة مع علامات مكان الوسائط.
• الردود تتوجه دائماً إلى نفس محادثة Zalo.
• Long-polling افتراضياً؛ وضع webhook متاح مع channels.zalo.webhookUrl.

الحدود

• يتم تقسيم النص الصادر إلى 2000 حرف (حد Zalo API).
• تنزيلات/رفع الوسائط محددة بـ channels.zalo.mediaMaxMb (افتراضي 5).
• البث المباشر محظور افتراضياً بسبب حد 2000 حرف مما يجعل البث أقل فائدة.

التحكم في الوصول (الرسائل المباشرة)

الوصول للرسائل المباشرة

افتراضياً: channels.zalo.dmPolicy = "pairing". المرسلون غير المعروفون يتلقون رمز اقتران؛ يتم تجاهل الرسائل حتى الموافقة (تنتهي صلاحية الرموز بعد ساعة واحدة).

الموافقة عبر:

openclaw pairing list zalo
openclaw pairing approve zalo <CODE>

الاقتران هو تبادل الرمز الافتراضي.

channels.zalo.allowFrom يقبل معرفات المستخدمين الرقمية (لا يتوفر البحث عن اسم المستخدم).

Long-polling مقابل webhook

• افتراضياً: long-polling (لا حاجة لعنوان URL عام).
• وضع Webhook: اضبط channels.zalo.webhookUrl و channels.zalo.webhookSecret.
• يجب أن يكون سر webhook من 8-256 حرفاً.
• يجب أن يستخدم URL webhook HTTPS.
• Zalo يرسل الأحداث مع رأس X-Bot-Api-Secret-Token للتحقق.
• Gateway HTTP يتعامل مع طلبات webhook في channels.zalo.webhookPath (يتم تعيينه افتراضياً إلى مسار URL webhook).

أنواع الرسائل المدعومة

• الرسائل النصية: دعم كامل مع تقسيم 2000 حرف.
• رسائل الصور: تنزيل ومعالجة الصور الواردة؛ إرسال الصور عبر sendPhoto.
• الملصقات: مسجلة لكن غير معالجة بالكامل (لا استجابة من الوكيل).
• الأنواع غير المدعومة: مسجلة (مثل، رسائل من مستخدمين محميين).

القدرات

استكشاف الأخطاء وإصلاحها