Documentação

A API de WhatsApp do Talaria

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.

GET/instances

List instances

POST/instances

Create an instance (a WhatsApp number slot)

namestringshown in the panel
external_idstringthe clients own id (unique per account), e.g. TALARIA_RESGATAFACIL_12_34
webhook_urlstringoptional per-instance webhook (in addition to account webhooks)
metadataobject
GET/instances/{instance}

An instance, with its live state (cheap; answer in ~100 ms)

PATCH/instances/{instance}

Rename, metadata, webhook, sending pace

namestring
webhook_urlstring, null]
metadataobject
pacePace
reject_callsboolean
DELETE/instances/{instance}

Unlink and forget the instance

POST/instances/{instance}/connect

Start linking (idempotent; never invalidates a QR or code still valid)

methodstringum de: qr, pairing_code
phonestringdigits; required for pairing_code (landlines included)
GET/instances/{instance}/qr

The current QR (also pushed as session.qr events)

POST/instances/{instance}/logout

Unlink the device (the instance stays

POST/instances/{instance}/stop

'Disconnect but stay linked (suspend): no sends

POST/instances/{instance}/start

'Connect again a stopped instance (no new QR); 409 not_linked if it was never linked or was logged out (use connect)'

POST/instances/{instance}/restart

Reconnect now

GET/instances/{instance}/profile

Who the linked number is

GET/instances/{instance}/sync

Sync status per collection (app-state versions, history progress, LID map coverage)

POST/instances/{instance}/appstate/resyncem breve

Ask the phone for fresh app-state snapshots (labels, contacts, archive …)

collectionsarrayum 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.

POST/instances/{instance}/messages

Send a message (always answers the message id)

Corpo: SendMessage

tostring
typestringum de: text, image, video, audio, voice, document, sticker, location, contact, reaction, poll
textstringtext body; caption for media
link_previewboolean
mediaMediaInput
locationobject
contactobject
reactionobjectempty removes
pollobject
reply_tostringa message id
mentionsarray
mention_allbooleangroups; mentions every participant without listing them in the text
typing_msintegershows typing (or recording, for voice) first
view_onceboolean
queuestringpaced = the instances outbox (pace)
tagstringpaced sends; e.g. a campaign id, cancellable together
client_refstringechoed in events (e.g. campaign contact id)
GET/instances/{instance}/messages/{message}

A message Talaria sent or received (kept as long as the event log), with its status

POST/instances/{instance}/messages/{message}/read

Send a read receipt

GET/instances/{instance}/media/{message}em breve

Download a received message's media (decrypted); 410 when WhatsApp no longer has it

POST/instances/{instance}/presence

Presence, global or in a chat

chatstring
statestringum 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.

GET/instances/{instance}/contacts

Every known contact (address book, chats, groups), paginated export

GET/instances/{instance}/contacts/{contact}

One contact by pn or lid

POST/instances/{instance}/contacts/check

Which phones are on WhatsApp, with their LID (batch, up to 1000; cached)

POST/instances/{instance}/contacts/resolve

Resolve LIDs to phones and phones to LIDs (batch, up to 10000; answers from the map in < 2 s)

lidsarray
pnsarray
query_unknownbooleanalso 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.

GET/instances/{instance}/chats

Chats (from history sync and live traffic), newest first

GET/instances/{instance}/chats/{chat}

One chat

PATCH/instances/{instance}/chats/{chat}em breve

Archive, pin, mute, mark read, labels add/remove (app-state writes)

archivedboolean
pinnedboolean
muted_untilstring, null]
readboolean
labels_addarray
labels_removearray

Etiquetas

As etiquetas do WhatsApp Business, lidas da sincronização do app, e as conversas de cada uma.

GET/instances/{instance}/labels

WhatsApp Business labels, from app-state (with chat counts and the sync version)

POST/instances/{instance}/labelsem breve

Create a label (answers its id)

PATCH/instances/{instance}/labels/{label}em breve

Rename or recolour

DELETE/instances/{instance}/labels/{label}em breve

Delete the label

GET/instances/{instance}/labels/{label}/chats

Every chat with the label (current associations only; removals applied)

POST/instances/{instance}/labels/{label}/chatsem breve

Assign or unassign the label on many chats

addarray
removearray

Grupos

Grupos e comunidades: metadados, tamanho, endereçamento (pn ou lid).

GET/instances/{instance}/groups

Groups the number is in (no participants; fast)

POST/instances/{instance}/groupsem breve

Create a group

GET/instances/{instance}/groups/{group}

Group metadata (fresh from WhatsApp, participants included)

PATCH/instances/{instance}/groups/{group}em breve

Subject, description, settings

subjectstring
descriptionstring
announcementboolean
lockedboolean
GET/instances/{instance}/groups/{group}/participantsem breve

Participants with role, pn and lid (paginated)

POST/instances/{instance}/groups/{group}/participantsem breve

Add, remove, promote, demote (per-participant results)

actionstringum de: add, remove, promote, demote
participantsarray
GET/instances/{instance}/groups/{group}/inviteem breve

The invite link

DELETE/instances/{instance}/groups/{group}/inviteem breve

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.

GET/events

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.

GET/webhooks

Webhook endpoints, with delivery health

POST/webhooks

Add a webhook endpoint (answers its secret once)

urlstring
typesarrayevent types, wildcards allowed; default all
instancesarraydefault all
signaturestringhmac_sha512 = X-Webhook-Hmac of the raw body (WAHA-compatible)
batch_receiptsboolean
PATCH/webhooks/{webhook}

Change url

DELETE/webhooks/{webhook}

Remove

GET/webhooks/{webhook}/deliveries

Delivery attempts (7 days)

POST/webhooks/{webhook}/replay

Deliver events again (failed ones, or a range)

failed_onlyboolean
afterstringan event cursor
untilstring