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

# Visão geral dos webhooks

> Como o Wabox entrega eventos, o que vem em cada requisição e as garantias de entrega.

Webhooks são a única forma de **receber** alguma coisa do WhatsApp: mensagens, recibos, mudanças de conexão. O Wabox faz um `POST` HTTPS com JSON para a URL que você configurar, uma URL por tipo de evento.

| Tipo                         | O que avisa                                                  | Página                                      |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| `received`                   | Chegou uma mensagem (qualquer tipo) ou um evento de chat     | [received](/webhooks/received)              |
| `delivery`                   | Resultado de um envio feito pela API                         | [delivery](/webhooks/delivery)              |
| `message_status`             | Recibo de mensagem sua: enviada, entregue, lida, reproduzida | [message\_status](/webhooks/message-status) |
| `connected` / `disconnected` | Estado da conexão mudou                                      | [conexão](/webhooks/connection)             |
| `chat_presence`              | Contato digitando, gravando, online                          | [chat\_presence](/webhooks/chat-presence)   |

## Configuração

No painel, em **Webhooks e configurações gerais**, ou pela API:

```bash theme={"system"}
curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "received_url": "https://seu-servidor.com/wabox",
    "delivery_url": "https://seu-servidor.com/wabox",
    "message_status_url": "https://seu-servidor.com/wabox",
    "connected_url": "https://seu-servidor.com/wabox",
    "disconnected_url": "https://seu-servidor.com/wabox",
    "chat_presence_url": null
  }'
```

Pode ser a mesma URL para tudo (use `type` no corpo ou o header `X-Wabox-Event` para rotear) ou uma por tipo. `null` desliga o tipo. `PUT /webhooks/{type}` com `{ "value": "https://..." }` altera um só. Os [filtros](/webhooks/filters) decidem quais mensagens chegam.

## Anatomia de uma entrega

```http theme={"system"}
POST /wabox HTTP/1.1
Host: seu-servidor.com
Content-Type: application/json
User-Agent: Wabox-Webhook/1.0
X-Wabox-Event: received
X-Wabox-Event-Id: 01J5Q8ZK3M4N5P6Q7R8S9T0V1X
X-Wabox-Instance-Id: 8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b
X-Wabox-Signature: t=1786968300,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{ "type": "received", "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X", "instance_id": "8f2a3c1e-...", "momment": 1786968300000, ... }
```

Todo payload tem quatro campos em comum:

| Campo         | Tipo   | Descrição                                                                                    |
| ------------- | ------ | -------------------------------------------------------------------------------------------- |
| `type`        | string | Tipo do evento (o mesmo do header `X-Wabox-Event`)                                           |
| `event_id`    | string | ULID único do evento. Chave de idempotência                                                  |
| `instance_id` | string | Instância que gerou o evento                                                                 |
| `momment`     | number | Epoch em **milissegundos**. O nome (com dois "m") é herdado da z-api para facilitar migração |

## Garantias de entrega

* **Ordem**: entregas de uma mesma instância saem uma de cada vez, na ordem em que os eventos aconteceram. Instâncias diferentes são paralelas.
* **Tentativas**: você tem 10 s para responder 2xx. Caso contrário o Wabox tenta de novo após 10 s, 1 min, 10 min, 1 h e 6 h. Depois disso o evento é descartado e fica registrado como falha nos **Logs de webhook** do painel.
* **Pelo menos uma vez**: uma entrega pode repetir (por exemplo, você respondeu 200 mas a conexão caiu antes de o Wabox ler). Guarde `event_id` e ignore repetidos.
* **Sem conteúdo em repouso**: o Wabox não guarda o conteúdo das mensagens; se todas as tentativas falharem, a mensagem não é recuperável pela API. Mantenha o endpoint disponível.

<Warning>
  Responda **antes** de processar. Se o seu handler demora (chama outra API, grava em banco lento), coloque o evento em uma fila interna e devolva 200 na hora. Um endpoint lento vira reenvios, que viram duplicidade.
</Warning>

## Segurança

Verifique `X-Wabox-Signature` em toda entrega — é o que garante que veio do Wabox e não de alguém que descobriu a sua URL. Passo a passo com código em [Assinatura dos webhooks](/security/webhook-signature).

## Testando

* Sem servidor público: use um túnel (ngrok, Cloudflare Tunnel) apontando para a sua máquina.
* Para ver o payload cru: qualquer serviço de "request bin".
* No painel, **Logs de webhook** mostra cada tentativa com status HTTP, tempo de resposta e o corpo enviado, e permite **reenviar** manualmente.
* A aba **Testes** da instância dispara mensagens reais para um número seu e acompanha `delivery` e `message_status` — veja [Diagnóstico](/guides/diagnostics).