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

# Migrando do z-api

> Troque o host, converta para snake_case e o resto continua igual. O que muda, o que não muda e como migrar sem parar.

O Wabox foi desenhado para que quem vem da z-api mude o mínimo possível: o mesmo formato de rota, os mesmos conceitos (instância, token, `Client-Token`, webhooks por tipo, fila) e os mesmos nomes de endpoint na maioria dos casos. A diferença principal é a convenção de nomes: **`snake_case`** em tudo.

## O que não muda

* **Rota**: `/instances/{instance_id}/token/{token}/<endpoint>` — só o host passa a ser `api.wabox.me`.
* **Header `Client-Token`**, com o mesmo papel.
* **Webhooks por tipo** (`received`, `delivery`, `message_status`, `connected`, `disconnected`, `chat_presence`) com o campo `momment` mantido de propósito.
* **Envio assíncrono**: resposta imediata com id, resultado no `delivery`.
* Os nomes da maioria dos endpoints: `send-text`, `send-image`, `send-button-list`, `send-option-list`, `send-carousel`, `qr-code`, `status`, `phone-exists`, `queue`…
* Vários endpoints da z-api continuam funcionando como **alias** (`/create-group`, `/profile-picture`, `/modify-chat`, `/tags`, `/send-button-actions`…). Veja a coluna "Alias aceito" na [tabela de rotas](/migration/route-mapping).

## O que muda

<Tabs>
  <Tab title="Nomes de campos">
    camelCase → snake\_case. Os mais usados:

    | z-api                              | Wabox                             |
    | ---------------------------------- | --------------------------------- |
    | `messageId` (ao responder)         | `reply_to_message_id`             |
    | `messageId` (na resposta do envio) | `message_id` (e `id` como alias)  |
    | `zaapId`                           | `wabox_id`                        |
    | `delayMessage`, `delayTyping`      | `delay_message`, `delay_typing`   |
    | `editMessageId`                    | `edit_message_id`                 |
    | `mentionAll`                       | `mention_all`                     |
    | `isGroup`, `fromMe`, `fromApi`     | `is_group`, `from_me`, `from_api` |
    | `senderName`, `chatName`           | `sender_name`, `chat_name`        |
    | `referenceMessageId`               | `reference_message_id`            |
    | `image.imageUrl`                   | `image.url`                       |
    | `notifySentByMe`                   | `notify_sent_by_me`               |

    A lista completa está na [tabela de rotas](/migration/route-mapping#campos-renomeados).
  </Tab>

  <Tab title="Mídia">
    O campo de mídia tem o nome do tipo (`image`, `audio`, `document`…) e aceita URL, `data:` URL ou base64 puro. `send-document/{extension}` funciona, mas `extension` também pode ir no body.
  </Tab>

  <Tab title="Webhooks">
    * Configuração num objeto só: `PUT /webhooks` com todas as URLs e filtros (em vez de um endpoint por URL). `PUT /webhooks/{type}` com `{ "value": "..." }` também existe.
    * Assinatura HMAC em `X-Wabox-Signature` — verifique, é de graça. Veja [Assinatura dos webhooks](/security/webhook-signature).
    * `event_id` único por entrega para deduplicar.
    * Conteúdo de mídia recebida em `image.url` (assinada, 24 h) em vez de `imageUrl`.
  </Tab>

  <Tab title="Erros">
    Sempre `{ "error": { "code", "message" } }`, com `code` estável. Veja [Erros](/api-reference/errors).
  </Tab>

  <Tab title="O que não existe">
    Chamadas (`send-call`), instâncias mobile, listas de transmissão, Meta AI, `order-payment-update`, `reply-button`/`reply-template-button` (no Wabox as respostas chegam pelo webhook, não são endpoints) e a API Partner. Detalhes e motivos em [Limitações conhecidas](/resources/limitations).
  </Tab>
</Tabs>

## Migrando sem parar

<Steps>
  <Step title="Crie a instância no Wabox e conecte o número">
    Um número só pode estar vinculado a uma sessão web por provedor, mas pode ter **vários aparelhos vinculados**. Você pode conectar o mesmo número no Wabox enquanto a z-api ainda está ativa e comparar os webhooks lado a lado.
  </Step>

  <Step title="Aponte os webhooks para um endpoint novo">
    Faça o seu handler aceitar os dois formatos (ou converta o payload do Wabox para o formato antigo com um adaptador de 20 linhas). Compare por alguns dias.
  </Step>

  <Step title="Troque os envios">
    Mude o host e os nomes de campos. Se você usa alguma biblioteca ou nó no-code apontando para a z-api, o [HTTP genérico](/integrations/http) resolve.
  </Step>

  <Step title="Desligue a instância antiga">
    Remova o aparelho da z-api em **Aparelhos conectados** no celular. Duas sessões ativas no mesmo número dividem os eventos recebidos entre si sem problema, mas não faz sentido pagar duas.
  </Step>
</Steps>

## Adaptador de payload (exemplo)

Se você quer trocar o host hoje e mexer no código depois:

```javascript theme={"system"}
// Converte um webhook `received` do Wabox para o formato camelCase antigo (subconjunto)
export function toLegacy(event) {
  return {
    type: "ReceivedCallback",
    instanceId: event.instance_id,
    messageId: event.message_id,
    phone: event.phone,
    fromMe: event.from_me,
    fromApi: event.from_api,
    isGroup: event.is_group,
    chatName: event.chat_name,
    senderName: event.sender_name,
    momment: event.momment,
    referenceMessageId: event.reference_message_id,
    text: event.text ? { message: event.text.message } : undefined,
    image: event.image ? { imageUrl: event.image.url, caption: event.image.caption, mimeType: event.image.mime_type } : undefined,
    // ...outros tipos conforme o seu uso
  };
}
```

Trate isso como ponte temporária: o formato do Wabox é o que evolui e ganha campos novos.