Boas Práticas de Integração

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 429 e 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
  1. Crie um webhook (POST /v1/webhooks) assinando os eventos de que você precisa. Um nome genérico cobre os específicos: message.sent assina text.sent, image.sent, audio.sent… (os eventos chegam com o tipo de conteúdo no nome, ex.: text.delivered; o tipo também vem em data.message_type).
  2. Verifique a assinatura de cada entrega: HMAC-SHA256 de X-Catcher-Timestamp + "." + corpo_cru com o secret do webhook, comparado em tempo constante com X-Catcher-Signature (sha256=<hex>). Recuse timestamps com mais de 5 minutos de diferença. Exemplos em Verificação de assinatura HMAC.
  3. 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.
  4. Deduplique por event_id. A entrega é pelo menos uma vez: o mesmo event_id pode chegar de novo depois de uma retentativa. Guarde os event_id processados e ignore repetidos.
  5. 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: se read já foi gravado, um delivered atrasado não muda nada.
  6. Correlacione pelo message_id (UUID da Catcher) devolvido no 202 do envio — é o mesmo valor em data.message_ids de todos os eventos daquela mensagem. Veja §22.

Envelope de todo evento (webhook, SSE e WebSocket):

json
{
  "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:

bash
# 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 read para dar uma mensagem por concluída.
  • Gerar Idempotency-Key nova ao retentar o mesmo envio.
  • Retentar um 429 antes do Retry-After.
  • Processar o evento inteiro antes de responder o webhook.
  • Enviar a chave ctc_ como Authorization: Bearer (use X-API-Key).