Zalo

وضعیت: آزمایشی. هم پیام‌های مستقیم و هم گفت‌وگوهای گروهی پیاده‌سازی شده‌اند؛ جدول قابلیت‌ها در ادامه، رفتار تأییدشده در ربات‌های Zalo Bot Creator / Marketplace را نشان می‌دهد.

Plugin همراه

Zalo در نسخه‌های فعلی OpenClaw به‌صورت یک Plugin همراه عرضه می‌شود، بنابراین بیلدهای بسته‌بندی‌شده به نصب جداگانه نیاز ندارند.

در بیلدی قدیمی‌تر یا نصبی سفارشی که Zalo را شامل نمی‌شود، بسته npm را مستقیماً نصب کنید:

• نصب: openclaw plugins install @openclaw/zalo
• نسخه پین‌شده: openclaw plugins install @openclaw/zalo@2026.6.11
• از یک checkout محلی: openclaw plugins install ./path/to/local/zalo-plugin
• جزئیات: 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 یک برنامه پیام‌رسان متمرکز بر ویتنام است. API ربات آن به Gateway اجازه می‌دهد رباتی را هم برای مکالمات 1:1 و هم برای گفت‌وگوهای گروهی اجرا کند و پاسخ‌ها را به‌صورت قطعی به Zalo مسیریابی کند (مدل هرگز کانال‌ها را انتخاب نمی‌کند).

این صفحه ربات‌های Zalo Bot Creator / Marketplace را پوشش می‌دهد. ربات‌های Zalo Official Account (OA) سطح محصول متفاوتی هستند و ممکن است رفتار متفاوتی داشته باشند؛ این صفحه آن‌ها را پوشش نمی‌دهد.

نحوه کار

• پیام‌های ورودی با جای‌نگهدارهای رسانه در پاکت مشترک کانال نرمال‌سازی می‌شوند.
• پاسخ‌ها همیشه به همان گفت‌وگوی Zalo بازگردانده می‌شوند؛ پاسخ نقل‌قولی استفاده نمی‌شود (replyToMode به‌طور ثابت غیرفعال است).
• حالت پیش‌فرض، نظرسنجی طولانی (getUpdates) است؛ حالت Webhook از طریق channels.zalo.webhookUrl در دسترس است.
• در گروه‌ها برای فعال‌کردن ربات، @mention لازم است؛ این مورد به‌ازای هر کانال قابل‌پیکربندی نیست.

محدودیت‌ها

کنترل دسترسی

پیام‌های مستقیم

• channels.zalo.dmPolicy: pairing (پیش‌فرض) | allowlist | open | disabled.
• جفت‌سازی: فرستندگان ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ پیام‌ها تا زمان تأیید نادیده گرفته می‌شوند. اعتبار کدها پس از 1 ساعت منقضی می‌شود.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • جزئیات: جفت‌سازی
• channels.zalo.allowFrom شناسه‌های عددی کاربر Zalo را می‌پذیرد (جست‌وجوی نام کاربری وجود ندارد). open به "*" نیاز دارد.

گروه‌ها

گفت‌وگوهای گروهی توسط Plugin پشتیبانی می‌شوند (chatTypes: ["direct", "group"]) و دسترسی به آن‌ها به mention و سیاست گروه وابسته است:

• 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) استفاده کنند.
  • تنها پس از ذخیره پایدار رویداد خام، HTTP 200 برگردانده می‌شود؛ خطاهای ذخیره‌سازی HTTP 500 برمی‌گردانند.
  • طبق مستندات API ‏Zalo، نظرسنجی getUpdates و Webhook به‌ازای هر حساب مانعةالجمع هستند.

انواع پیام پشتیبانی‌شده

• متن: پشتیبانی کامل، تقسیم‌شده به قطعه‌های 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 درخواست / 60s برای هر مسیر+IP)؛ عقب‌نشینی کنید و دوباره تلاش کنید

مرجع پیکربندی

پیکربندی کامل: پیکربندی

channels.zalo.botToken، channels.zalo.dmPolicy و دیگر کلیدهای مسطح سطح بالا، شکل کوتاه قدیمی تک‌حسابی برای فیلدهای بالا هستند؛ هر دو شکل پشتیبانی می‌شوند.

گزینه محیطی: ZALO_BOT_TOKEN=... فقط توکن حساب پیش‌فرض را تفکیک می‌کند.

مرتبط

• نمای کلی کانال‌ها - همه کانال‌های پشتیبانی‌شده
• جفت‌سازی - احراز هویت پیام مستقیم و جریان جفت‌سازی
• گروه‌ها - رفتار گفت‌وگوی گروهی و الزام mention
• مسیریابی کانال - مسیریابی نشست برای پیام‌ها
• امنیت - مدل دسترسی و مقاوم‌سازی