Zalo

Статус: експериментальний. Реалізовано як прямі повідомлення, так і групові чати; наведена нижче таблиця Можливості відображає перевірену поведінку ботів Zalo Bot Creator / Marketplace.

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

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

У старішій збірці або спеціальній інсталяції, з якої виключено Zalo, установіть пакет npm безпосередньо:

• Установлення: openclaw plugins install @openclaw/zalo
• Закріплена версія: openclaw plugins install @openclaw/zalo@2026.6.11
• З локальної робочої копії: openclaw plugins install ./path/to/local/zalo-plugin
• Докладніше: Плагіни

Швидке налаштування

1. Створіть токен бота на https://bot.zaloplatforms.com (увійдіть, створіть бота, налаштуйте параметри). Токен має формат numeric_id:secret; для ботів Marketplace придатний до використання токен середовища виконання може міститися у вітальному повідомленні бота.
2. Задайте токен як змінну середовища ZALO_BOT_TOKEN=... (лише для облікового запису за замовчуванням) або в конфігурації.
3. Перезапустіть Gateway.
4. Підтвердьте код сполучення під час першого контакту через прямі повідомлення (типова політика прямих повідомлень — сполучення).

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

{  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.
• У групах для запуску бота потрібна @згадка; це не можна налаштувати окремо для каналу.

Обмеження

Керування доступом

Прямі повідомлення

• channels.zalo.dmPolicy: pairing (за замовчуванням) | allowlist | open | disabled.
• Сполучення: невідомі відправники отримують код сполучення; повідомлення ігноруються до підтвердження. Термін дії кодів спливає через 1 годину.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Докладніше: Сполучення
• channels.zalo.allowFrom приймає числові ідентифікатори користувачів Zalo (пошук за іменем користувача не підтримується). Для open потрібно вказати "*".

Групи

Групові чати підтримуються плагіном (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 має містити 8–256 символів.
  • Zalo надсилає події із заголовком X-Bot-Api-Secret-Token, який перевіряється порівнянням зі сталим часом виконання.
  • HTTP-сервер Gateway обробляє запити Webhook за шляхом channels.zalo.webhookPath (за замовчуванням використовується шлях з URL-адреси Webhook).
  • Запити мають використовувати Content-Type: application/json (або тип медіа з суфіксом +json).
  • Відповідно до документації Zalo API, опитування getUpdates і Webhook є взаємовиключними.

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

• Текст: повна підтримка з поділом на фрагменти по 2000 символів.
• Медіафайли: вхідні й вихідні, з обмеженням mediaMaxMb.
• Реакції, гілки, опитування, вбудовані команди: не підтримуються плагіном.
• Потокове передавання: плагін заявляє можливість блокового потокового передавання, але Zalo не має спеціальних параметрів налаштування вихідної черги чи обʼєднання тексту (на відміну від деяких інших регіональних каналів); якщо це важливо для вашого сценарію використання, перевірте поточну поведінку у своєму середовищі.

Можливості

Цілі доставлення (CLI/cron)

Використовуйте ідентифікатор чату як ціль:

openclaw message send --channel zalo --target 123456789 --message "hi"

Усунення несправностей

Бот не відповідає:

• Перевірте токен: openclaw channels status --probe
• Переконайтеся, що відправника схвалено (через сполучення або allowFrom)
• Перевірте журнали Gateway: openclaw logs --follow

Webhook не отримує події:

• Переконайтеся, що URL-адреса Webhook використовує HTTPS
• Переконайтеся, що секрет містить 8–256 символів
• Переконайтеся, що кінцева точка HTTP-сервера Gateway доступна за налаштованим шляхом
• Переконайтеся, що опитування getUpdates не виконується одночасно (вони є взаємовиключними)
• Сплеск запитів може призвести до відповіді HTTP 429 (120 запитів / 60 с для кожної комбінації шляху й IP-адреси); збільште інтервал і повторіть спробу

Довідник конфігурації

Повна конфігурація: Конфігурація

channels.zalo.botToken, channels.zalo.dmPolicy та інші плоскі ключі верхнього рівня є застароченими скороченнями для одного облікового запису, що відповідають наведеним вище полям; підтримуються обидві форми.

Змінна середовища: ZALO_BOT_TOKEN=... визначає токен лише для облікового запису за замовчуванням.

Повʼязані матеріали

• Огляд каналів — усі підтримувані канали
• Сполучення — автентифікація прямих повідомлень і процес сполучення
• Групи — поведінка групових чатів і обмеження за згадкою
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу й посилення захисту