# Talaria: referência da API

Base: `https://talaria-api.rrlabs.io/v1`. JSON em snake_case; listas com `?limit=` e `?after=`; POSTs aceitam `Idempotency-Key`. Endpoints 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)
- `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)

### `GET /instances/{instance}`

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

### `PATCH /instances/{instance}`

Rename, metadata, webhook, sending pace
- `name` (string)
- `webhook_url` (string, null])
- `metadata` (object)
- `pace` (Pace)
- `reject_calls` (boolean)

### `DELETE /instances/{instance}`

Unlink and forget the instance

### `POST /instances/{instance}/connect`

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)

### `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/resync` (em breve)

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.

### `POST /instances/{instance}/messages`

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)

### `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
- `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.

### `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)
- `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.

### `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)
- `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.

### `GET /instances/{instance}/labels`

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

### `POST /instances/{instance}/labels` (em 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}/chats` (em breve)

Assign or unassign the label on many chats
- `add` (array)
- `remove` (array)

## 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}/groups` (em 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
- `subject` (string)
- `description` (string)
- `announcement` (boolean)
- `locked` (boolean)

### `GET /instances/{instance}/groups/{group}/participants` (em breve)

Participants with role, pn and lid (paginated)

### `POST /instances/{instance}/groups/{group}/participants` (em breve)

Add, remove, promote, demote (per-participant results)
- `action` (string): um de: add, remove, promote, demote
- `participants` (array)

### `GET /instances/{instance}/groups/{group}/invite` (em breve)

The invite link

### `DELETE /instances/{instance}/groups/{group}/invite` (em 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)
- `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)

### `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_only` (boolean)
- `after` (string): an event cursor
- `until` (string)
