​

Zalo (Bot API)

​

Plugin incluído

• Instalar via CLI: openclaw plugins install @openclaw/zalo
• Ou a partir de um checkout do código-fonte: openclaw plugins install ./path/to/local/zalo-plugin
• Detalhes: Plugins

​

Configuração rápida (iniciante)

1. Verifique se o plugin Zalo está disponível.
   • As versões empacotadas atuais do OpenClaw já o incluem.
   • Instalações antigas/personalizadas podem adicioná-lo manualmente com os comandos acima.
2. Defina o token:
   • Env: ZALO_BOT_TOKEN=...
   • Ou configuração: channels.zalo.accounts.default.botToken: "...".
3. Reinicie o gateway (ou conclua a configuração).
4. O acesso por DM usa pareamento por padrão; aprove o código de pareamento no primeiro contato.

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

​

O que é

• Um canal Zalo Bot API controlado pelo Gateway.
• Roteamento determinístico: respostas voltam para o Zalo; o modelo nunca escolhe canais.
• DMs compartilham a sessão principal do agente.
• A seção Recursos abaixo mostra o suporte atual para bots do Marketplace.

​

Configuração (caminho rápido)

​

1) Criar um token de bot (Zalo Bot Platform)

1. Acesse https://bot.zaloplatforms.com e faça login.
2. Crie um novo bot e configure suas definições.
3. Copie o token completo do bot (normalmente numeric_id:secret). Para bots do Marketplace, o token de runtime utilizável pode aparecer na mensagem de boas-vindas do bot após a criação.

​

2) Configurar o token (env ou config)

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

3. Reinicie o gateway. O Zalo é iniciado quando um token é resolvido (env ou config).
4. O acesso por DM usa pareamento por padrão. Aprove o código quando o bot for contatado pela primeira vez.

​

Como funciona (comportamento)

• Mensagens de entrada são normalizadas para o envelope de canal compartilhado com placeholders de mídia.
• As respostas sempre são roteadas de volta para o mesmo chat do Zalo.
• Long-polling por padrão; modo webhook disponível com channels.zalo.webhookUrl.

​

Limites

• Texto de saída é fragmentado em blocos de 2000 caracteres (limite da API do Zalo).
• Downloads/uploads de mídia são limitados por channels.zalo.mediaMaxMb (padrão 5).
• O streaming é bloqueado por padrão, porque o limite de 2000 caracteres torna o streaming menos útil.

​

Controle de acesso (DMs)

​

Acesso por DM

• Padrão: channels.zalo.dmPolicy = "pairing". 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).
• Aprovar via:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Pareamento é a troca de token padrão. Detalhes: Pareamento
• channels.zalo.allowFrom aceita IDs numéricos de usuário (não há busca por nome de usuário).

​

Controle de acesso (Grupos)

• channels.zalo.groupPolicy controla o tratamento de entrada em grupos: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe quais IDs de remetente podem acionar o bot em grupos.
• Se groupAllowFrom não estiver definido, o Zalo usa allowFrom como fallback para verificações do remetente.
• Observação de runtime: se channels.zalo estiver totalmente ausente, o runtime ainda usa groupPolicy="allowlist" como fallback por segurança.

• groupPolicy: "disabled" — bloqueia todas as mensagens de grupo.
• groupPolicy: "open" — permite qualquer membro do grupo (controlado por menção).
• groupPolicy: "allowlist" — padrão com falha fechada; apenas remetentes permitidos são aceitos.

​

Long-polling vs webhook

• Padrão: long-polling (não exige URL pública).
• Modo webhook: defina channels.zalo.webhookUrl e channels.zalo.webhookSecret.
  • O segredo do webhook deve ter de 8 a 256 caracteres.
  • A URL do webhook deve usar HTTPS.
  • O Zalo envia eventos com o cabeçalho X-Bot-Api-Secret-Token para verificação.
  • O Gateway HTTP trata 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 tipos de mídia +json).
  • Eventos duplicados (event_name + message_id) são ignorados por uma curta janela de repetição.
  • Tráfego em rajadas é limitado por taxa por caminho/origem e pode retornar HTTP 429.

​

Tipos de mensagem compatíveis

• Mensagens de texto: suporte completo com fragmentação em 2000 caracteres.
• URLs simples no texto: comportam-se como entrada de texto normal.
• Prévias de link / cartões de link avançados: consulte o status de bots do Marketplace em Recursos; eles não acionavam uma resposta de forma confiável.
• Mensagens de imagem: consulte o status de bots do Marketplace em Recursos; o tratamento de imagens de entrada era pouco confiável (indicador de digitação sem resposta final).
• Stickers: consulte o status de bots do Marketplace em Recursos.
• Notas de voz / arquivos de áudio / vídeo / anexos de arquivo genéricos: consulte o status de bots do Marketplace em Recursos.
• Tipos não compatíveis: registrados em log (por exemplo, mensagens de usuários protegidos).

​

Recursos

​

Destinos de entrega (CLI/cron)

• Use um ID de chat como destino.
• Exemplo: openclaw message send --channel zalo --target 123456789 --message "hi".

​

Solução de problemas

• Verifique se o token é válido: openclaw channels status --probe
• Verifique se o remetente foi aprovado (pairing ou allowFrom)
• Verifique os logs do gateway: openclaw logs --follow

• Verifique se a URL do webhook usa HTTPS
• Verifique se o token secreto tem de 8 a 256 caracteres
• Confirme se o endpoint HTTP do gateway pode ser acessado no caminho configurado
• Verifique se o polling getUpdates não está em execução (são mutuamente exclusivos)

​

Referência de configuração (Zalo)

• channels.zalo.enabled: ativa/desativa a inicialização do canal.
• channels.zalo.botToken: token do bot da Zalo Bot Platform.
• channels.zalo.tokenFile: lê o token de um caminho de arquivo regular. Links simbólicos são rejeitados.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (padrão: pairing).
• channels.zalo.allowFrom: allowlist de DM (IDs de usuário). open exige "*". O assistente solicitará IDs numéricos.
• channels.zalo.groupPolicy: open | allowlist | disabled (padrão: allowlist). Presente na configuração; consulte Recursos e Controle de acesso (Grupos) para o comportamento atual de bots do Marketplace.
• channels.zalo.groupAllowFrom: allowlist de remetentes de grupo (IDs de usuário). Usa allowFrom como fallback quando não está definido.
• channels.zalo.mediaMaxMb: limite de mídia de entrada/saída (MB, padrão 5).
• channels.zalo.webhookUrl: ativa o modo webhook (HTTPS obrigatório).
• channels.zalo.webhookSecret: segredo do webhook (8-256 caracteres).
• channels.zalo.webhookPath: caminho do webhook no servidor HTTP do gateway.
• channels.zalo.proxy: URL de proxy para solicitações à API.

• channels.zalo.accounts.<id>.botToken: token por conta.
• channels.zalo.accounts.<id>.tokenFile: arquivo de token regular por conta. Links simbólicos são rejeitados.
• channels.zalo.accounts.<id>.name: nome de exibição.
• channels.zalo.accounts.<id>.enabled: ativa/desativa a conta.
• channels.zalo.accounts.<id>.dmPolicy: política de DM por conta.
• channels.zalo.accounts.<id>.allowFrom: allowlist por conta.
• channels.zalo.accounts.<id>.groupPolicy: política de grupo por conta. Presente na configuração; consulte Recursos e Controle de acesso (Grupos) para o comportamento atual de bots do Marketplace.
• channels.zalo.accounts.<id>.groupAllowFrom: allowlist de remetentes de grupo por conta.
• channels.zalo.accounts.<id>.webhookUrl: URL de webhook por conta.
• channels.zalo.accounts.<id>.webhookSecret: segredo de webhook por conta.
• channels.zalo.accounts.<id>.webhookPath: caminho de webhook por conta.
• channels.zalo.accounts.<id>.proxy: URL de proxy por conta.

​

Relacionado

• Visão geral dos canais — todos os canais compatíveis
• Pareamento — autenticação por DM e fluxo de pareamento
• Grupos — comportamento de chat em grupo e controle por menção
• Roteamento de canais — roteamento de sessão para mensagens
• Segurança — modelo de acesso e reforço de segurança