---
read_when:
    - Робота над функціями Zalo або вебхуками
summary: Статус підтримки бота Zalo, можливості та конфігурація
title: Zalo
x-i18n:
    generated_at: "2026-04-05T18:00:14Z"
    model: gpt-5.4
    provider: openai
    source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119
    source_path: channels/zalo.md
    workflow: 15
---

# Zalo (Bot API)

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

## Вбудований плагін

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

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

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

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

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

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

```json5
{
  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 придатний для runtime токен може з’явитися у вітальному повідомленні бота після створення.

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

Приклад:

```json5
{
  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. Підтвердьте код, коли вперше звертаєтеся до бота.

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

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

## Обмеження

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

## Керування доступом (DM)

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

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

## Керування доступом (групи)

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

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

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

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

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

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

## Long-polling vs 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`) ігноруються протягом короткого вікна повтору.
  - Сплески трафіку обмежуються за частотою для кожного path/source і можуть повертати HTTP 429.

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

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

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

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

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

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

| Функція                     | Статус                                  |
| --------------------------- | --------------------------------------- |
| Особисті повідомлення       | ✅ Підтримується                        |
| Групи                       | ❌ Недоступно для ботів Marketplace     |
| Медіа (вхідні зображення)   | ⚠️ Обмежено / перевірте у своєму середовищі |
| Медіа (вихідні зображення)  | ⚠️ Не перевірялося повторно для ботів Marketplace |
| Звичайні URL у тексті       | ✅ Підтримується                        |
| Попередній перегляд посилань| ⚠️ Ненадійно для ботів Marketplace      |
| Реакції                     | ❌ Не підтримується                     |
| Стікери                     | ⚠️ Немає відповіді агента для ботів Marketplace |
| Голосові повідомлення / аудіо / відео | ⚠️ Немає відповіді агента для ботів Marketplace  |
| Вкладення файлів            | ⚠️ Немає відповіді агента для ботів Marketplace  |
| Треди                       | ❌ Не підтримується                     |
| Опитування                  | ❌ Не підтримується                     |
| Власні команди              | ❌ Не підтримується                     |
| 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-ендпоїнт gateway доступний за налаштованим шляхом
- Переконайтеся, що polling через getUpdates не виконується (вони взаємовиключні)

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

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

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

Параметри провайдера:

- `channels.zalo.enabled`: увімкнути/вимкнути запуск каналу.
- `channels.zalo.botToken`: токен бота з Zalo Bot Platform.
- `channels.zalo.tokenFile`: читати токен зі шляху до звичайного файлу. Символічні посилання відхиляються.
- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (типово: pairing).
- `channels.zalo.allowFrom`: allowlist для DM (ID користувачів). Для `open` потрібне `"*"`. Майстер налаштування попросить числові ID.
- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (типово: allowlist). Є в конфігурації; для поточної поведінки ботів 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 проксі для API-запитів.

Параметри для кількох облікових записів:

- `channels.zalo.accounts.<id>.botToken`: токен для окремого облікового запису.
- `channels.zalo.accounts.<id>.tokenFile`: звичайний файл токена для окремого облікового запису. Символічні посилання відхиляються.
- `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`: політика груп для окремого облікового запису. Є в конфігурації; для поточної поведінки ботів 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 проксі для окремого облікового запису.

## Пов’язане

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