---
name: catcher
description: Use a Catcher (API brasileira de WhatsApp, não-oficial) para enviar e receber mensagens de WhatsApp via REST + webhooks. Esta skill mostra como obter credenciais e dar os primeiros passos (registrar, criar instância, parear QR, enviar mensagem).
---

# Catcher — super skill

Base da API: `https://api.catcher.one/v1`. Autenticação: header `X-API-Key: bza_...`
(o token retornado no registro é uma API key, NÃO um JWT — nunca envie
`Authorization: Bearer bza_...`).

## Primeiros passos (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 (bza_xxxx...)
```

### 2. Criar e conectar instância
```bash
TOKEN="bza_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
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/messages/text \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "554137984905",
    "text": "Ola! Teste do BiaZap"
  }'
```

### 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"
  }'
```

### 5. Ouvir eventos em tempo real
```bash
# SSE
curl -N \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.catcher.one/v1/instances/$INSTANCE/events"

# Ou via WebSocket com wscat
wscat -H "Authorization: Bearer $TOKEN" -c "wss://api.catcher.one/v1/instances/$INSTANCE/ws"
```

### 6. Buscar mensagem e baixar mídia recebida
```bash
# Buscar mensagem pelo UUID do BiaZap (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"
```

## Referências

- Mapa completo da API: https://catcher.one/skills/catcher-whatsapp-api/SKILL.md
- Manual inteiro em um arquivo: https://catcher.one/llms-full.txt
- Índice para agentes: https://catcher.one/llms.txt
- Console humano: https://app.catcher.one