Boas Práticas de Integração#
Leia antes de escrever a integração (vale também para um agente de IA escrevendo o código por você). A Catcher avisa quando algo acontece; a sua integração não precisa perguntar. Integrações que consultam a API em loop para descobrir o que mudou gastam a cota de requisições da empresa, recebem
429e ficam mais lentas do que se só ouvissem os eventos.
Modelo de consumo: webhook primeiro#
| Você quer saber… | Caminho certo | Não faça |
|---|---|---|
| Se uma mensagem saiu, chegou, foi lida ou ouvida | Eventos *.sent, *.delivered, *.read, *.played, *.delivery_failed no webhook |
GET /v1/instances/{id}/message/{messageId} em loop |
| Se chegou mensagem nova | Evento *.received no webhook |
Listar /chats ou /messages a cada minuto |
| Se a instância caiu, voltou ou foi desconectada | Eventos connection.update, instance.offline, instance.recovered e instance.banned |
GET /v1/instances/{id} a cada minuto |
| O que você perdeu enquanto o seu servidor esteve fora | GET /v1/instances/{id}/events/history?after=<último event_id> (paginado por cursor) |
Um GET por mensagem pendente |
| Se as entregas do webhook estão em dia | O próprio webhook: a Catcher entrega em ordem e retenta sozinho; o Console mostra a fila | Consultar o histórico de entregas a cada 2 minutos |
- Crie um webhook (
POST /v1/webhooks) assinando os eventos de que você precisa. Um nome genérico cobre os específicos:message.sentassinatext.sent,image.sent,audio.sent… (os eventos chegam com o tipo de conteúdo no nome, ex.:text.delivered; o tipo também vem emdata.message_type). - Verifique a assinatura de cada entrega: HMAC-SHA256 de
X-Catcher-Timestamp + "." + corpo_crucom osecretdo webhook, comparado em tempo constante comX-Catcher-Signature(sha256=<hex>). Recuse timestamps com mais de 5 minutos de diferença. Exemplos em Verificação de assinatura HMAC. - Responda 2xx rápido. A Catcher espera até 10 s; grave o evento numa fila/tabela sua e processe depois. Processar dentro da requisição (chamar outra API, esperar banco lento) vira timeout, e timeout vira retentativa.
- Deduplique por
event_id. A entrega é pelo menos uma vez: o mesmoevent_idpode chegar de novo depois de uma retentativa. Guarde osevent_idprocessados e ignore repetidos. - Não dependa da ordem entre eventos diferentes para decidir estado. Use a
ordem de progresso do status (
queued<sent<delivered<read<played) e nunca rebaixe: sereadjá foi gravado, umdeliveredatrasado não muda nada. - Correlacione pelo
message_id(UUID da Catcher) devolvido no202do envio — é o mesmo valor emdata.message_idsde todos os eventos daquela mensagem. Veja §22.
Envelope de todo evento (webhook, SSE e WebSocket):
{
"event_id": "ca5e3b45-055a-4ccc-be37-cb9d76d25887",
"type": "text.delivered",
"instance_id": "be23db3e-900d-4194-98ca-7a1deb2157a5",
"timestamp": "2026-11-22T14:05:12.311Z",
"data": { "message_ids": ["550e8400-e29b-41d4-a716-446655440000"], "message_type": "text", "...": "..." }
}
Estados finais: uma mensagem pode "terminar" sem read#
Muita gente desliga a confirmação de leitura no WhatsApp. Para essas pessoas o
read nunca chega, e uma mensagem pode ficar em delivered para sempre.
Trate assim:
| Status | É final? | O que significa |
|---|---|---|
queued |
Não | Aceita pela API, esperando a vez na fila (o envio espera alguns segundos de propósito) |
sent |
Não, mas pode demorar | Saiu para o WhatsApp. Se o celular do destinatário está desligado, o delivered chega quando ele ligar, horas ou dias depois |
delivered |
Pode ser final | Chegou no aparelho. Se a pessoa não confirma leitura, nada mais vai acontecer — e está tudo certo |
read |
Final para texto, imagem, documento | A pessoa abriu a conversa |
played |
Final para áudio, vídeo e visualização única | A pessoa ouviu/assistiu |
failed (evento *.delivery_failed) |
Final | Não foi entregue. O motivo vem em data.reason. Com data.wire_state="not_sent" é seguro reenviar; com "unknown" a mensagem pode ter chegado — confira antes de reenviar |
deleted |
Final | Apagada para todos |
cancelled (envio) |
Final | Apagada antes de sair da fila; nada foi enviado. Chega como *.deleted com pre_send: true, e a mensagem não existe mais em GET .../message/{id} (404) |
Nunca reconsulte uma mensagem "até ela ficar lida". Considere a mensagem
concluída em delivered para fins de fluxo e atualize para read/played
se o evento chegar.
Recuperar o que foi perdido: events/history#
O webhook retenta sozinho, em ordem, até o seu servidor voltar — na maioria dos
casos você não perde nada. Se mesmo assim precisar reconciliar (o seu banco foi
restaurado, você descartou eventos por engano), não faça um GET por
mensagem. Leia o histórico de eventos por cursor:
# Comece do último event_id que você processou e avance de 200 em 200
curl -H "X-API-Key: $TOKEN" \
"https://api.catcher.one/v1/instances/$INSTANCE/events/history?after=$LAST_EVENT_ID&limit=200"
# { "events": [ ... em ordem crescente ... ], "has_more": true }
# Repita com after=<event_id do último item> enquanto has_more for true.
Sem um event_id de partida, use since=<RFC3339>. Filtre com
types=message.delivered,message.read para trazer só o que interessa. O
histórico guarda 7 dias. Uma reconciliação de um dia inteiro costuma caber
em poucas requisições — contra centenas de GET de mensagem.
GET /v1/instances/{id}/message/{messageId} continua disponível para uma
consulta pontual (abrir uma mensagem que um atendente clicou, conferir um caso
de suporte). Ele não substitui os eventos.
Limite de requisições (429)#
O limite é por empresa, somando todas as chaves e integrações (padrão
60 requisições por minuto; veja Rate Limiting). Ao receber
429, espere os segundos de Retry-After antes de tentar de novo — não
retente na hora nem em paralelo. Uma integração que faz polling consome a cota
das outras integrações da mesma empresa.
Envios: Idempotency-Key#
Todo envio assíncrono exige Idempotency-Key. Gere um valor por mensagem
lógica (ex.: o id do pedido + o passo do fluxo) e reutilize o mesmo valor se
precisar reenviar depois de um erro de rede ou timeout: a API devolve o mesmo
message_id em vez de mandar duas vezes. Uma chave nova a cada tentativa
transforma retentativa em mensagem duplicada no celular do cliente. O 202
significa "na fila", não "entregue": a prova de entrega é o evento.
Teste antes de usar a conta real#
Crie um webhook com simulator: true (veja Simulador de webhooks)
ou use o simulador no Console: ele recebe entregas reais, com assinatura, e
mostra cada evento. Antes de ligar a integração numa conta de verdade, confira
que o seu código: valida a assinatura, ignora um event_id repetido, trata uma
mensagem que fica em delivered sem read e se recupera por events/history
depois de ficar fora do ar.
Nunca faça#
- Polling de
GET /v1/instances/{id}/message/{messageId}para acompanhar status. - Polling de
GET /v1/instances/{id}para saber se a instância está conectada. - Consultar o histórico de entregas de webhook em loop para "ver se chegou".
- Esperar
readpara dar uma mensagem por concluída. - Gerar
Idempotency-Keynova ao retentar o mesmo envio. - Retentar um
429antes doRetry-After. - Processar o evento inteiro antes de responder o webhook.
- Enviar a chave
ctc_comoAuthorization: Bearer(useX-API-Key).