Documentação

A API de WhatsApp do Talaria

Primeiros passos

O Talaria conecta um número como aparelho do WhatsApp Web e dá a você uma API REST, um registro de eventos e webhooks assinados. É uma API de WhatsApp não oficial, não afiliada à Meta.

1. A chave

Crie a conta e escolha um plano. A primeira chave aparece uma única vez no fim do cadastro; outras, em Painel → Chaves de API (guardamos só o hash). Toda chamada leva Authorization: Bearer tk_live_….

2. Uma instância

Cada instância é um número. O plano diz quantas você pode ter; além dele, a API responde 402 plan_limit.

curl
curl https://talaria-api.rrlabs.io/v1/instances \
  -H "Authorization: Bearer $TALARIA_KEY" \
  -d '{"name": "Atendimento", "external_id": "loja-1"}'

3. Conectar

Pelo QR ({"method": "qr"}: a resposta traz qr e qr_png) ou por código de pareamento, que serve também para fixos. Pedir de novo nunca invalida um QR ou código ainda válido.

curl
curl https://talaria-api.rrlabs.io/v1/instances/ins_.../connect \
  -H "Authorization: Bearer $TALARIA_KEY" \
  -d '{"method": "pairing_code", "phone": "5511912345678"}'

# 200
{ "state": "pairing", "pairing_code": "K7QM-2XPA", ... }

4. Enviar

A resposta é 202 com o id da mensagem, que volta em message.sent e message.status. Com Idempotency-Key, repetir a chamada não envia duas vezes.

curl
curl https://talaria-api.rrlabs.io/v1/instances/ins_.../messages \
  -H "Authorization: Bearer $TALARIA_KEY" \
  -H "Idempotency-Key: pedido-42" \
  -d '{"to": "5511987654321", "type": "text", "text": "Olá!"}'

# 202
{ "id": "3EB0...", "status": "sent", "to": { "pn": "5511987654321", "lid": "...@lid" } }

5. Receber

Pelo registro de eventos (7 dias, com cursor) ou por webhooks. Cada pessoa vem com pn e lid.

curl
curl "https://talaria-api.rrlabs.io/v1/events?after=evt_...&types=message.*" \
  -H "Authorization: Bearer $TALARIA_KEY"

# 200
{ "data": [ { "id": "evt_...", "type": "message.received", "instance": "ins_...", "data": { ... } } ], "next": "evt_..." }

Erros

Um status HTTP e {"error": {"code", "message", "details"}}. Os códigos são estáveis: unauthorized, forbidden, not_found, invalid_request, conflict, plan_limit, rate_limited, not_connected, not_on_whatsapp, lid_unresolved, media_unavailable, whatsapp_error, internal.

json
# 402
{ "error": { "code": "plan_limit", "message": "Your plan (Pro) has 10 instance(s); delete one or upgrade.",
             "details": { "plan": "pro", "instances": 10 } } }