Regional platforms

Zalo

وضعیت: آزمایشی. پیام‌های مستقیم پشتیبانی می‌شوند. بخش قابلیت‌ها در ادامه، رفتار فعلی ربات Marketplace را نشان می‌دهد.

Plugin همراه

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

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

نصب از طریق CLI: openclaw plugins install @openclaw/zalo
نسخه پین‌شده: openclaw plugins install @openclaw/[email protected]
یا از checkout سورس: openclaw plugins install ./path/to/local/zalo-plugin
جزئیات: Plugins

راه‌اندازی سریع (مبتدی)

مطمئن شوید Plugin مربوط به Zalo در دسترس است.
- نسخه‌های بسته‌بندی‌شده فعلی OpenClaw از قبل آن را همراه دارند.
- نصب‌های قدیمی‌تر/سفارشی می‌توانند آن را با دستورهای بالا به‌صورت دستی اضافه کنند.
توکن را تنظیم کنید:
- Env: ZALO_BOT_TOKEN=...
- یا config: channels.zalo.accounts.default.botToken: "...".
Gateway را بازراه‌اندازی کنید (یا راه‌اندازی را کامل کنید).
دسترسی پیام مستقیم به‌صورت پیش‌فرض با جفت‌سازی انجام می‌شود؛ در اولین تماس، کد جفت‌سازی را تأیید کنید.

حداقل پیکربندی:

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

چیست

Zalo یک برنامه پیام‌رسان متمرکز بر ویتنام است؛ Bot API آن به Gateway اجازه می‌دهد برای گفت‌وگوهای یک‌به‌یک یک ربات اجرا کند. برای پشتیبانی یا اعلان‌هایی که در آن‌ها مسیریابی قطعی به Zalo می‌خواهید، گزینه مناسبی است.

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

یک کانال Zalo Bot API که مالک آن Gateway است.
مسیریابی قطعی: پاسخ‌ها به Zalo برمی‌گردند؛ مدل هرگز کانال‌ها را انتخاب نمی‌کند.
پیام‌های مستقیم نشست اصلی agent را به اشتراک می‌گذارند.
بخش قابلیت‌ها در ادامه، پشتیبانی فعلی ربات Marketplace را نشان می‌دهد.

راه‌اندازی (مسیر سریع)

1) ایجاد توکن ربات (Zalo Bot Platform)

به https://bot.zaloplatforms.com بروید و وارد شوید.
یک ربات جدید بسازید و تنظیمات آن را پیکربندی کنید.
توکن کامل ربات را کپی کنید (معمولاً numeric_id:secret). برای ربات‌های Marketplace، توکن قابل‌استفاده در زمان اجرا ممکن است پس از ایجاد در پیام خوشامد ربات ظاهر شود.

2) پیکربندی توکن (env یا config)

نمونه:

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

اگر بعداً به سطحی از ربات Zalo منتقل شدید که در آن گروه‌ها در دسترس هستند، می‌توانید پیکربندی ویژه گروه مانند groupPolicy و groupAllowFrom را صریحاً اضافه کنید. برای رفتار فعلی ربات Marketplace، قابلیت‌ها را ببینید.

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

پشتیبانی چندحسابی: از channels.zalo.accounts با توکن‌های جداگانه برای هر حساب و name اختیاری استفاده کنید.

Gateway را بازراه‌اندازی کنید. وقتی توکن تشخیص داده شود (env یا config)، Zalo شروع به کار می‌کند.
دسترسی پیام مستقیم به‌صورت پیش‌فرض روی جفت‌سازی است. وقتی برای اولین بار با ربات تماس گرفته شد، کد را تأیید کنید.

نحوه کار (رفتار)

پیام‌های ورودی با placeholderهای رسانه در envelope مشترک کانال نرمال‌سازی می‌شوند.
پاسخ‌ها همیشه به همان گفت‌وگوی Zalo برمی‌گردند.
به‌صورت پیش‌فرض long-polling؛ حالت webhook با channels.zalo.webhookUrl در دسترس است.

محدودیت‌ها

متن خروجی به قطعه‌های ۲۰۰۰ نویسه‌ای تقسیم می‌شود (محدودیت Zalo API).
دانلود/آپلود رسانه با channels.zalo.mediaMaxMb محدود می‌شود (پیش‌فرض 5).
Streaming به‌صورت پیش‌فرض مسدود است، چون محدودیت ۲۰۰۰ نویسه‌ای کاربرد Streaming را کمتر می‌کند.

کنترل دسترسی (پیام‌های مستقیم)

دسترسی پیام مستقیم

پیش‌فرض: channels.zalo.dmPolicy = "pairing". فرستنده‌های ناشناخته یک کد جفت‌سازی دریافت می‌کنند؛ پیام‌ها تا زمان تأیید نادیده گرفته می‌شوند (کدها پس از ۱ ساعت منقضی می‌شوند).
تأیید از طریق:
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
جفت‌سازی تبادل توکن پیش‌فرض است. جزئیات: جفت‌سازی
channels.zalo.allowFrom شناسه‌های عددی کاربر را می‌پذیرد (جست‌وجوی نام کاربری در دسترس نیست).

کنترل دسترسی (گروه‌ها)

برای ربات‌های Zalo Bot Creator / Marketplace، پشتیبانی گروه در عمل در دسترس نبود، چون ربات اصلاً نمی‌توانست به گروه اضافه شود.

یعنی کلیدهای پیکربندی مرتبط با گروه در ادامه در schema وجود دارند، اما برای ربات‌های Marketplace قابل‌استفاده نبودند:

channels.zalo.groupPolicy مدیریت ورودی گروه را کنترل می‌کند: open | allowlist | disabled.
channels.zalo.groupAllowFrom محدود می‌کند کدام شناسه‌های فرستنده می‌توانند ربات را در گروه‌ها فعال کنند.
اگر groupAllowFrom تنظیم نشده باشد، Zalo برای بررسی فرستنده به allowFrom برمی‌گردد.
نکته زمان اجرا: اگر channels.zalo کاملاً وجود نداشته باشد، runtime همچنان برای ایمنی به groupPolicy="allowlist" برمی‌گردد.

مقادیر سیاست گروه (وقتی دسترسی گروه روی سطح ربات شما در دسترس باشد) عبارت‌اند از:

groupPolicy: "disabled" — همه پیام‌های گروه را مسدود می‌کند.
groupPolicy: "open" — به هر عضو گروه اجازه می‌دهد (با دروازه mention).
groupPolicy: "allowlist" — پیش‌فرض fail-closed؛ فقط فرستنده‌های مجاز پذیرفته می‌شوند.

اگر از سطح محصول متفاوتی برای ربات Zalo استفاده می‌کنید و رفتار گروهیِ کارا را تأیید کرده‌اید، آن را جداگانه مستند کنید و فرض نکنید با جریان ربات Marketplace یکسان است.

Long-polling در برابر webhook

پیش‌فرض: long-polling (به URL عمومی نیاز ندارد).
حالت Webhook: channels.zalo.webhookUrl و channels.zalo.webhookSecret را تنظیم کنید.
- webhook secret باید ۸ تا ۲۵۶ نویسه باشد.
- URL مربوط به webhook باید از HTTPS استفاده کند.
- Zalo رویدادها را با header به نام X-Bot-Api-Secret-Token برای راستی‌آزمایی ارسال می‌کند.
- HTTP مربوط به Gateway درخواست‌های webhook را در channels.zalo.webhookPath مدیریت می‌کند (پیش‌فرض مسیر URL مربوط به webhook است).
- درخواست‌ها باید از Content-Type: application/json (یا انواع رسانه‌ای +json) استفاده کنند.
- رویدادهای تکراری (event_name + message_id) برای یک بازه کوتاه replay نادیده گرفته می‌شوند.
- ترافیک burst به‌ازای هر مسیر/منبع rate-limit می‌شود و ممکن است HTTP 429 برگرداند.

نکته: طبق مستندات Zalo API، getUpdates (polling) و webhook برای هر ربات به‌صورت متقابل ناسازگارند.

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

برای یک نمای سریع از پشتیبانی، قابلیت‌ها را ببینید. نکات زیر در جاهایی که رفتار به زمینه بیشتری نیاز دارد، جزئیات اضافه می‌کنند.

پیام‌های متنی: پشتیبانی کامل با تقسیم‌بندی ۲۰۰۰ نویسه‌ای.
URLهای ساده در متن: مانند ورودی متن عادی رفتار می‌کنند.
پیش‌نمایش لینک‌ها / کارت‌های لینک غنی: وضعیت ربات Marketplace را در قابلیت‌ها ببینید؛ این‌ها به‌طور قابل‌اعتماد پاسخ را فعال نمی‌کردند.
پیام‌های تصویری: وضعیت ربات Marketplace را در قابلیت‌ها ببینید؛ مدیریت تصویر ورودی قابل‌اعتماد نبود (نشانگر تایپ بدون پاسخ نهایی).
استیکرها: وضعیت ربات Marketplace را در قابلیت‌ها ببینید.
یادداشت‌های صوتی / فایل‌های صوتی / ویدئو / پیوست‌های فایل عمومی: وضعیت ربات Marketplace را در قابلیت‌ها ببینید.
انواع پشتیبانی‌نشده: ثبت می‌شوند (برای مثال، پیام‌های کاربران محافظت‌شده).

قابلیت‌ها

این جدول رفتار فعلی ربات Zalo Bot Creator / Marketplace را در OpenClaw خلاصه می‌کند.

ویژگی	وضعیت
پیام‌های مستقیم	✅ پشتیبانی می‌شود
گروه‌ها	❌ برای ربات‌های Marketplace در دسترس نیست
رسانه (تصاویر ورودی)	⚠️ محدود / در محیط خود تأیید کنید
رسانه (تصاویر خروجی)	⚠️ برای ربات‌های Marketplace دوباره آزموده نشده است
URLهای ساده در متن	✅ پشتیبانی می‌شود
پیش‌نمایش لینک‌ها	⚠️ برای ربات‌های Marketplace غیرقابل‌اعتماد
واکنش‌ها	❌ پشتیبانی نمی‌شود
استیکرها	⚠️ بدون پاسخ agent برای ربات‌های Marketplace
یادداشت صوتی / صوت / ویدئو	⚠️ بدون پاسخ agent برای ربات‌های Marketplace
پیوست‌های فایل	⚠️ بدون پاسخ agent برای ربات‌های Marketplace
Threadها	❌ پشتیبانی نمی‌شود
نظرسنجی‌ها	❌ پشتیبانی نمی‌شود
دستورهای بومی	❌ پشتیبانی نمی‌شود
Streaming	⚠️ مسدود شده (محدودیت ۲۰۰۰ نویسه)

مقصدهای تحویل (CLI/cron)

از یک chat id به‌عنوان مقصد استفاده کنید.
نمونه: openclaw message send --channel zalo --target 123456789 --message "hi".

عیب‌یابی

ربات پاسخ نمی‌دهد:

بررسی کنید توکن معتبر است: openclaw channels status --probe
تأیید کنید فرستنده تأیید شده است (pairing یا allowFrom)
لاگ‌های Gateway را بررسی کنید: openclaw logs --follow

Webhook رویدادها را دریافت نمی‌کند:

مطمئن شوید URL مربوط به webhook از HTTPS استفاده می‌کند
تأیید کنید secret token بین ۸ تا ۲۵۶ نویسه است
اطمینان پیدا کنید endpoint HTTP مربوط به Gateway روی مسیر پیکربندی‌شده در دسترس است
بررسی کنید polling مربوط به getUpdates در حال اجرا نباشد (این‌ها متقابلاً ناسازگارند)

مرجع پیکربندی (Zalo)

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

کلیدهای تخت سطح بالا (channels.zalo.botToken، channels.zalo.dmPolicy، و موارد مشابه) میان‌بر قدیمی تک‌حسابی هستند. برای پیکربندی‌های جدید، channels.zalo.accounts.<id>.* را ترجیح دهید. هر دو شکل همچنان اینجا مستند شده‌اند چون در schema وجود دارند.

گزینه‌های provider:

channels.zalo.enabled: فعال/غیرفعال کردن شروع کانال.
channels.zalo.botToken: توکن ربات از Zalo Bot Platform.
channels.zalo.tokenFile: خواندن توکن از مسیر یک فایل معمولی. symlinkها رد می‌شوند.
channels.zalo.dmPolicy: pairing | allowlist | open | disabled (پیش‌فرض: pairing).
channels.zalo.allowFrom: allowlist پیام مستقیم (شناسه‌های کاربر). open به "*" نیاز دارد. wizard شناسه‌های عددی را درخواست می‌کند.
channels.zalo.groupPolicy: open | allowlist | disabled (پیش‌فرض: allowlist). در config وجود دارد؛ برای رفتار فعلی ربات Marketplace، قابلیت‌ها و کنترل دسترسی (گروه‌ها) را ببینید.
channels.zalo.groupAllowFrom: allowlist فرستنده گروه (شناسه‌های کاربر). وقتی تنظیم نشده باشد، به allowFrom برمی‌گردد.
channels.zalo.mediaMaxMb: سقف رسانه ورودی/خروجی (MB، پیش‌فرض 5).
channels.zalo.webhookUrl: فعال کردن حالت webhook (HTTPS الزامی است).
channels.zalo.webhookSecret: webhook secret (۸ تا ۲۵۶ نویسه).
channels.zalo.webhookPath: مسیر webhook روی سرور HTTP مربوط به Gateway.
channels.zalo.proxy: URL مربوط به proxy برای درخواست‌های API.

گزینه‌های چندحسابی:

channels.zalo.accounts.<id>.botToken: توکن جداگانه برای هر حساب.
channels.zalo.accounts.<id>.tokenFile: فایل توکن معمولی جداگانه برای هر حساب. symlinkها رد می‌شوند.
channels.zalo.accounts.<id>.name: نام نمایشی.
channels.zalo.accounts.<id>.enabled: فعال/غیرفعال کردن حساب.
channels.zalo.accounts.<id>.dmPolicy: سیاست پیام مستقیم جداگانه برای هر حساب.
channels.zalo.accounts.<id>.allowFrom: allowlist جداگانه برای هر حساب.
channels.zalo.accounts.<id>.groupPolicy: سیاست گروه جداگانه برای هر حساب. در config وجود دارد؛ برای رفتار فعلی ربات Marketplace، قابلیت‌ها و کنترل دسترسی (گروه‌ها) را ببینید.
channels.zalo.accounts.<id>.groupAllowFrom: allowlist فرستنده گروه جداگانه برای هر حساب.
channels.zalo.accounts.<id>.webhookUrl: URL مربوط به webhook جداگانه برای هر حساب.
channels.zalo.accounts.<id>.webhookSecret: webhook secret جداگانه برای هر حساب.
channels.zalo.accounts.<id>.webhookPath: مسیر webhook جداگانه برای هر حساب.
channels.zalo.accounts.<id>.proxy: URL مربوط به proxy جداگانه برای هر حساب.

مرتبط

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

# Plugin همراه

# راه‌اندازی سریع (مبتدی)

# چیست

# راه‌اندازی (مسیر سریع)

# 1) ایجاد توکن ربات (Zalo Bot Platform)

# 2) پیکربندی توکن (env یا config)

# نحوه کار (رفتار)

# محدودیت‌ها

# کنترل دسترسی (پیام‌های مستقیم)

# دسترسی پیام مستقیم

# کنترل دسترسی (گروه‌ها)

# Long-polling در برابر webhook

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

# قابلیت‌ها

# مقصدهای تحویل (CLI/cron)

# عیب‌یابی

# مرجع پیکربندی (Zalo)

# مرتبط