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

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.

3. Перезапустите шлюз. 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 <КОД>
• Сопряжение — это стандартный обмен токенами. Подробности: Сопряжение
• 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..botToken: токен для каждой учётной записи.
• channels.zalo.accounts..tokenFile: файл токена для каждой учётной записи.
• channels.zalo.accounts..name: отображаемое имя.
• channels.zalo.accounts..enabled: включить/отключить учётную запись.
• channels.zalo.accounts..dmPolicy: политика личных сообщений для каждой учётной записи.
• channels.zalo.accounts..allowFrom: список разрешений для каждой учётной записи.
• channels.zalo.accounts..groupPolicy: политика групп для каждой учётной записи.
• channels.zalo.accounts..groupAllowFrom: список разрешений отправителей в группах для каждой учётной записи.
• channels.zalo.accounts..webhookUrl: URL вебхука для каждой учётной записи.
• channels.zalo.accounts..webhookSecret: секрет вебхука для каждой учётной записи.
• channels.zalo.accounts..webhookPath: путь вебхука для каждой учётной записи.
• channels.zalo.accounts..proxy: URL прокси для каждой учётной записи.

WhatsAppZalo Personal