Платформы обмена сообщениями

Zalo

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

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

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

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

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

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

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

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

Что это такое

Zalo — это мессенджер, ориентированный на Вьетнам; его Bot API позволяет Шлюзу запускать бота для общения один на один. Он хорошо подходит для поддержки или уведомлений, где требуется детерминированная маршрутизация обратно в Zalo.

  • Канал Zalo Bot API, управляемый Шлюзом.
  • Детерминированная маршрутизация: ответы всегда отправляются обратно в Zalo; модель никогда не выбирает каналы.
  • Личные сообщения используют основную сессию агента.
  • Группы поддерживаются с контролем политик (groupPolicy + groupAllowFrom) и по умолчанию используют поведение "закрытый список разрешений" (fail-closed allowlist).

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

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.

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

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

  • Входящие сообщения нормализуются в общий канальный конверт с заполнителями для медиа.
  • Ответы всегда маршрутизируются обратно в тот же чат 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 <КОД>
  • Сопряжение — это стандартный обмен токенами. Подробности: Сопряжение
  • channels.zalo.allowFrom принимает числовые идентификаторы пользователей (поиск по имени пользователя недоступен).

Контроль доступа (Группы)

  • channels.zalo.groupPolicy управляет обработкой входящих сообщений из групп: open | allowlist | disabled.
  • Поведение по умолчанию — "закрытый список разрешений" (fail-closed): allowlist.
  • channels.zalo.groupAllowFrom ограничивает, какие идентификаторы отправителей могут активировать бота в группах.
  • Если groupAllowFrom не задан, Zalo использует allowFrom для проверки отправителя.
  • groupPolicy: "disabled" блокирует все сообщения из групп.
  • groupPolicy: "open" разрешает сообщения от любого участника группы (с упоминанием бота).
  • Примечание для времени выполнения: если channels.zalo полностью отсутствует, среда выполнения всё равно откатывается к groupPolicy="allowlist" для безопасности.

Long-polling против вебхука

  • По умолчанию: long-polling (не требует публичного URL).
  • Режим вебхука: задайте channels.zalo.webhookUrl и channels.zalo.webhookSecret.
    • Секрет вебхука должен содержать от 8 до 256 символов.
    • URL вебхука должен использовать HTTPS.
    • Zalo отправляет события с заголовком X-Bot-Api-Secret-Token для проверки.
    • HTTP-сервер шлюза обрабатывает запросы вебхука по пути channels.zalo.webhookPath (по умолчанию используется путь из URL вебхука).
    • Запросы должны использовать Content-Type: application/json (или медиатипы +json).
    • Дублирующиеся события (event_name + message_id) игнорируются в течение короткого окна повторной передачи.
    • Пиковая нагрузка ограничивается по скорости на путь/источник и может возвращать HTTP 429.

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

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

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

Возможности

ФункцияСтатус
Личные сообщения✅ Поддерживается
Группы⚠️ Поддерживается с контролем политик (по умолчанию — список разрешений)
Медиа (изображения)✅ Поддерживается
Реакции❌ Не поддерживается
Ветки обсуждений❌ Не поддерживается
Опросы❌ Не поддерживается
Нативные команды❌ Не поддерживается
Потоковая передача⚠️ Заблокирована (ограничение в 2000 символов)

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

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

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

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

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

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

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

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

Полная конфигурация: Конфигурация Параметры провайдера:

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

WhatsAppZalo Personal