Primeiros passos

Em dez minutos: uma chave, uma instância conectada e a primeira mensagem saindo.

1. Crie uma chave de API

No painel, vá em Chaves de API → Nova chave. A chave (gwk_live_...) aparece uma vez só: guarde num cofre ou numa variável de ambiente.

export GW_API_KEY=gwk_live_...

Cada chave tem escopos. Dê a cada sistema só o que ele usa:

Uma chave também pode ser restrita a algumas instâncias (por exemplo, uma chave por loja).

2. Crie e conecte uma instância

Uma instância é um número de WhatsApp conectado ao Recadu. O jeito mais simples de conectar é pelo painel: Instâncias → Nova instância, depois leia o QR com o celular em WhatsApp → Aparelhos conectados → Conectar um aparelho.

Pela API:

curl -X POST https://api.recadu.com.br/v1/instances \
  -H "Authorization: Bearer $GW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "loja-centro"}'
# {"id": "ins_0192...", "state": "pending_pair", ...}

O pareamento pela API está em Instâncias e pareamento.

Ainda sem um número para testar? Crie uma instância com "kind": "sandbox": ela conecta sozinha, sem celular, e simula envios e respostas. Veja Sandbox.

3. Envie uma mensagem

curl -X POST https://api.recadu.com.br/v1/messages \
  -H "Authorization: Bearer $GW_API_KEY" \
  -H "Idempotency-Key: pedido-4821-saiu" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "ins_0192...",
    "to": "5537999990000",
    "type": "text",
    "text": {"body": "Seu pedido saiu para entrega."}
  }'

{
  "id": "msg_0192...",
  "instance_id": "ins_0192...",
  "direction": "outbound",
  "to": "5537999990000",
  "type": "text",
  "status": "queued",
  "created_at": "2026-10-13T14:02:11.204Z"
}

O telefone vai com DDI e DDD, só dígitos. A resposta 202 significa que a mensagem foi aceita; ela sai em seguida, na ordem da conversa. Acompanhe por GET /v1/messages/{id} ou, melhor, por webhook.

4. Receba as respostas

Cadastre a URL do seu sistema em Webhooks no painel (ou POST /v1/webhook-endpoints) e trate pelo menos:

• message.received: o contato escreveu;
• message.interactive_reply: o contato clicou num botão, escolheu na lista, votou na enquete ou respondeu com o número da opção;
• message.status_updated: entregue, lida.

Detalhes e exemplos de verificação da assinatura em Webhooks e eventos.

Convenções

Idempotência. Mande Idempotency-Key em todo POST que cria algo. Repetir o mesmo pedido com a mesma chave em até 24 h devolve a mesma resposta (com Idempotent-Replayed: true) e não envia de novo. Use algo que identifique o envio no seu sistema, como pedido-4821-saiu. A mesma chave com outro corpo dá 422 idempotency-key-reused.

Paginação. Listas aceitam ?limit= e ?cursor=. A resposta traz data e next_cursor; null no fim.

{"data": [ ... ], "next_cursor": "eyJ..."}

Concorrência. GET /v1/instances/{id} e GET /v1/messages/{id} devolvem ETag. Mande If-Match no PATCH da instância para não sobrescrever a mudança de outra pessoa; se ela mudou, a resposta é 412 precondition-failed.

Limites. Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Acima do limite, 429 rate-limited com Retry-After em segundos.

Erros. Sempre em application/problem+json:

{
  "type": "https://docs.recadu.com.br/problems/policy-new-contacts-limit",
  "title": "Muitas requisições",
  "status": 429,
  "detail": "Limite de 300 contatos novos em 24 h atingido para esta instância.",
  "instance": "/v1/messages",
  "request_id": "5f0c9a1e2b7d4c8e9a6b3d2f1e0c4b7a"
}

Trate pelo type (estável), mostre o detail (em português) e guarde o request_id para falar com o suporte. Se você mandar X-Request-ID no pedido, ele é usado no lugar do gerado. Lista completa em Erros.

IDs. Todo ID tem prefixo: ins_ (instância), msg_ (mensagem), med_ (mídia), evt_ (evento), whe_ (destino de webhook), whd_ (entrega).