---
read_when:
    - کار روی قابلیت‌ها یا Webhookهای Zalo
summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Zalo
title: Zalo
x-i18n:
    generated_at: "2026-07-12T09:40:50Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 36e624f1abeeaee56d7376b9df9209f8e7614ade2f089bcecd76ff746b942765
    source_path: channels/zalo.md
    workflow: 16
---

وضعیت: آزمایشی. هم پیام‌های مستقیم و هم گفت‌وگوهای گروهی پیاده‌سازی شده‌اند؛ جدول [قابلیت‌ها](#capabilities) در ادامه، رفتار تأییدشده در ربات‌های 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ها](/fa/tools/plugin)

## راه‌اندازی سریع

1. در [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) یک توکن ربات ایجاد کنید (وارد شوید، یک ربات بسازید و تنظیمات را پیکربندی کنید). قالب توکن `numeric_id:secret` است؛ برای ربات‌های Marketplace، توکن قابل‌استفاده در زمان اجرا ممکن است در پیام خوشامدگویی ربات نمایش داده شود.
2. توکن را به‌صورت متغیر محیطی `ZALO_BOT_TOKEN=...` (فقط برای حساب پیش‌فرض) یا در پیکربندی تنظیم کنید.
3. Gateway را راه‌اندازی مجدد کنید.
4. در نخستین تماس از طریق پیام مستقیم، کد جفت‌سازی را تأیید کنید (سیاست پیش‌فرض پیام مستقیم، جفت‌سازی است).

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

```json5
{
  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` در دسترس است.
- در گروه‌ها، برای فعال‌شدن ربات باید به آن @اشاره شود؛ این مورد برای هر کانال قابل‌پیکربندی نیست.

## محدودیت‌ها

| محدودیت                              | مقدار                                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| اندازه قطعه متن خروجی                | ۲۰۰۰ نویسه (محدودیت Zalo API)                                                               |
| اندازه رسانه (ورودی/خروجی)           | `channels.zalo.mediaMaxMb`، مقدار پیش‌فرض `5` مگابایت                                        |
| بدنه درخواست Webhook                 | ۱ مگابایت، مهلت خواندن ۳۰ ثانیه                                                             |
| محدودیت نرخ Webhook                  | ۱۲۰ درخواست در ۶۰ ثانیه به‌ازای هر مسیر+IP کارخواه، سپس HTTP 429                            |
| بازه رویداد تکراری Webhook           | ۵ دقیقه (با کلید مسیر + حساب + نام رویداد + گفت‌وگو + فرستنده + شناسه پیام)                  |

## کنترل دسترسی

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

- `channels.zalo.dmPolicy`: `pairing` (پیش‌فرض) | `allowlist` | `open` | `disabled`.
- جفت‌سازی: فرستندگان ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ پیام‌ها تا زمان تأیید نادیده گرفته می‌شوند. کدها پس از ۱ ساعت منقضی می‌شوند.
  - `openclaw pairing list zalo`
  - `openclaw pairing approve zalo <CODE>`
  - جزئیات: [جفت‌سازی](/fa/channels/pairing)
- `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 گزینه‌های اختصاصی تنظیم صف خروجی/ادغام متن ندارد (برخلاف برخی کانال‌های منطقه‌ای دیگر)؛ اگر این موضوع برای مورد استفاده شما اهمیت دارد، رفتار فعلی را در محیط خود بررسی کنید.

## قابلیت‌ها

| قابلیت                  | وضعیت                               |
| ----------------------- | ----------------------------------- |
| پیام‌های مستقیم         | پشتیبانی می‌شود                     |
| گروه‌ها                 | پشتیبانی می‌شود (نیازمند اشاره)     |
| رسانه (ورودی/خروجی)     | پشتیبانی می‌شود، محدود به `mediaMaxMb` |
| واکنش‌ها                | پشتیبانی نمی‌شود                    |
| رشته‌ها                 | پشتیبانی نمی‌شود                    |
| نظرسنجی‌ها              | پشتیبانی نمی‌شود                    |
| فرمان‌های بومی          | پشتیبانی نمی‌شود                    |
| پاسخ به / نقل‌قول       | استفاده نمی‌شود (به‌صورت ثابت غیرفعال) |

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

از یک شناسه گفت‌وگو به‌عنوان مقصد استفاده کنید:

```bash
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)؛ کمی صبر کنید و دوباره تلاش کنید

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

پیکربندی کامل: [پیکربندی](/fa/gateway/configuration)

| تنظیم                                         | توضیح                                                     | پیش‌فرض                  |
| --------------------------------------------- | --------------------------------------------------------- | ------------------------ |
| `channels.zalo.enabled`                       | فعال/غیرفعال‌کردن راه‌اندازی کانال                        | `true`                   |
| `channels.zalo.accounts.<id>.botToken`        | توکن ربات از Zalo Bot Platform                            | -                        |
| `channels.zalo.accounts.<id>.tokenFile`       | خواندن توکن از فایل (پیوندهای نمادین رد می‌شوند)          | -                        |
| `channels.zalo.accounts.<id>.name`            | نام نمایشی                                                | -                        |
| `channels.zalo.accounts.<id>.enabled`         | فعال/غیرفعال‌کردن این حساب                                | `true`                   |
| `channels.zalo.accounts.<id>.dmPolicy`        | سیاست پیام مستقیم برای هر حساب                            | `pairing`                |
| `channels.zalo.accounts.<id>.allowFrom`       | فهرست مجاز پیام مستقیم (شناسه‌های کاربر)                   | -                        |
| `channels.zalo.accounts.<id>.groupPolicy`     | سیاست گروه برای هر حساب                                   | [گروه‌ها](#groups) را ببینید |
| `channels.zalo.accounts.<id>.groupAllowFrom`  | فهرست مجاز فرستندگان گروه؛ در نبود مقدار از `allowFrom` استفاده می‌کند | -              |
| `channels.zalo.accounts.<id>.mediaMaxMb`      | سقف رسانه ورودی/خروجی (مگابایت)                           | `5`                      |
| `channels.zalo.accounts.<id>.webhookUrl`      | فعال‌کردن حالت Webhook (HTTPS الزامی است)                 | -                        |
| `channels.zalo.accounts.<id>.webhookSecret`   | راز Webhook (۸ تا ۲۵۶ نویسه)                              | -                        |
| `channels.zalo.accounts.<id>.webhookPath`     | مسیر Webhook در سرور HTTP مربوط به Gateway                | مسیر URL مربوط به Webhook |
| `channels.zalo.accounts.<id>.proxy`           | URL پراکسی برای درخواست‌های API                           | -                        |
| `channels.zalo.accounts.<id>.responsePrefix`  | بازنویسی پیشوند پاسخ خروجی                                | -                        |
| `channels.zalo.defaultAccount`                | حساب پیش‌فرض هنگام پیکربندی چند حساب                       | `default`                |

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

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

## مرتبط

- [نمای کلی کانال‌ها](/fa/channels) - همه کانال‌های پشتیبانی‌شده
- [جفت‌سازی](/fa/channels/pairing) - احراز هویت پیام مستقیم و جریان جفت‌سازی
- [گروه‌ها](/fa/channels/groups) - رفتار گفت‌وگوی گروهی و الزام اشاره
- [مسیریابی کانال](/fa/channels/channel-routing) - مسیریابی نشست برای پیام‌ها
- [امنیت](/fa/gateway/security) - مدل دسترسی و مقاوم‌سازی