​

Zalo (Bot API)

​

الإضافة المضمنة

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

​

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

1. تأكد من أن إضافة Zalo متوفرة.
   • تتضمنها بالفعل إصدارات OpenClaw المجمعة الحالية.
   • يمكن لعمليات التثبيت القديمة/المخصصة إضافتها يدويًا باستخدام الأوامر أعلاه.
2. اضبط الرمز المميز:
   • Env: ZALO_BOT_TOKEN=...
   • أو في الإعدادات: channels.zalo.accounts.default.botToken: "...".
3. أعد تشغيل البوابة (أو أكمل الإعداد).
4. يكون الوصول عبر الرسائل الخاصة في وضع الاقتران افتراضيًا؛ وافق على رمز الاقتران عند أول تواصل.

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

​

ما هو

• قناة Zalo Bot API تملكها البوابة.
• توجيه حتمي: تعود الردود إلى Zalo؛ ولا يختار النموذج القنوات.
• تشارك الرسائل الخاصة الجلسة الرئيسية للوكيل.
• يوضح قسم الإمكانات أدناه الدعم الحالي لبوتات Marketplace.

​

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

​

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

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

​

2) إعداد الرمز المميز (env أو config)

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

3. أعد تشغيل البوابة. يبدأ Zalo عند حل الرمز المميز (من env أو config).
4. يكون الوصول عبر الرسائل الخاصة مضبوطًا افتراضيًا على الاقتران. وافق على الرمز عند أول تواصل مع البوت.

​

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

• تُطبَّع الرسائل الواردة إلى غلاف القناة المشترك مع عناصر نائبة للوسائط.
• تُوجَّه الردود دائمًا إلى دردشة 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 معرّفات مستخدمين رقمية (لا يتوفر بحث باسم المستخدم).

​

التحكم في الوصول (المجموعات)

• يتحكم channels.zalo.groupPolicy في معالجة الرسائل الواردة من المجموعات: open | allowlist | disabled.
• يقيّد channels.zalo.groupAllowFrom معرّفات المرسلين الذين يمكنهم تشغيل البوت في المجموعات.
• إذا لم يتم تعيين groupAllowFrom، فيرجع Zalo إلى allowFrom لفحوصات المرسلين.
• ملاحظة وقت التشغيل: إذا كان channels.zalo مفقودًا بالكامل، فإن وقت التشغيل لا يزال يرجع إلى groupPolicy="allowlist" من أجل الأمان.

• groupPolicy: "disabled" — يحظر جميع رسائل المجموعات.
• groupPolicy: "open" — يسمح لأي عضو في المجموعة (مع تقييد بالإشارة).
• groupPolicy: "allowlist" — افتراضي مغلق الفشل؛ لا يتم قبول سوى المرسلين المسموح لهم.

​

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 للتحقق.
  • يتولى HTTP الخاص بالبوابة معالجة طلبات webhook عند channels.zalo.webhookPath (الافتراضي هو مسار عنوان URL الخاص بـ webhook).
  • يجب أن تستخدم الطلبات Content-Type: application/json (أو أنواع وسائط +json).
  • يتم تجاهل الأحداث المكررة (event_name + message_id) خلال نافذة إعادة تشغيل قصيرة.
  • يتم تطبيق تحديد معدل على الاندفاعات المرورية لكل مسار/مصدر وقد تعيد HTTP 429.

​

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

• الرسائل النصية: دعم كامل مع تجزئة عند 2000 حرف.
• عناوين URL العادية في النص: تتصرف مثل الإدخال النصي العادي.
• معاينات الروابط / بطاقات الروابط الغنية: راجع حالة بوتات Marketplace في الإمكانات؛ إذ لم تكن تستثير ردًا بشكل موثوق.
• رسائل الصور: راجع حالة بوتات Marketplace في الإمكانات؛ كانت معالجة الصور الواردة غير موثوقة (مؤشر كتابة من دون رد نهائي).
• الملصقات: راجع حالة بوتات Marketplace في الإمكانات.
• الملاحظات الصوتية / الملفات الصوتية / الفيديو / مرفقات الملفات العامة: راجع حالة بوتات Marketplace في الإمكانات.
• الأنواع غير المدعومة: يتم تسجيلها (مثل الرسائل الواردة من المستخدمين المحميين).

​

الإمكانات

​

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

• استخدم معرّف دردشة كهدف.
• مثال: openclaw message send --channel zalo --target 123456789 --message "hi".

​

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

• تحقّق من أن الرمز المميز صالح: openclaw channels status --probe
• تحقّق من أن المرسل معتمد (عبر الاقتران أو allowFrom)
• تحقّق من سجلات البوابة: openclaw logs --follow

• تأكد من أن عنوان URL الخاص بـ webhook يستخدم HTTPS
• تحقّق من أن الرمز السري يتكون من 8 إلى 256 حرفًا
• أكّد أن نقطة نهاية HTTP الخاصة بالبوابة قابلة للوصول على المسار المهيأ
• تحقّق من أن استطلاع getUpdates لا يعمل (فهما متنافيان)

​

مرجع الإعدادات (Zalo)

• channels.zalo.enabled: تمكين/تعطيل بدء تشغيل القناة.
• channels.zalo.botToken: رمز البوت المميز من Zalo Bot Platform.
• channels.zalo.tokenFile: قراءة الرمز المميز من مسار ملف عادي. يتم رفض الروابط الرمزية.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (الافتراضي: pairing).
• channels.zalo.allowFrom: قائمة سماح الرسائل الخاصة (معرّفات المستخدمين). يتطلب open وجود "*". سيطلب المعالج المعرّفات الرقمية.
• channels.zalo.groupPolicy: open | allowlist | disabled (الافتراضي: allowlist). موجود في الإعدادات؛ راجع الإمكانات والتحكم في الوصول (المجموعات) لسلوك بوتات Marketplace الحالي.
• channels.zalo.groupAllowFrom: قائمة سماح مرسلي المجموعات (معرّفات المستخدمين). ترجع إلى allowFrom عندما لا تكون معيّنة.
• channels.zalo.mediaMaxMb: الحد الأقصى للوسائط الواردة/الصادرة (MB، الافتراضي 5).
• channels.zalo.webhookUrl: تمكين وضع webhook (يتطلب HTTPS).
• channels.zalo.webhookSecret: سر webhook (8-256 حرفًا).
• channels.zalo.webhookPath: مسار webhook على خادم HTTP الخاص بالبوابة.
• channels.zalo.proxy: عنوان URL للوكيل لطلبات API.

• channels.zalo.accounts.<id>.botToken: رمز مميز لكل حساب.
• channels.zalo.accounts.<id>.tokenFile: ملف رمز مميز عادي لكل حساب. يتم رفض الروابط الرمزية.
• channels.zalo.accounts.<id>.name: اسم العرض.
• channels.zalo.accounts.<id>.enabled: تمكين/تعطيل الحساب.
• channels.zalo.accounts.<id>.dmPolicy: سياسة الرسائل الخاصة لكل حساب.
• channels.zalo.accounts.<id>.allowFrom: قائمة السماح لكل حساب.
• channels.zalo.accounts.<id>.groupPolicy: سياسة المجموعات لكل حساب. موجودة في الإعدادات؛ راجع الإمكانات والتحكم في الوصول (المجموعات) لسلوك بوتات Marketplace الحالي.
• channels.zalo.accounts.<id>.groupAllowFrom: قائمة سماح مرسلي المجموعات لكل حساب.
• channels.zalo.accounts.<id>.webhookUrl: عنوان URL لـ webhook لكل حساب.
• channels.zalo.accounts.<id>.webhookSecret: سر webhook لكل حساب.
• channels.zalo.accounts.<id>.webhookPath: مسار webhook لكل حساب.
• channels.zalo.accounts.<id>.proxy: عنوان URL للوكيل لكل حساب.

​

ذو صلة

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