منصات المراسلة

Zalo

الحالة: تجريبية. الرسائل المباشرة مدعومة؛ معالجة المجموعات متاحة مع ضوابط سياسة المجموعة الصريحة.

الإضافة مطلوبة

يتم شحن Zalo كإضافة وليست مضمنة في التثبيت الأساسي.

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

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

  1. قم بتثبيت إضافة Zalo:
    • من نسخة مصدر محلية: openclaw plugins install ./extensions/zalo
    • من npm (إذا كانت منشورة): openclaw plugins install @openclaw/zalo
    • أو اختر Zalo في الإعداد الأولي وقم بتأكيد مطالبة التثبيت
  2. عيّن الرمز المميز (Token):
    • متغير البيئة: ZALO_BOT_TOKEN=...
    • أو في التكوين: channels.zalo.botToken: "...".
  3. أعد تشغيل البوابة (أو أكمل الإعداد الأولي).
  4. الوصول للرسائل المباشرة يكون بالاقتران بشكل افتراضي؛ قم بالموافقة على رمز الاقتران عند أول اتصال.

الحد الأدنى للتكوين:

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

ما هو

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

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

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

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

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

2) تكوين الرمز المميز (متغير بيئة أو تكوين)

مثال:

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

خيار متغير البيئة: ZALO_BOT_TOKEN=... (يعمل للحساب الافتراضي فقط). دعم الحسابات المتعددة: استخدم channels.zalo.accounts مع رموز لكل حساب واختياريًا name.

  1. أعد تشغيل البوابة. يبدأ Zalo عند حل الرمز المميز (من متغير البيئة أو التكوين).
  2. الوصول للرسائل المباشرة يكون بالاقتران افتراضياً. وافق على الرمز عند أول اتصال بالبوت.

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

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

الحدود

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

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

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

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

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

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

الاقتران الطويل مقابل Webhook

  • الافتراضي: الاقتران الطويل (لا يتطلب عنوان URL عام).
  • وضع Webhook: عيّن channels.zalo.webhookUrl و channels.zalo.webhookSecret.
    • يجب أن يكون سر Webhook بين 8 إلى 256 حرفاً.
    • يجب أن يستخدم عنوان Webhook URL بروتوكول HTTPS.
    • يرسل Zalo الأحداث مع رأس X-Bot-Api-Secret-Token للتحقق.
    • تتعامل بوابة HTTP مع طلبات Webhook عند channels.zalo.webhookPath (تكون افتراضياً مسار عنوان Webhook URL).
    • يجب أن تستخدم الطلبات Content-Type: application/json (أو أنواع الوسائط +json).
    • يتم تجاهل الأحداث المكررة (event_name + message_id) لنافذة إعادة تشغيل قصيرة.
    • حركة المرور المفاجئة محدودة بمعدل لكل مسار/مصدر وقد تعيد HTTP 429.

ملاحظة: getUpdates (الاقتران) و webhook متنافيان حصرياً وفقاً لوثائق واجهة برمجة تطبيقات Zalo.

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

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

الإمكانيات

الميزةالحالة
الرسائل المباشرة✅ مدعومة
المجموعات⚠️ مدعومة مع ضوابط السياسة (القائمة المسموح بها افتراضياً)
الوسائط (الصور)✅ مدعومة
التفاعلات (Reactions)❌ غير مدعومة
السلاسل (Threads)❌ غير مدعومة
الاستطلاعات (Polls)❌ غير مدعومة
الأوامر الأصلية❌ غير مدعومة
البث المباشر (Streaming)⚠️ محظور (حد 2000 حرف)

أهداف التسليم (سطر الأوامر/المهام المجدولة)

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

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

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

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

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

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

مرجع التكوين (Zalo)

التكوين الكامل: التكوين خيارات المزود:

  • channels.zalo.enabled: تمكين/تعطيل بدء تشغيل القناة.
  • channels.zalo.botToken: رمز البوت من منصة Zalo Bot.
  • channels.zalo.tokenFile: قراءة الرمز المميز من مسار الملف.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (الافتراضي: pairing).
  • channels.zalo.allowFrom: القائمة المسموح بها للرسائل المباشرة (معرفات المستخدم). open تتطلب "*". سيسأل المعالج عن المعرفات الرقمية.
  • channels.zalo.groupPolicy: open | allowlist | disabled (الافتراضي: allowlist).
  • channels.zalo.groupAllowFrom: قائمة المرسلين المسموح لهم في المجموعات (معرفات المستخدم). يترجع إلى allowFrom عندما لا يتم تعيينه.
  • channels.zalo.mediaMaxMb: حد الوسائط الواردة/الصادرة (ميجابايت، الافتراضي 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: سياسة المجموعة لكل حساب.
  • channels.zalo.accounts.<id>.groupAllowFrom: قائمة مرسلي المجموعة المسموح لهم لكل حساب.
  • channels.zalo.accounts.<id>.webhookUrl: عنوان Webhook URL لكل حساب.
  • channels.zalo.accounts.<id>.webhookSecret: سر Webhook لكل حساب.
  • channels.zalo.accounts.<id>.webhookPath: مسار Webhook لكل حساب.
  • channels.zalo.accounts.<id>.proxy: عنوان URL للوكيل لكل حساب.

WhatsAppZalo Personal