--- name: catcher description: Integra um sistema com a Catcher, API de WhatsApp (WhatsApp Web por QR Code) com envio por REST e eventos por webhook assinado. Use ao escrever ou revisar uma integração com a Catcher — criar conta e API key ctc_, conectar instância, configurar webhook, enviar mensagens, acompanhar status sem polling e recuperar eventos perdidos. --- # Catcher — super skill API de WhatsApp para desenvolvedores e agentes de IA. Você conecta números pelo WhatsApp Web (QR Code no Console ou pela API), envia e recebe mensagens por REST e recebe cada acontecimento por webhook assinado, SSE ou WebSocket. Base da API: https://api.catcher.one/v1 — autenticação pelo header X-API-Key (chave ctc_...). Teste grátis de 7 dias com 1 instância e 1 proxy; depois, R$ 50 por mês por instância e R$ 50 por proxy. ## Primeiros passos 1. **Crie a conta** no Console (https://app.catcher.one) ou por `POST https://api.catcher.one/v1/auth/register`. O registro devolve uma **API key** `ctc_...` (chaves antigas `bza_...` continuam valendo). Confirme o e-mail: criar webhook e escolher proxy exigem e-mail verificado. 2. **Autentique** toda requisição com `X-API-Key: ctc_...`. 3. **Crie uma instância** (`POST /v1/instances`) e **conecte** (`POST /v1/instances/{id}/connect`). A instância precisa de um proxy: escolha um em `GET /v1/proxies/offers` ou deixe o `connect` vincular um automaticamente. Leia o QR Code com o WhatsApp do celular (`GET /v1/instances/{id}/qr` ou `/qr/stream`). Uma instância pareada nunca troca de proxy. 4. **Crie o webhook** (`POST /v1/webhooks`) com os eventos que você usa e guarde o `secret` (só aparece na criação). Antes de usar a conta real, teste com um webhook `simulator: true`. 5. **Envie** (`POST /v1/instances/{id}/messages/text` com `Idempotency-Key`). O `202` traz o `message_id`; o resto da história da mensagem chega pelo webhook (`text.sent`, `text.delivered`, `text.read`…). ## Modelo de consumo (leia antes de escrever código) - **Webhook primeiro.** A Catcher avisa cada envio, entrega, leitura, mensagem recebida e queda de conexão. Não consulte a API em loop para descobrir o que mudou. - **Verifique a assinatura** (`X-Catcher-Signature` = HMAC-SHA256 de `X-Catcher-Timestamp + "." + corpo`, tolerância de 5 min), **responda 2xx em menos de 10 s** e processe depois. - **Deduplique por `event_id`**: a entrega é pelo menos uma vez. - **`delivered` pode ser o estado final.** Quem desliga a confirmação de leitura nunca gera `read`. - **Recupere perdas por cursor** com `GET /v1/instances/{id}/events/history?after=`, nunca com um `GET` por mensagem. - **`429`: espere o `Retry-After`.** O limite é por empresa (padrão 60 req/min). - **`Idempotency-Key`**: uma por mensagem lógica, a mesma ao retentar. ## Nunca faça - Polling de `GET /v1/instances/{id}/message/{messageId}` ou de `GET /v1/instances/{id}`. - Esperar `read` para dar a mensagem por concluída. - Chave nova de `Idempotency-Key` ao retentar o mesmo envio. - Enviar `ctc_...` em `Authorization: Bearer` (use `X-API-Key`). ## Boas práticas de integração (do manual) > **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=`). 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= enquanto has_more for true. ``` Sem um `event_id` de partida, use `since=`. 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`). ## Referências - Skill da API (auth + mapa da superfície): https://docs.catcher.one/skills/catcher-whatsapp-api/SKILL.md - Manual inteiro em um arquivo: https://docs.catcher.one/llms-full.txt - Índice para agentes: https://docs.catcher.one/llms.txt - Console: https://app.catcher.one