Guia Rápido - Fluxo Completo#
1. Registrar empresa e obter token#
bash
# Registrar
curl -X POST https://api.catcher.one/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"company_name": "Minha Empresa",
"owner_email": "eu@empresa.com",
"owner_name": "Joao",
"password": "MinhaSenh@123"
}'
# Salve o token retornado (ctc_xxxx...)
2. Criar e conectar instância#
bash
TOKEN="ctc_xxxx..."
# Criar instancia
curl -X POST https://api.catcher.one/v1/instances \
-H "X-API-Key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Principal"}'
# Salve o ID retornado
INSTANCE="84c2e480-..."
# Conectar (gera QR code)
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/connect \
-H "X-API-Key: $TOKEN"
# Escaneie o QR code no WhatsApp
# Ou use pairing code
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/pairing-code \
-H "X-API-Key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"phone": "554137984905"}'
3. Enviar mensagem#
bash
# Todo envio assíncrono exige Idempotency-Key (sem ele: 400 IDEMPOTENCY_KEY_REQUIRED).
# Use um valor único por mensagem lógica; reenviar a MESMA chave devolve o mesmo
# message_id em vez de duplicar o envio.
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/messages/text \
-H "X-API-Key: $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": "554137984905",
"text": "Ola! Teste do Catcher"
}'
# 202 { "status": "queued", "message_id": "<uuid>", "task_id": "...", "idempotency_key": "..." }
4. Configurar webhook para receber eventos#
bash
curl -X POST https://api.catcher.one/v1/webhooks \
-H "X-API-Key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://meuservidor.com/webhook",
"events": "message.received,message.sent,message.delivered,message.read,message.played,message.delivery_failed,connection.update"
}'
# Guarde o "secret" da resposta (só aparece aqui) para validar X-Catcher-Signature.
# O status de cada envio chega por estes eventos: não consulte a mensagem em loop.
# Veja "Boas Práticas de Integração" (assinatura, dedupe por event_id, estados finais).
5. Ouvir eventos em tempo real#
bash
# SSE
curl -N \
-H "X-API-Key: $TOKEN" \
"https://api.catcher.one/v1/instances/$INSTANCE/events"
# Ou via WebSocket com wscat
wscat -H "X-API-Key: $TOKEN" -c "wss://api.catcher.one/v1/instances/$INSTANCE/ws"
6. Buscar mensagem e baixar mídia recebida#
bash
# Consulta pontual (ex.: abrir uma mensagem). Para acompanhar status, use os eventos;
# para reconciliar depois de uma queda, use /events/history?after=<event_id>.
# Buscar mensagem pelo UUID do Catcher (elemento de message_ids do evento) ou pelo ID do WhatsApp (hex)
curl -H "X-API-Key: $TOKEN" \
"https://api.catcher.one/v1/instances/$INSTANCE/message/3EB0ABC123DEF456"
# Resposta inclui media_id se a mensagem tiver midia
# Baixar midia (imagem, audio, video, documento, sticker)
MEDIA_ID="b2c3d4e5-f6a7-8901-bcde-f12345678901"
curl -o arquivo_recebido.ogg \
-H "X-API-Key: $TOKEN" \
"https://api.catcher.one/v1/instances/$INSTANCE/media/$MEDIA_ID"