Перейти до основного вмісту

​
Zalo (Bot API)

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

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

Zalo постачається як вбудований плагін у поточних релізах OpenClaw, тому звичайні зібрані збірки не потребують окремого встановлення. Якщо ви використовуєте старішу збірку або спеціальне встановлення без Zalo, установіть його вручну:
  • Установлення через CLI: openclaw plugins install @openclaw/zalo
  • Або з локальної копії вихідного коду: openclaw plugins install ./path/to/local/zalo-plugin
  • Докладніше: Плагіни

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

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

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

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

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

​
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.
  1. Перезапустіть gateway. Zalo запускається, коли визначено токен (через env або config).
  2. Доступ до 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.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.

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

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

​
Можливості

Ця таблиця підсумовує поточну поведінку ботів 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)

Повна конфігурація: Конфігурація Плоскі ключі верхнього рівня (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 див. Можливості і Керування доступом (групи).
  • 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 див. Можливості і Керування доступом (групи).
  • 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 проксі для окремого облікового запису.

​
Пов’язане