Zalo

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

Plugin همراه

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

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

• نصب: openclaw plugins install @openclaw/zalo
• نسخه ثابت‌شده: openclaw plugins install @openclaw/zalo@2026.6.11
• از یک نسخه محلی کد: 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 یک برنامه پیام‌رسان متمرکز بر ویتنام است. 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 باید بین ۸ تا ۲۵۶ نویسه باشد.
  • Zalo رویدادها را با سرآیند X-Bot-Api-Secret-Token ارسال می‌کند که با مقایسه زمان‌ثابت بررسی می‌شود.
  • HTTP مربوط به Gateway درخواست‌های Webhook را در channels.zalo.webhookPath مدیریت می‌کند (مقدار پیش‌فرض، مسیر URL مربوط به Webhook است).
  • درخواست‌ها باید از Content-Type: application/json (یا نوع رسانه‌ای +json) استفاده کنند.
  • طبق مستندات Zalo API، نظرسنجی getUpdates و Webhook برای هر ربات متقابلاً انحصاری هستند.

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

• متن: پشتیبانی کامل، قطعه‌بندی‌شده به ۲۰۰۰ نویسه.
• رسانه: ورودی/خروجی، محدودشده با 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 استفاده می‌کند
• تأیید کنید که راز بین ۸ تا ۲۵۶ نویسه است
• تأیید کنید که نقطه پایانی HTTP مربوط به Gateway در مسیر پیکربندی‌شده در دسترس است
• تأیید کنید که نظرسنجی getUpdates هم‌زمان در حال اجرا نیست (این دو متقابلاً انحصاری هستند)
• افزایش ناگهانی درخواست‌ها می‌تواند HTTP 429 برگرداند (۱۲۰ درخواست در ۶۰ ثانیه به‌ازای هر مسیر+IP)؛ کمی صبر کنید و دوباره تلاش کنید

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

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

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

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

مرتبط

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