Zalo (Bot API)¶

Статус: экспериментальный. Только личные сообщения; группы появятся в ближайшее время согласно документации Zalo.

Требуется плагин¶

Zalo поставляется в виде плагина и не входит в базовую установку.

• Установка через CLI: openclaw plugins install @openclaw/zalo
• Или выберите Zalo во время онбординга и подтвердите запрос на установку
• Подробности: Plugins

Быстрая настройка (для начинающих)¶

1. Установите плагин Zalo: - Из исходного репозитория: openclaw plugins install ./extensions/zalo - Из npm (если опубликован): openclaw plugins install @openclaw/zalo - Или выберите Zalo в онбординге и подтвердите запрос на установку
2. Установите токен: - Env: ZALO_BOT_TOKEN=... - Или конфиг: channels.zalo.botToken: "...".
3. Перезапустите Gateway (шлюз) (или завершите онбординг).
4. Доступ к личным сообщениям по умолчанию — через сопряжение; подтвердите код сопряжения при первом контакте.

Минимальный конфиг:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Что это такое¶

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

• Канал Zalo Bot API, принадлежащий Gateway (шлюзу).
• Детерминированная маршрутизация: ответы всегда возвращаются в Zalo; модель не выбирает каналы.
• ЛС разделяют основную сессию агента.
• Группы пока не поддерживаются (в документации Zalo указано «coming soon»).

Настройка (быстрый путь)¶

1. Создайте токен бота (Zalo Bot Platform)¶

1. Перейдите на https://bot.zaloplatforms.com и войдите.
2. Создайте нового бота и настройте его параметры.
3. Скопируйте токен бота (формат: 12345689:abc-xyz).

2) Настройте токен (переменные окружения или конфиг)¶

Пример:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Вариант через переменные окружения: ZALO_BOT_TOKEN=... (работает только для учетной записи по умолчанию).

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

3. Перезапустите Gateway (шлюз). Zalo запускается, когда токен определен (через переменные окружения или конфиг).
4. Доступ к личным сообщениям по умолчанию — через сопряжение. Подтвердите код при первом обращении к боту.

Как это работает (поведение)¶

• Входящие сообщения нормализуются в общий конверт канала с плейсхолдерами медиа.
• Ответы всегда маршрутизируются обратно в тот же чат Zalo.
• По умолчанию используется long-polling; режим вебхука доступен с channels.zalo.webhookUrl.

Ограничения¶

• Исходящий текст разбивается на фрагменты по 2000 символов (ограничение API Zalo).
• Загрузка/выгрузка медиа ограничена параметром channels.zalo.mediaMaxMb (по умолчанию 5).
• Стриминг по умолчанию заблокирован, так как лимит в 2000 символов делает его менее полезным.

Контроль доступа (личные сообщения)¶

Доступ к ЛС¶

• По умолчанию: channels.zalo.dmPolicy = "pairing". Неизвестные отправители получают код сопряжения; сообщения игнорируются до подтверждения (коды истекают через 1 час).
• Подтверждение через:
• openclaw pairing list zalo
• openclaw pairing approve zalo <CODE>
• Сопряжение — стандартный обмен токенами. Подробности: Pairing
• channels.zalo.allowFrom принимает числовые идентификаторы пользователей (поиск по имени пользователя недоступен).

Long-polling vs вебхук¶

• По умолчанию: long-polling (публичный URL не требуется).
• Режим вебхука: установите channels.zalo.webhookUrl и channels.zalo.webhookSecret.
• Секрет вебхука должен быть длиной 8–256 символов.
• URL вебхука должен использовать HTTPS.
• Zalo отправляет события с заголовком X-Bot-Api-Secret-Token для проверки.
• Gateway (шлюз) HTTP обрабатывает запросы вебхука по адресу channels.zalo.webhookPath (по умолчанию — путь URL вебхука).

Примечание: getUpdates (polling) и вебхук взаимоисключающи согласно документации API Zalo.

Поддерживаемые типы сообщений¶

• Текстовые сообщения: полная поддержка с разбиением по 2000 символов.
• Изображения: загрузка и обработка входящих изображений; отправка изображений через sendPhoto.
• Стикеры: логируются, но не полностью обрабатываются (без ответа агента).
• Неподдерживаемые типы: логируются (например, сообщения от защищенных пользователей).

Возможности¶

Цели доставки (CLI/cron)¶

• Используйте идентификатор чата в качестве цели.
• Пример: openclaw message send --channel zalo --target 123456789 --message "hi".

Устранение неполадок¶

Бот не отвечает:

• Проверьте валидность токена: openclaw channels status --probe
• Убедитесь, что отправитель одобрен (сопряжение или allowFrom)
• Проверьте логи Gateway (шлюза): openclaw logs --follow

Вебхук не получает события:

• Убедитесь, что URL вебхука использует HTTPS
• Проверьте, что секретный токен имеет длину 8–256 символов
• Подтвердите, что HTTP‑эндпоинт Gateway (шлюза) доступен по настроенному пути
• Убедитесь, что polling getUpdates не запущен (они взаимоисключающи)

Справочник конфигурации (Zalo)¶

Полная конфигурация: Configuration

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

• channels.zalo.enabled: включить/отключить запуск канала.
• channels.zalo.botToken: токен бота из Zalo Bot Platform.
• channels.zalo.tokenFile: читать токен из файла по пути.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: сопряжение).
• channels.zalo.allowFrom: список разрешённых для личных сообщений (ID пользователей). open требует "*". Мастер настройки запросит числовые ID.
• channels.zalo.mediaMaxMb: лимит медиа для входящих/исходящих (МБ, по умолчанию 5).
• channels.zalo.webhookUrl: включить режим вебхука (требуется HTTPS).
• channels.zalo.webhookSecret: секрет вебхука (8–256 символов).
• channels.zalo.webhookPath: путь вебхука на 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: политика личных сообщений для учетной записи.
• channels.zalo.accounts.<id>.allowFrom: список разрешённых для учетной записи.
• channels.zalo.accounts.<id>.webhookUrl: URL вебхука для учетной записи.
• channels.zalo.accounts.<id>.webhookSecret: секрет вебхука для учетной записи.
• channels.zalo.accounts.<id>.webhookPath: путь вебхука для учетной записи.
• channels.zalo.accounts.<id>.proxy: URL прокси для учетной записи.