--- read_when: - Робота над функціями Zalo або Webhook summary: Стан підтримки бота Zalo, можливості та налаштування title: Zalo x-i18n: generated_at: "2026-05-02T21:58:37Z" model: gpt-5.5 provider: openai source_hash: 6226af1217e1e8b03b485df99f6375872b487f7040c091f2bb2d85e18dec75d0 source_path: channels/zalo.md workflow: 16 --- Статус: експериментальний. 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 { 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 { 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 ` - 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..*`. Обидві форми все ще задокументовані тут, бо вони існують у схемі. Опції провайдера: - `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..botToken`: токен для кожного облікового запису. - `channels.zalo.accounts..tokenFile`: звичайний файл токена для кожного облікового запису. Symlink відхиляються. - `channels.zalo.accounts..name`: відображуване ім'я. - `channels.zalo.accounts..enabled`: увімкнути/вимкнути обліковий запис. - `channels.zalo.accounts..dmPolicy`: політика DM для кожного облікового запису. - `channels.zalo.accounts..allowFrom`: allowlist для кожного облікового запису. - `channels.zalo.accounts..groupPolicy`: групова політика для кожного облікового запису. Присутня в config; поточну поведінку ботів Marketplace див. у [Можливостях](#capabilities) і [Контролі доступу (групи)](#access-control-groups). - `channels.zalo.accounts..groupAllowFrom`: allowlist відправників у групах для кожного облікового запису. - `channels.zalo.accounts..webhookUrl`: URL webhook для кожного облікового запису. - `channels.zalo.accounts..webhookSecret`: секрет webhook для кожного облікового запису. - `channels.zalo.accounts..webhookPath`: шлях webhook для кожного облікового запису. - `channels.zalo.accounts..proxy`: URL proxy для кожного облікового запису. ## Пов'язане - [Огляд каналів](/uk/channels) — усі підтримувані канали - [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing - [Групи](/uk/channels/groups) — поведінка групових чатів і gate за згадкою - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Безпека](/uk/gateway/security) — модель доступу й посилення захисту