Skip to main content
A Channel API permite que sistemas externos (ERP, CRM, automações) enviem mensagens por um canal do Zazz Chat, roteiem conversas entre equipes e atendentes e recebam eventos via webhook.
Substitua {host} pelo host do back-end da sua instalação.

​
Autenticação

A API usa duas credenciais. Cada rota aceita uma delas:

​
API key de conta

A API key de conta pertence à conta, não a um canal. Ela define quais canais pode acessar e quais ações pode executar (scopes).
1

Acesse as API Keys

No painel, vá em Configurações → API Keys. A tela exige a permissão api_keys:manage.
2

Crie a key

Clique em Criar API key, dê um nome e escolha Todos os canais ou canais específicos. Marque só os scopes que a integração usa.
3

Copie o token

O token (zk_live_...) aparece uma única vez. Envie como Authorization: ApiKey zk_live_.... Se ele vazar, revogue a key ou rotacione para gerar um token novo.
Key sem o scope da rota, channelId fora dos canais da key ou conversa de um canal fora da key respondem 404, não 403. A API não confirma a existência de recursos que a key não pode ver. Credencial ausente, inválida ou revogada responde 401.
As rotas da API key de conta têm limite de 120 requisições por minuto por key. Acima disso, a resposta é 429.

​
Chave de API do canal

A chave de API do canal é usada no envio de mensagens. Ela é por canal e é gerada dentro do sistema:
1

Acesse as configurações do canal

No painel, vá em Dashboard → Suporte → Canais, escolha o canal e abra Configurações.
2

Abra a aba API

Ative a API do canal e, se quiser, defina o nome da fila de atendimento usada pelos chats criados via API (padrão: API).
3

Gere a chave

Clique em Gerar chave. A chave completa é exibida uma única vez — copie e guarde em local seguro. Depois disso, o sistema mostra apenas um preview. Gerar uma nova chave invalida a anterior.
A API precisa estar habilitada na aba API do canal. Com a API desabilitada, qualquer requisição retorna 404 Invalid API token, mesmo com a chave correta.

​
Modelo assíncrono

O envio de mensagens é assíncrono: a requisição enfileira a mensagem e retorna imediatamente um requestId. O processamento (criação/reabertura do chat, envio ao provider) acontece em background.
  • O chat criado ou reaberto pelo envio entra na fila configurada na aba API do canal (padrão API).
  • O status de cada envio (queued, sucesso ou falha, incluindo erros do provider) fica nos logs da aba API do canal, pesquisáveis pelo requestId.
  • Requisições que falharam podem ser reenviadas manualmente pelos logs.

​
Retry automático de templates

Para mensagens de template que falham no provider com erros temporários de pareamento (códigos Meta 138002 e 138005), o sistema reenfileira automaticamente o envio com atraso de 2 minutos, até 5 tentativas. Os retries aparecem no histórico do log com status retry_auto.