> ## Documentation Index
> Fetch the complete documentation index at: https://developer.wabox.me/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Wabox é uma API não-oficial de WhatsApp (aparelho vinculado). Tudo é snake_case; a base é https://api.wabox.me/instances/{instance_id}/token/{token}.
> Envios respondem { id, message_id, wabox_id, status: "queued" } na hora; o resultado real chega no webhook delivery. Envios não são idempotentes: confira GET /queue antes de repetir.
> Sempre verifique X-Wabox-Signature (HMAC-SHA256 de "<t>.<corpo cru>") nos webhooks e deduplique por event_id.
> Botões, listas, carrossel e catálogo são best effort e não renderizam no WhatsApp Web/Desktop. Não existem: chamadas, listas de transmissão, histórico de mensagens, instância mobile.
> Não invente endpoints ou campos: use o OpenAPI em https://api.wabox.me/openapi.json.

# Identificadores: phone, LID, grupos e canais

> Como o WhatsApp identifica chats e por que você deve guardar o LID junto com o número.

## O campo `phone`

Em toda a API, `phone` identifica **o chat**, não necessariamente um telefone:

| Formato                        | Chat                                 | Exemplo                         |
| ------------------------------ | ------------------------------------ | ------------------------------- |
| DDI + DDD + número, só dígitos | Conversa individual                  | `5511988887777`                 |
| `<id>-group`                   | Grupo                                | `120363012345678901-group`      |
| `<id>@g.us`                    | Grupo (JID cru; aceito como entrada) | `120363012345678901@g.us`       |
| `<id>@newsletter`              | Canal                                | `120363012345678901@newsletter` |
| `<id>@lid`                     | Contato por LID                      | `98765432109876@lid`            |
| `status@broadcast`             | Seu status                           | —                               |

Regras para números: sem `+`, espaços, parênteses ou traços; DDI obrigatório (`55` para o Brasil). O nono dígito do celular brasileiro é aceito com e sem, mas o WhatsApp pode registrar o contato de um jeito só — se `phone_not_on_whatsapp` aparecer, confira com `GET /phone-exists/{phone}`, que devolve o `canonical_phone`.

## LID

O WhatsApp está migrando de identificadores baseados no telefone para **LIDs** (*linked identifiers*): um número opaco por conta (`98765432109876@lid`) que não revela o telefone. Hoje os dois convivem; o WhatsApp entrega alguns eventos identificados por LID, principalmente em grupos e para contatos que ativaram a proteção do número.

O que isso significa para você:

* O webhook `received` pode trazer `chat_lid`, `sender_lid` e `participant_lid` além de `phone`/`participant_phone`. **Guarde os dois.**
* Em raros casos, `phone` (ou `participant_phone`) chega **só no formato LID**, porque o WhatsApp não informou o número. Nesses casos, use o LID como destino: todos os endpoints aceitam `xxx@lid` em `phone`.
* `GET /contacts/{phone}` e `GET /phone-exists/{phone}` devolvem `lid` quando conhecido, e aceitam LID como entrada — use para resolver de um lado para o outro.
* Não trate o LID como chave permanente absoluta: o WhatsApp pode reatribuir em situações como troca de número. Trate `phone` como a chave de negócio e o LID como identificador auxiliar.

## Grupos

Ids de grupo aparecem como `<id>-group` em toda a API e nos webhooks. O `<id>` costuma ser um timestamp de criação com dígitos extras (`120363012345678901`); grupos antigos podem ter o formato `<criador>-<timestamp>-group`. Use exatamente o que a API devolveu.

* Criar: `POST /groups` devolve o `id`.
* Descobrir por link de convite: `GET /groups/invite-info?invite=https://chat.whatsapp.com/...`.
* Dentro do grupo, quem enviou está em `participant_phone` / `participant_lid`.

## Canais

`<id>@newsletter`. Para publicar, use qualquer `send-*` com esse id em `phone` (você precisa ser admin do canal). Reações e leitura têm endpoints próprios em **Canais**.

## Mensagens

`message_id` é uma string opaca escolhida pelo remetente. Para mensagens enviadas pela API, o Wabox gera um id no formato do WhatsApp Web (`3EB0` + 18 hex) e o devolve na resposta antes de enviar — é o mesmo id em `delivery`, `message_status` e `reference_message_id`. Ids de mensagens recebidas vêm no formato do aparelho de quem enviou e podem ter outro tamanho.

## `id`, `message_id`, `wabox_id`, `event_id`

| Campo         | O que é                                    | Onde aparece                                                         |
| ------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| `message_id`  | Id da mensagem no WhatsApp                 | Resposta de envio, webhooks, referência para responder/reagir/apagar |
| `id`          | Alias de `message_id`                      | Resposta de envio (compatibilidade com ferramentas no-code)          |
| `wabox_id`    | Id do envio na fila do Wabox (`wbx_…`)     | Resposta de envio, `delivery`, `GET/DELETE /queue`                   |
| `event_id`    | Id único de cada entrega de webhook (ULID) | Todos os webhooks; use para deduplicar                               |
| `instance_id` | Id da instância (UUID)                     | URL da API, todos os webhooks                                        |