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 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 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 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 "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.
# 402
{ "error": { "code": "plan_limit", "message": "Your plan (Pro) has 10 instance(s); delete one or upgrade.",
"details": { "plan": "pro", "instances": 10 } } }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.
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.
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.
5. Receber
Pelo registro de eventos (7 dias, com cursor) ou por webhooks. Cada pessoa vem com pn e lid.
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.
Webhooks
Cada endpoint recebe os eventos que escolher (types, com curingas como message.*) das instâncias que escolher.
Assinaturas
standard (Standard Webhooks): cabeçalhos webhook-id, webhook-timestamp e webhook-signature: v1,<base64>, o HMAC-SHA256 de id.timestamp.corpo com a chave whsec_… decodificada de base64. hmac_sha512: X-Webhook-Hmac, o HMAC-SHA512 hexadecimal do corpo cru, com o segredo hsec_… inteiro como chave. O webhook_url de uma instância é assinado dos dois jeitos, com o segredo da conta (em Chaves de API).
Novas tentativas e reenvio
Em 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h e 12 h, por 24 h; um 410 encerra. As tentativas ficam 7 dias em GET /v1/webhooks/{id}/deliveries e no painel, que reenvia com um clique (POST /v1/webhooks/{id}/replay).
Referência da API
Cada endpoint do contrato (docs/openapi.yaml). Base https://talaria-api.rrlabs.io/v1; JSON em snake_case; listas com ?limit= e ?after=; POSTs aceitam Idempotency-Key. Os marcados em breve estão no contrato e ainda não respondem.