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

# O que renderiza onde

> Botões, listas, carrossel, PIX, eventos e status: em quais aparelhos cada mensagem interativa aparece.

Mensagens interativas não fazem parte do que um usuário comum consegue enviar pelo WhatsApp: são formatos reservados a contas comerciais na API oficial. O Wabox as monta no mesmo formato que o WhatsApp usa internamente ("native flow"), e por isso elas **funcionam nos apps de celular** — mas o comportamento depende do cliente de quem recebe e pode mudar sem aviso. Tratamos tudo desta página como **best effort**.

## Tabela de compatibilidade

| Mensagem                           | Endpoint           | Android / iOS           | WhatsApp Web / Desktop | Resposta chega em                |
| ---------------------------------- | ------------------ | ----------------------- | ---------------------- | -------------------------------- |
| Botões (reply, URL, ligar, copiar) | `send-button-list` | ✓                       | ✗ placeholder          | `buttons_response`               |
| Botão "copiar código" (OTP)        | `send-button-otp`  | ✓                       | ✗ placeholder          | —                                |
| Botão PIX                          | `send-button-pix`  | ✓ (abre o app do banco) | ✗ placeholder          | —                                |
| Lista de opções                    | `send-option-list` | ✓                       | ✗ placeholder          | `list_response`                  |
| Carrossel                          | `send-carousel`    | ✓                       | ✗ placeholder          | `buttons_response`               |
| Evento de calendário               | `send-event`       | ✓                       | ✓                      | `event_response`                 |
| Status (stories)                   | `send-*-status`    | ✓                       | ✓                      | `received` (respostas ao status) |
| Enquete                            | `send-poll`        | ✓                       | ✓                      | `poll_vote`                      |
| Localização, contato, mídia, texto | `send-*`           | ✓                       | ✓                      | `received`                       |

**Placeholder** significa que o WhatsApp Web/Desktop mostra algo como "mensagem de visualização única" ou um aviso de que o conteúdo precisa ser visto no celular. Não é um bug do Wabox: o conteúdo é cifrado de forma idêntica para todos os aparelhos, e o cliente web simplesmente não implementa esses tipos para contas comuns. z-api, Evolution e similares têm exatamente o mesmo comportamento.

<Warning>
  Se o seu público atende pelo computador (equipes de suporte, empresas B2B), **não dependa de botões e listas**. Ofereça a alternativa em texto: "Responda 1 para confirmar, 2 para remarcar".
</Warning>

## Detalhes por tipo

<AccordionGroup>
  <Accordion title="Botões (send-button-list)">
    Até 3 botões renderizam bem; acima disso o app pode mostrar como lista. Tipos: `reply` (devolve `button_id`), `url` (abre o link), `call` (disca), `copy` (copia um texto). Pode levar `image` no topo. Apps muito antigos podem receber só o texto.
  </Accordion>

  <Accordion title="Lista (send-option-list)">
    Um botão (`button_label`) que abre um menu com `sections[].rows[]` (ou `options[]` simples). A escolha chega em `list_response.selected_row_id`.
  </Accordion>

  <Accordion title="Carrossel (send-carousel)">
    Cards com imagem, texto e botões, deslizáveis. Cada card tem seus próprios botões (`buttons_response` traz o `button_id` do card). Ainda em validação com número real — teste com o seu público antes de usar em produção.
  </Accordion>

  <Accordion title="PIX (send-button-pix)">
    Botão que abre o app de pagamento com a chave (`key`, `key_type`: CPF, CNPJ, telefone, e-mail ou aleatória) e o nome do recebedor. O Wabox não confirma pagamento — isso é entre o cliente e o banco.
  </Accordion>

  <Accordion title="Eventos (send-event, send-edit-event, send-event-response)">
    Renderizam em todos os clientes, com RSVP. Edição, cancelamento e RSVP dependem de um segredo da mensagem que o engine guarda em memória: só funcionam para eventos **criados pela API ou recebidos desde o último restart** do engine. Fora disso, `delivery` vem com `message_not_found`.
  </Accordion>

  <Accordion title="Status (send-text-status, send-image-status, send-video-status)">
    Publicam no seu status seguindo a **privacidade de status** configurada no celular (meus contatos, exceto, só compartilhar com). Não há como escolher a audiência pela API. Respostas ao status chegam como `received` normais.
  </Accordion>
</AccordionGroup>

## Como testar

A aba **Testes** da instância envia cada tipo interativo para um número seu e acompanha o `delivery`. Ela mostra se o WhatsApp **aceitou** o envio; para saber como renderizou, olhe o celular. Veja [Diagnóstico](/guides/diagnostics).

## Se algo parar de renderizar

O WhatsApp muda o formato interno desses tipos periodicamente. Quando isso acontece, o envio pode passar a chegar como texto ou nem aparecer. Avise pelo suporte com o `message_id` e a versão do app de quem recebeu; enquanto isso, use a alternativa em texto. O [changelog](/resources/changelog) registra ajustes nesses formatos.