List instances
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.
Instâncias
Cada instância é um número de WhatsApp conectado como aparelho: crie, conecte pelo QR ou por código de pareamento, acompanhe o estado real.
Create an instance (a WhatsApp number slot)
| name | string | shown in the panel |
| external_id | string | the clients own id (unique per account), e.g. TALARIA_RESGATAFACIL_12_34 |
| webhook_url | string | optional per-instance webhook (in addition to account webhooks) |
| metadata | object |
An instance, with its live state (cheap; answer in ~100 ms)
Rename, metadata, webhook, sending pace
| name | string | |
| webhook_url | string, null] | |
| metadata | object | |
| pace | Pace | |
| reject_calls | boolean |
Unlink and forget the instance
Start linking (idempotent; never invalidates a QR or code still valid)
| method | string | um de: qr, pairing_code |
| phone | string | digits; required for pairing_code (landlines included) |
The current QR (also pushed as session.qr events)
Unlink the device (the instance stays
'Disconnect but stay linked (suspend): no sends
'Connect again a stopped instance (no new QR); 409 not_linked if it was never linked or was logged out (use connect)'
Reconnect now
Who the linked number is
Sync status per collection (app-state versions, history progress, LID map coverage)
Ask the phone for fresh app-state snapshots (labels, contacts, archive …)
| collections | array | um de: critical_block, critical_unblock_low, regular_high, regular, regular_low |
Mensagens
Envie texto, mídia, localização, contato e reação; a resposta traz sempre o id da mensagem, que volta em message.status.
Send a message (always answers the message id)
Corpo: SendMessage
| to | string | |
| type | string | um de: text, image, video, audio, voice, document, sticker, location, contact, reaction, poll |
| text | string | text body; caption for media |
| link_preview | boolean | |
| media | MediaInput | |
| location | object | |
| contact | object | |
| reaction | object | empty removes |
| poll | object | |
| reply_to | string | a message id |
| mentions | array | |
| mention_all | boolean | groups; mentions every participant without listing them in the text |
| typing_ms | integer | shows typing (or recording, for voice) first |
| view_once | boolean | |
| queue | string | paced = the instances outbox (pace) |
| tag | string | paced sends; e.g. a campaign id, cancellable together |
| client_ref | string | echoed in events (e.g. campaign contact id) |
A message Talaria sent or received (kept as long as the event log), with its status
Send a read receipt
Download a received message's media (decrypted); 410 when WhatsApp no longer has it
Presence, global or in a chat
| chat | string | |
| state | string | um de: available, unavailable, typing, recording, paused |
Contatos
Cada contato vem com pn (telefone) e lid. Verifique números no WhatsApp e resolva LID ↔ telefone em lote.
Every known contact (address book, chats, groups), paginated export
One contact by pn or lid
Which phones are on WhatsApp, with their LID (batch, up to 1000; cached)
Resolve LIDs to phones and phones to LIDs (batch, up to 10000; answers from the map in < 2 s)
| lids | array | |
| pns | array | |
| query_unknown | boolean | also ask WhatsApp (usync) for pns not in the map; answers may come later as contact.pn_resolved / lid.mapping |
Conversas
As conversas da instância, da sincronização do histórico em diante.
Chats (from history sync and live traffic), newest first
One chat
Archive, pin, mute, mark read, labels add/remove (app-state writes)
| archived | boolean | |
| pinned | boolean | |
| muted_until | string, null] | |
| read | boolean | |
| labels_add | array | |
| labels_remove | array |
Etiquetas
As etiquetas do WhatsApp Business, lidas da sincronização do app, e as conversas de cada uma.
WhatsApp Business labels, from app-state (with chat counts and the sync version)
Create a label (answers its id)
Rename or recolour
Delete the label
Every chat with the label (current associations only; removals applied)
Assign or unassign the label on many chats
| add | array | |
| remove | array |
Grupos
Grupos e comunidades: metadados, tamanho, endereçamento (pn ou lid).
Groups the number is in (no participants; fast)
Create a group
Group metadata (fresh from WhatsApp, participants included)
Subject, description, settings
| subject | string | |
| description | string | |
| announcement | boolean | |
| locked | boolean |
Participants with role, pn and lid (paginated)
Add, remove, promote, demote (per-participant results)
| action | string | um de: add, remove, promote, demote |
| participants | array |
The invite link
Revoke the invite link (a new one is made)
Eventos
O registro de eventos de 7 dias, com cursor: o que os webhooks entregam, para ler quando quiser.
The event log (7 days), for catching up after downtime; same objects as webhooks
Webhooks
Endpoints assinados (Standard Webhooks ou X-Webhook-Hmac), novas tentativas por 24 h, entregas e reenvio.
Webhook endpoints, with delivery health
Add a webhook endpoint (answers its secret once)
| url | string | |
| types | array | event types, wildcards allowed; default all |
| instances | array | default all |
| signature | string | hmac_sha512 = X-Webhook-Hmac of the raw body (WAHA-compatible) |
| batch_receipts | boolean |
Change url
Remove
Delivery attempts (7 days)
Deliver events again (failed ones, or a range)
| failed_only | boolean | |
| after | string | an event cursor |
| until | string |
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.