---
read_when:
    - Trabalhando em recursos do Zalo ou webhooks
summary: Status de suporte do bot do Zalo, recursos e configuração
title: Zalo
x-i18n:
    generated_at: "2026-04-05T12:37:01Z"
    model: gpt-5.4
    provider: openai
    source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119
    source_path: channels/zalo.md
    workflow: 15
---

# Zalo (Bot API)

Status: experimental. DMs são compatíveis. A seção [Recursos](#capabilities) abaixo reflete o comportamento atual de bots do Marketplace.

## Plugin incluído

O Zalo é distribuído como um plugin incluído nas versões atuais do OpenClaw, então builds
empacotadas normais não precisam de uma instalação separada.

Se você estiver em uma build mais antiga ou em uma instalação personalizada que exclui o Zalo, instale-o
manualmente:

- 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](/tools/plugin)

## 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.

Configuração mínima:

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

## O que é

Zalo é um aplicativo de mensagens focado no Vietnã; sua Bot API permite que o Gateway execute um bot para conversas 1:1.
É uma boa opção para suporte ou notificações quando você quer roteamento determinístico de volta para o Zalo.

Esta página reflete o comportamento atual do OpenClaw para **bots Zalo Bot Creator / Marketplace**.
**Bots Zalo Official Account (OA)** pertencem a uma superfície de produto diferente do Zalo e podem se comportar de forma diferente.

- 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](#capabilities) 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](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)

Exemplo:

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

Se mais tarde você migrar para uma superfície de bot do Zalo em que grupos estejam disponíveis, poderá adicionar explicitamente configurações específicas de grupo, como `groupPolicy` e `groupAllowFrom`. Para o comportamento atual de bots do Marketplace, consulte [Recursos](#capabilities).

Opção de env: `ZALO_BOT_TOKEN=...` (funciona apenas para a conta padrão).

Suporte a múltiplas contas: use `channels.zalo.accounts` com tokens por conta e `name` opcional.

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/pairing)
- `channels.zalo.allowFrom` aceita IDs numéricos de usuário (não há busca por nome de usuário).

## Controle de acesso (Grupos)

Para **bots Zalo Bot Creator / Marketplace**, o suporte a grupos não estava disponível na prática porque o bot não podia ser adicionado a um grupo.

Isso significa que as chaves de configuração relacionadas a grupos abaixo existem no schema, mas não eram utilizáveis para bots do Marketplace:

- `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.

Os valores de política de grupo (quando o acesso a grupos estiver disponível na superfície do seu bot) são:

- `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.

Se você estiver usando uma superfície de produto de bot do Zalo diferente e tiver verificado comportamento de grupo funcional, documente isso separadamente em vez de assumir que corresponde ao fluxo de bots do Marketplace.

## 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.

**Observação:** `getUpdates` (polling) e webhook são mutuamente exclusivos segundo a documentação da API do Zalo.

## Tipos de mensagem compatíveis

Para uma visão rápida do suporte, consulte [Recursos](#capabilities). As observações abaixo acrescentam detalhes quando o comportamento exige contexto adicional.

- **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](#capabilities); eles não acionavam uma resposta de forma confiável.
- **Mensagens de imagem**: consulte o status de bots do Marketplace em [Recursos](#capabilities); 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](#capabilities).
- **Notas de voz / arquivos de áudio / vídeo / anexos de arquivo genéricos**: consulte o status de bots do Marketplace em [Recursos](#capabilities).
- **Tipos não compatíveis**: registrados em log (por exemplo, mensagens de usuários protegidos).

## Recursos

Esta tabela resume o comportamento atual de **bots Zalo Bot Creator / Marketplace** no OpenClaw.

| Recurso                     | Status                                  |
| --------------------------- | --------------------------------------- |
| Mensagens diretas           | ✅ Compatível                           |
| Grupos                      | ❌ Não disponível para bots do Marketplace |
| Mídia (imagens de entrada)  | ⚠️ Limitado / verifique no seu ambiente |
| Mídia (imagens de saída)    | ⚠️ Não testado novamente para bots do Marketplace |
| URLs simples no texto       | ✅ Compatível                           |
| Prévias de link             | ⚠️ Pouco confiáveis para bots do Marketplace |
| Reações                     | ❌ Não compatível                       |
| Stickers                    | ⚠️ Sem resposta do agente para bots do Marketplace |
| Notas de voz / áudio / vídeo | ⚠️ Sem resposta do agente para bots do Marketplace |
| Anexos de arquivo           | ⚠️ Sem resposta do agente para bots do Marketplace |
| Threads                     | ❌ Não compatível                       |
| Enquetes                    | ❌ Não compatível                       |
| Comandos nativos            | ❌ Não compatível                       |
| Streaming                   | ⚠️ Bloqueado (limite de 2000 caracteres) |

## 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

**O bot não responde:**

- 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`

**Webhook não recebe eventos:**

- 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)

Configuração completa: [Configuration](/gateway/configuration)

As chaves planas de nível superior (`channels.zalo.botToken`, `channels.zalo.dmPolicy` e similares) são um atalho legado de conta única. Para novas configurações, prefira `channels.zalo.accounts.<id>.*`. Ambas as formas ainda estão documentadas aqui porque existem no schema.

Opções do provedor:

- `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](#capabilities) e [Controle de acesso (Grupos)](#access-control-groups) 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.

Opções de múltiplas contas:

- `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](#capabilities) e [Controle de acesso (Grupos)](#access-control-groups) 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](/channels) — todos os canais compatíveis
- [Pareamento](/channels/pairing) — autenticação por DM e fluxo de pareamento
- [Grupos](/channels/groups) — comportamento de chat em grupo e controle por menção
- [Roteamento de canais](/channels/channel-routing) — roteamento de sessão para mensagens
- [Segurança](/gateway/security) — modelo de acesso e reforço de segurança
