Zalo

Status: experimental. Mensagens diretas e conversas em grupo estão implementadas; a tabela de Recursos abaixo reflete o comportamento verificado em bots do Zalo Bot Creator / Marketplace.

Plugin incluído

O Zalo é distribuído como um Plugin incluído nas versões atuais do OpenClaw, portanto, builds empacotados não precisam de uma instalação separada.

Em um build mais antigo ou em uma instalação personalizada que exclua o Zalo, instale o pacote npm diretamente:

• Instalar: openclaw plugins install @openclaw/zalo
• Versão fixada: openclaw plugins install @openclaw/zalo@2026.6.11
• De um checkout local: openclaw plugins install ./path/to/local/zalo-plugin
• Detalhes: Plugins

Configuração rápida

1. Crie um token de bot em https://bot.zaloplatforms.com (entre na conta, crie um bot e defina as configurações). O token tem o formato numeric_id:secret; para bots do Marketplace, o token utilizável em tempo de execução pode aparecer na mensagem de boas-vindas do bot.
2. Defina o token como a variável de ambiente ZALO_BOT_TOKEN=... (somente para a conta padrão) ou na configuração.
3. Reinicie o Gateway.
4. Aprove o código de pareamento no primeiro contato por mensagem direta (a política padrão de mensagens diretas é o pareamento).

Configuração mínima:

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

Várias contas: adicione mais entradas em channels.zalo.accounts.<id>, cada uma com seu próprio botToken/name. channels.zalo.botToken (estrutura simples, sem accounts) é uma forma abreviada legada para uma única conta; prefira accounts.<id>.* em novas configurações.

O que é

O Zalo é um aplicativo de mensagens voltado ao Vietnã. Sua API de bots permite que o Gateway execute um bot tanto em conversas individuais quanto em conversas em grupo, com roteamento determinístico de volta ao Zalo (o modelo nunca escolhe os canais).

Esta página aborda bots do Zalo Bot Creator / Marketplace. Os bots de Conta Oficial (OA) do Zalo pertencem a uma superfície de produto diferente e podem se comportar de forma distinta; esta página não os aborda.

Como funciona

• As mensagens recebidas são normalizadas no envelope compartilhado do canal, com espaços reservados para mídia.
• As respostas sempre são roteadas de volta à mesma conversa do Zalo; respostas com citação não são usadas (replyToMode permanece desativado).
• Por padrão, usa sondagem longa (getUpdates); o modo Webhook está disponível por meio de channels.zalo.webhookUrl.
• Em grupos, é necessário mencionar o bot com @ para acioná-lo; isso não pode ser configurado por canal.

Limites

Controle de acesso

Mensagens diretas

• channels.zalo.dmPolicy: pairing (padrão) | allowlist | open | disabled.
• Pareamento: remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até a aprovação. Os códigos expiram após 1 hora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Detalhes: Pareamento
• channels.zalo.allowFrom aceita IDs numéricos de usuários do Zalo (sem consulta por nome de usuário). open exige "*".

Grupos

As conversas em grupo são compatíveis com o Plugin (chatTypes: ["direct", "group"]) e são controladas pela menção e pela política de grupos:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe quais IDs de remetentes podem acionar o bot em grupos; quando não definido, usa allowFrom.
• Resolução padrão: quando channels.zalo está configurado, um groupPolicy não definido é resolvido como open. Quando channels.zalo está completamente ausente, o tempo de execução aplica allowlist como opção segura.
• Ressalva relatada em uso real: em algumas configurações de bots do Marketplace, não foi possível adicionar o bot a nenhum grupo. Se isso acontecer, verifique as configurações do seu bot na Zalo Bot Platform; trata-se de uma restrição da plataforma, não de uma política do OpenClaw.

Sondagem longa versus Webhook

• Padrão: sondagem longa (não requer URL pública).
• Modo Webhook: defina channels.zalo.webhookUrl e channels.zalo.webhookSecret.
  • A URL do Webhook deve usar HTTPS.
  • O segredo do Webhook deve ter entre 8 e 256 caracteres.
  • O Zalo envia eventos com um cabeçalho X-Bot-Api-Secret-Token, verificado por meio de uma comparação em tempo constante.
  • O HTTP do Gateway processa as solicitações de Webhook em channels.zalo.webhookPath (o padrão é o caminho da URL do Webhook).
  • As solicitações devem usar Content-Type: application/json (ou um tipo de mídia +json).
  • A sondagem por getUpdates e o Webhook são mutuamente exclusivos, conforme a documentação da API do Zalo.

Tipos de mensagem compatíveis

• Texto: compatibilidade total, dividido em blocos de 2.000 caracteres.
• Mídia: recebimento e envio, limitados por mediaMaxMb.
• Reações, tópicos, enquetes e comandos nativos: não são compatíveis com o Plugin.
• Transmissão contínua: o Plugin declara o recurso de transmissão em blocos, mas o Zalo não possui opções específicas para ajustar a fila de envio ou a mesclagem de texto (ao contrário de alguns outros canais regionais); verifique o comportamento atual no seu ambiente se isso for importante para seu caso de uso.

Recursos

Destinos de entrega (CLI/Cron)

Use um ID de conversa como destino:

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

Solução de problemas

O bot não responde:

• Verifique o token: openclaw channels status --probe
• Verifique se o remetente está aprovado (pareamento ou allowFrom)
• Verifique os logs do Gateway: openclaw logs --follow

O Webhook não está recebendo eventos:

• Confirme que a URL do Webhook usa HTTPS
• Confirme que o segredo tem entre 8 e 256 caracteres
• Confirme que o endpoint HTTP do Gateway está acessível no caminho configurado
• Confirme que a sondagem por getUpdates também não está em execução (eles são mutuamente exclusivos)
• Uma rajada de solicitações pode retornar HTTP 429 (120 solicitações / 60 s por caminho+IP); aguarde e tente novamente

Referência de configuração

Configuração completa: Configuração

channels.zalo.botToken, channels.zalo.dmPolicy e outras chaves simples de nível superior são formas abreviadas legadas para uma única conta correspondentes aos campos acima; ambas as formas são compatíveis.

Opção de ambiente: ZALO_BOT_TOKEN=... resolve somente o token da conta padrão.

Relacionados

• Visão geral dos canais - todos os canais compatíveis
• Pareamento - autenticação de mensagens diretas e fluxo de pareamento
• Grupos - comportamento de conversas em grupo e exigência de menções
• Roteamento de canais - roteamento de sessões para mensagens
• Segurança - modelo de acesso e proteção