> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zalo

Статус: експериментальний. DM підтримуються. Розділ [Можливості](#capabilities) нижче відображає поточну поведінку ботів Marketplace.

## Вбудований Plugin

Zalo постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні пакетовані
збірки не потребують окремого встановлення.

Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Zalo, установіть
npm-пакет напряму:

* Установити через CLI: `openclaw plugins install @openclaw/zalo`
* Закріплена версія: `openclaw plugins install @openclaw/zalo@2026.5.2`
* Або з checkout вихідного коду: `openclaw plugins install ./path/to/local/zalo-plugin`
* Докладніше: [Plugins](/uk/tools/plugin)

## Швидке налаштування (для початківців)

1. Переконайтеся, що Plugin Zalo доступний.
   * Поточні пакетовані випуски OpenClaw уже містять його.
   * Старіші/власні встановлення можуть додати його вручну командами вище.
2. Задайте токен:
   * Env: `ZALO_BOT_TOKEN=...`
   * Або config: `channels.zalo.accounts.default.botToken: "..."`.
3. Перезапустіть Gateway (або завершіть налаштування).
4. Доступ до DM за замовчуванням працює через pairing; підтвердьте код pairing під час першого контакту.

Мінімальна конфігурація:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}
```

## Що це таке

Zalo — це застосунок для обміну повідомленнями, орієнтований на В'єтнам; його Bot API дає Gateway змогу запускати бота для розмов 1:1.
Це добре підходить для підтримки або сповіщень, коли потрібна детермінована маршрутизація назад у Zalo.

Ця сторінка відображає поточну поведінку OpenClaw для **ботів Zalo Bot Creator / Marketplace**.
**Боти Zalo Official Account (OA)** — це інша продуктова поверхня Zalo, і вона може поводитися інакше.

* Канал Zalo Bot API, яким володіє Gateway.
* Детермінована маршрутизація: відповіді повертаються до Zalo; модель ніколи не вибирає канали.
* DM спільно використовують основну сесію агента.
* Розділ [Можливості](#capabilities) нижче показує поточну підтримку ботів Marketplace.

## Налаштування (швидкий шлях)

### 1) Створіть токен бота (Zalo Bot Platform)

1. Перейдіть на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) і ввійдіть.
2. Створіть нового бота й налаштуйте його параметри.
3. Скопіюйте повний токен бота (зазвичай `numeric_id:secret`). Для ботів Marketplace придатний для виконання токен може з'явитися у привітальному повідомленні бота після створення.

### 2) Налаштуйте токен (env або config)

Приклад:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}
```

Якщо згодом ви перейдете на поверхню бота Zalo, де доступні групи, можна явно додати групову конфігурацію, як-от `groupPolicy` і `groupAllowFrom`. Поточну поведінку ботів Marketplace див. у [Можливостях](#capabilities).

Опція env: `ZALO_BOT_TOKEN=...` (працює лише для облікового запису за замовчуванням).

Підтримка кількох облікових записів: використовуйте `channels.zalo.accounts` із токенами для кожного облікового запису та необов'язковим `name`.

3. Перезапустіть Gateway. Zalo запускається, коли токен визначено (env або config).
4. Доступ до DM за замовчуванням працює через pairing. Підтвердьте код, коли з ботом уперше зв'яжуться.

## Як це працює (поведінка)

* Вхідні повідомлення нормалізуються у спільний envelope каналу із заповнювачами медіа.
* Відповіді завжди маршрутизуються назад у той самий чат Zalo.
* За замовчуванням використовується long-polling; режим webhook доступний із `channels.zalo.webhookUrl`.

## Обмеження

* Вихідний текст розбивається на фрагменти по 2000 символів (обмеження Zalo API).
* Завантаження/вивантаження медіа обмежені `channels.zalo.mediaMaxMb` (за замовчуванням 5).
* Streaming за замовчуванням заблокований, бо обмеження у 2000 символів робить streaming менш корисним.

## Контроль доступу (DM)

### Доступ до DM

* За замовчуванням: `channels.zalo.dmPolicy = "pairing"`. Невідомі відправники отримують код pairing; повідомлення ігноруються, доки їх не підтвердять (коди спливають через 1 годину).
* Підтвердьте через:
  * `openclaw pairing list zalo`
  * `openclaw pairing approve zalo <CODE>`
* Pairing — це типовий обмін токеном. Докладніше: [Pairing](/uk/channels/pairing)
* `channels.zalo.allowFrom` приймає числові ID користувачів (пошук за іменем користувача недоступний).

## Контроль доступу (групи)

Для **ботів Zalo Bot Creator / Marketplace** підтримка груп на практиці була недоступна, бо бота взагалі не можна було додати до групи.

Це означає, що наведені нижче ключі конфігурації, пов'язані з групами, існують у схемі, але не були придатні для використання з ботами Marketplace:

* `channels.zalo.groupPolicy` керує обробкою вхідних повідомлень у групах: `open | allowlist | disabled`.
* `channels.zalo.groupAllowFrom` обмежує, які ID відправників можуть запускати бота в групах.
* Якщо `groupAllowFrom` не задано, Zalo повертається до `allowFrom` для перевірок відправника.
* Примітка щодо виконання: якщо `channels.zalo` повністю відсутній, runtime все одно повертається до `groupPolicy="allowlist"` для безпеки.

Значення групової політики (коли груповий доступ доступний на поверхні вашого бота):

* `groupPolicy: "disabled"` — блокує всі групові повідомлення.
* `groupPolicy: "open"` — дозволяє будь-якого учасника групи (з gate за згадкою).
* `groupPolicy: "allowlist"` — типовий fail-closed режим; приймаються лише дозволені відправники.

Якщо ви використовуєте іншу продуктову поверхню бота Zalo і підтвердили робочу поведінку груп, задокументуйте це окремо, а не припускайте, що вона збігається з потоком ботів Marketplace.

## Long-polling проти webhook

* За замовчуванням: long-polling (публічний URL не потрібен).
* Режим Webhook: задайте `channels.zalo.webhookUrl` і `channels.zalo.webhookSecret`.
  * Секрет webhook має містити 8-256 символів.
  * URL webhook має використовувати HTTPS.
  * Zalo надсилає події із заголовком `X-Bot-Api-Secret-Token` для перевірки.
  * HTTP Gateway обробляє запити webhook на `channels.zalo.webhookPath` (за замовчуванням шлях із URL webhook).
  * Запити мають використовувати `Content-Type: application/json` (або типи медіа `+json`).
  * Дублікати подій (`event_name + message_id`) ігноруються протягом короткого вікна replay.
  * Burst-трафік обмежується за частотою для кожного шляху/джерела й може повертати HTTP 429.

**Примітка:** getUpdates (polling) і webhook є взаємовиключними згідно з документацією Zalo API.

## Підтримувані типи повідомлень

Швидкий знімок підтримки див. у [Можливостях](#capabilities). Примітки нижче додають деталі там, де поведінка потребує додаткового контексту.

* **Текстові повідомлення**: повна підтримка з розбиттям на фрагменти по 2000 символів.
* **Звичайні URL у тексті**: поводяться як звичайне текстове введення.
* **Попередні перегляди посилань / насичені картки посилань**: див. статус ботів Marketplace у [Можливостях](#capabilities); вони не запускали відповідь надійно.
* **Повідомлення із зображеннями**: див. статус ботів Marketplace у [Можливостях](#capabilities); обробка вхідних зображень була ненадійною (індикатор набору без фінальної відповіді).
* **Стікери**: див. статус ботів Marketplace у [Можливостях](#capabilities).
* **Голосові нотатки / аудіофайли / відео / звичайні файлові вкладення**: див. статус ботів Marketplace у [Можливостях](#capabilities).
* **Непідтримувані типи**: логуються (наприклад, повідомлення від захищених користувачів).

## Можливості

Ця таблиця підсумовує поточну поведінку **ботів Zalo Bot Creator / Marketplace** в OpenClaw.

| Функція                          | Статус                                           |
| -------------------------------- | ------------------------------------------------ |
| Прямі повідомлення               | ✅ Підтримується                                  |
| Групи                            | ❌ Недоступні для ботів Marketplace               |
| Медіа (вхідні зображення)        | ⚠️ Обмежено / перевірте у своєму середовищі      |
| Медіа (вихідні зображення)       | ⚠️ Не тестувалося повторно для ботів Marketplace |
| Звичайні URL у тексті            | ✅ Підтримується                                  |
| Попередні перегляди посилань     | ⚠️ Ненадійні для ботів Marketplace               |
| Реакції                          | ❌ Не підтримуються                               |
| Стікери                          | ⚠️ Немає відповіді агента для ботів Marketplace  |
| Голосові нотатки / аудіо / відео | ⚠️ Немає відповіді агента для ботів Marketplace  |
| Файлові вкладення                | ⚠️ Немає відповіді агента для ботів Marketplace  |
| Threads                          | ❌ Не підтримуються                               |
| Опитування                       | ❌ Не підтримуються                               |
| Нативні команди                  | ❌ Не підтримуються                               |
| Streaming                        | ⚠️ Заблоковано (обмеження 2000 символів)         |

## Цілі доставки (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
* Перевірте, що секретний токен має 8-256 символів
* Підтвердьте, що HTTP endpoint Gateway доступний за налаштованим шляхом
* Перевірте, що polling getUpdates не запущено (вони взаємовиключні)

## Довідник конфігурації (Zalo)

Повна конфігурація: [Configuration](/uk/gateway/configuration)

Плоскі ключі верхнього рівня (`channels.zalo.botToken`, `channels.zalo.dmPolicy` тощо) — це застарочений скорочений запис для одного облікового запису. Для нових конфігурацій віддавайте перевагу `channels.zalo.accounts.<id>.*`. Обидві форми все ще задокументовані тут, бо вони існують у схемі.

Опції провайдера:

* `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 для DM (ID користувачів). `open` вимагає `"*"`. Майстер запитає числові ID.
* `channels.zalo.groupPolicy`: `open | allowlist | disabled` (за замовчуванням: allowlist). Присутній у config; поточну поведінку ботів Marketplace див. у [Можливостях](#capabilities) і [Контролі доступу (групи)](#access-control-groups).
* `channels.zalo.groupAllowFrom`: allowlist відправників у групах (ID користувачів). Повертається до `allowFrom`, якщо не задано.
* `channels.zalo.mediaMaxMb`: ліміт для вхідних/вихідних медіа (МБ, за замовчуванням 5).
* `channels.zalo.webhookUrl`: увімкнути режим webhook (потрібен HTTPS).
* `channels.zalo.webhookSecret`: секрет webhook (8-256 символів).
* `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`: політика DM для кожного облікового запису.
* `channels.zalo.accounts.<id>.allowFrom`: allowlist для кожного облікового запису.
* `channels.zalo.accounts.<id>.groupPolicy`: групова політика для кожного облікового запису. Присутня в config; поточну поведінку ботів Marketplace див. у [Можливостях](#capabilities) і [Контролі доступу (групи)](#access-control-groups).
* `channels.zalo.accounts.<id>.groupAllowFrom`: allowlist відправників у групах для кожного облікового запису.
* `channels.zalo.accounts.<id>.webhookUrl`: URL webhook для кожного облікового запису.
* `channels.zalo.accounts.<id>.webhookSecret`: секрет webhook для кожного облікового запису.
* `channels.zalo.accounts.<id>.webhookPath`: шлях webhook для кожного облікового запису.
* `channels.zalo.accounts.<id>.proxy`: URL proxy для кожного облікового запису.

## Пов'язане

* [Огляд каналів](/uk/channels) — усі підтримувані канали
* [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing
* [Групи](/uk/channels/groups) — поведінка групових чатів і gate за згадкою
* [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
* [Безпека](/uk/gateway/security) — модель доступу й посилення захисту