Zalo

الحالة: تجريبية. تم تنفيذ كلٍ من الرسائل المباشرة ومحادثات المجموعات؛ ويعكس جدول الإمكانات أدناه السلوك المتحقق منه في روبوتات Zalo Bot Creator / Marketplace.

Plugin المضمّن

يأتي Zalo بوصفه Plugin مضمّنًا في إصدارات OpenClaw الحالية، لذا لا تحتاج الحزم المبنية إلى تثبيت منفصل.

في إصدار أقدم أو تثبيت مخصص يستبعد Zalo، ثبّت حزمة npm مباشرةً:

• التثبيت: openclaw plugins install @openclaw/zalo
• إصدار مثبّت: openclaw plugins install @openclaw/zalo@2026.6.11
• من نسخة محلية: openclaw plugins install ./path/to/local/zalo-plugin
• التفاصيل: الإضافات

الإعداد السريع

1. أنشئ رمز روبوت في https://bot.zaloplatforms.com (سجّل الدخول، وأنشئ روبوتًا، واضبط الإعدادات). يكون الرمز بالصيغة numeric_id:secret؛ وبالنسبة إلى روبوتات Marketplace، قد يظهر رمز وقت التشغيل القابل للاستخدام في رسالة الترحيب الخاصة بالروبوت.
2. عيّن الرمز إما في متغير البيئة ZALO_BOT_TOKEN=... (للحساب الافتراضي فقط) أو في الإعدادات.
3. أعد تشغيل Gateway.
4. وافق على رمز الاقتران عند أول تواصل عبر رسالة مباشرة (سياسة الرسائل المباشرة الافتراضية هي الاقتران).

الحد الأدنى من الإعدادات:

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

الحسابات المتعددة: أضف مزيدًا من الإدخالات ضمن channels.zalo.accounts.<id>، ولكلٍ منها botToken وname خاصان به. يُعد channels.zalo.botToken (مسطحًا، من دون accounts) اختصارًا قديمًا لحساب واحد؛ فضّل accounts.<id>.* في الإعدادات الجديدة.

ما هو

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

تتناول هذه الصفحة روبوتات Zalo Bot Creator / Marketplace. أما روبوتات Zalo Official Account (OA) فهي واجهة منتج مختلفة وقد تتصرف على نحو مختلف؛ ولا تتناولها هذه الصفحة.

آلية العمل

• تُطبَّع الرسائل الواردة إلى غلاف القناة المشترك مع عناصر نائبة للوسائط.
• تُوجَّه الردود دائمًا إلى محادثة Zalo نفسها؛ ولا يُستخدم الرد المقتبس (replyToMode معطّل دائمًا).
• يُستخدم الاستقصاء الطويل (getUpdates) افتراضيًا؛ ويتوفر وضع Webhook عبر channels.zalo.webhookUrl.
• تتطلب المجموعات إشارة @ لتشغيل الروبوت؛ ولا يمكن ضبط ذلك لكل قناة.

الحدود

التحكم في الوصول

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

• channels.zalo.dmPolicy: ‏pairing (الافتراضي) | allowlist | open | disabled.
• الاقتران: يحصل المرسلون غير المعروفين على رمز اقتران؛ وتُتجاهل الرسائل حتى تتم الموافقة. تنتهي صلاحية الرموز بعد ساعة واحدة.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • التفاصيل: الاقتران
• يقبل channels.zalo.allowFrom معرّفات مستخدمي Zalo الرقمية (لا يوجد بحث باسم المستخدم). يتطلب open القيمة "*".

المجموعات

يدعم Plugin محادثات المجموعات (chatTypes: ["direct", "group"])، ويخضع تشغيلها للإشارة ولسياسة المجموعة:

• channels.zalo.groupPolicy: ‏open | allowlist | disabled.
• يقيّد channels.zalo.groupAllowFrom معرّفات المرسلين الذين يمكنهم تشغيل الروبوت في المجموعات؛ ويعود إلى allowFrom عند عدم تعيينه.
• الحل الافتراضي: عند إعداد channels.zalo، تُحل قيمة groupPolicy غير المعيّنة إلى open. وعند غياب channels.zalo بالكامل، يفشل وقت التشغيل بصورة مغلقة إلى allowlist.
• تنبيه مُبلّغ عنه من الاستخدام الفعلي: في بعض إعدادات روبوتات Marketplace، تعذّر إضافة الروبوت إلى أي مجموعة. إذا واجهت ذلك، فتحقق من إعدادات Zalo Bot Platform الخاصة بروبوتك؛ فهذا قيد من المنصة، وليس سياسة في OpenClaw.

الاستقصاء الطويل مقارنةً بـ Webhook

• الافتراضي: الاستقصاء الطويل (لا يلزم عنوان URL عام).
• وضع Webhook: عيّن channels.zalo.webhookUrl وchannels.zalo.webhookSecret.
  • يجب أن يستخدم عنوان URL الخاص بـ Webhook بروتوكول HTTPS.
  • يجب أن يتراوح طول سر Webhook بين 8 و256 محرفًا.
  • يرسل Zalo الأحداث مع ترويسة X-Bot-Api-Secret-Token، ويُتحقق منها بمقارنة ثابتة الزمن.
  • تعالج واجهة HTTP في Gateway طلبات Webhook عند channels.zalo.webhookPath (المسار الافتراضي هو مسار عنوان URL الخاص بـ Webhook).
  • يجب أن تستخدم الطلبات Content-Type: application/json (أو نوع وسائط +json).
  • يتنافى استقصاء getUpdates مع Webhook لكل حساب وفقًا لوثائق Zalo API.

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

• النص: دعم كامل، مع تقسيمه إلى أجزاء من 2000 محرف.
• الوسائط: واردة وصادرة، بحد أقصى يحدده mediaMaxMb.
• التفاعلات، وسلاسل المحادثات، والاستطلاعات، والأوامر الأصلية: لا يدعمها Plugin.
• البث: يعلن Plugin إمكانية البث على شكل كتل، لكن Zalo لا يوفر إعدادات مخصصة لضبط طابور الإرسال أو دمج النصوص (على خلاف بعض القنوات الإقليمية الأخرى)؛ تحقق من السلوك الحالي في بيئتك إذا كان ذلك مهمًا لحالة استخدامك.

الإمكانات

أهداف التسليم (CLI/Cron)

استخدم معرّف محادثة بوصفه الهدف:

openclaw message send --channel zalo --target 123456789 --message "hi"

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

الروبوت لا يستجيب:

• تحقق من الرمز: openclaw channels status --probe
• تحقق من الموافقة على المرسل (عبر الاقتران أو allowFrom)
• تحقق من سجلات Gateway: ‏openclaw logs --follow

Webhook لا يستقبل الأحداث:

• تأكد من أن عنوان URL الخاص بـ Webhook يستخدم HTTPS
• تأكد من أن طول السر يتراوح بين 8 و256 محرفًا
• تأكد من إمكانية الوصول إلى نقطة نهاية HTTP في Gateway عبر المسار المضبوط
• تأكد من أن استقصاء getUpdates لا يعمل أيضًا (فهما متنافيان)
• قد تؤدي دفعة كبيرة من الطلبات إلى إرجاع HTTP 429 (‏120 طلبًا / 60 ثانية لكل مسار+عنوان IP)؛ انتظر ثم أعد المحاولة

مرجع الإعدادات

الإعدادات الكاملة: الإعدادات

تُعد channels.zalo.botToken وchannels.zalo.dmPolicy والمفاتيح المسطحة الأخرى ذات المستوى الأعلى اختصارات قديمة لحساب واحد للحقول المذكورة أعلاه؛ ويُدعم كلا الشكلين.

خيار البيئة: يحل ZALO_BOT_TOKEN=... رمز الحساب الافتراضي فقط.

ذو صلة

• نظرة عامة على القنوات - جميع القنوات المدعومة
• الاقتران - مصادقة الرسائل المباشرة وتدفق الاقتران
• المجموعات - سلوك محادثات المجموعات واشتراط الإشارة
• توجيه القنوات - توجيه جلسات الرسائل
• الأمان - نموذج الوصول والتحصين