> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zazzinternet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Visão geral da Channel API do Zazz Chat: autenticação, scopes, modelo assíncrono e logs

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](/guias/webhooks).

```
https://{host}/channel-api/...
```

Substitua `{host}` pelo host do back-end da sua instalação.

## Autenticação

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

| Credencial            | Header                          | Rotas                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chave de API do canal | `x-channel-api-key: <chave>`    | [Enviar mensagem](/api-reference/endpoint/enviar-mensagem)                                                                                                                                                                                                                                                                                                                                                     |
| API key de conta      | `Authorization: ApiKey <token>` | [Listar conversas](/api-reference/endpoint/listar-conversas), [Transferir para equipe](/api-reference/endpoint/transferir-para-equipe), [Transferir para usuário](/api-reference/endpoint/transferir-para-usuario), [Capturar atendimento](/api-reference/endpoint/capturar-atendimento), [Listar equipes](/api-reference/endpoint/listar-equipes), [Listar usuários](/api-reference/endpoint/listar-usuarios) |

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

<Steps>
  <Step title="Acesse as API Keys">
    No painel, vá em **Configurações → API Keys**. A tela exige a permissão `api_keys:manage`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

| Scope            | Libera                                           |
| ---------------- | ------------------------------------------------ |
| `chats:read`     | Listar conversas                                 |
| `chats:transfer` | Transferir para equipe e transferir para usuário |
| `chats:capture`  | Capturar atendimento para um usuário             |
| `teams:read`     | Listar equipes                                   |
| `users:read`     | Listar usuários                                  |

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

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:

<Steps>
  <Step title="Acesse as configurações do canal">
    No painel, vá em **Dashboard → Suporte → Canais**, escolha o canal e abra **Configurações**.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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