> ## 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 ".") 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. # Webhook received > Toda mensagem que chega ao número, com o conteúdo em um bloco por tipo. `received` dispara para cada mensagem recebida pelo número conectado — texto, mídia, reação, voto, resposta de botão — e também para **eventos de chat** (alguém entrou no grupo, mensagem apagada, chamada perdida), que chegam com `notification` em vez de conteúdo. O schema completo com todos os campos está na [referência](/api-reference/webhooks/received). Esta página explica como ler o payload. ## Envelope ```json theme={"system"} { "type": "received", "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X", "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b", "momment": 1786968300000, "message_id": "3EB0A9C6D2F1E4B5A7C8", "phone": "5511988887777", "chat_lid": "98765432109876@lid", "sender_lid": "98765432109876@lid", "from_me": false, "from_api": false, "is_group": false, "is_newsletter": false, "is_edit": false, "forwarded": false, "broadcast": false, "waiting_message": false, "status": "RECEIVED", "chat_name": "Maria", "sender_name": "Maria", "text": { "message": "Olá! Tudo bem?" } } ``` | Campo | Descrição | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `message_id` | Id da mensagem no WhatsApp. Use em `reply_to_message_id`, `read-message`, `send-reaction`, `forward-message` | | `phone` | **O chat**: número do contato, `...-group` em grupos, `...@newsletter` em canais | | `chat_lid`, `sender_lid` | LIDs quando conhecidos — guarde junto com o número ([Identificadores](/guides/identifiers)) | | `from_me` | `true` para mensagens enviadas pelo número (só chegam com `notify_sent_by_me` ligado) | | `from_api` | Entre as `from_me`, distingue as enviadas pela API das digitadas no celular | | `is_group`, `participant_phone`, `participant_lid` | Em grupos, quem enviou | | `reference_message_id` | Mensagem que está sendo respondida | | `is_edit` | A mensagem é a edição de uma anterior (mesmo `message_id`) | | `forwarded`, `broadcast` | Encaminhada / veio de lista de transmissão | | `waiting_message` | Placeholder: o conteúdo real ainda está sendo decifrado; um segundo evento chega com o conteúdo | | `message_expiration_seconds`, `expires_at` | Mensagem temporária | | `status` | `RECEIVED` para mensagens dos outros; para as suas, o último recibo conhecido | ## Conteúdo por tipo Exatamente **um** dos blocos abaixo vem preenchido. Teste a presença do campo (`if (event.image) …`) em vez de olhar um campo "tipo". ```json theme={"system"} "text": { "message": "Olá! Tudo bem?" } ``` Quando o texto traz link com prévia, vêm também `title`, `description`, `url` e `thumbnail_url`. ```json theme={"system"} "image": { "mime_type": "image/jpeg", "url": "https://media.wabox.me/8f2a3c1e/2026/09/03/3EB0A9C6D2F1E4B5A7C9.jpg?X-Amz-Signature=...", "thumbnail_url": "https://media.wabox.me/.../3EB0A9C6D2F1E4B5A7C9.thumb.jpg?X-Amz-Signature=...", "caption": "olha isso", "width": 1080, "height": 1920, "view_once": false, "file_size": 245678, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } ``` * `url` é assinada e **expira em 24 h**. Copie o arquivo para o seu storage se precisar dele depois. * Se o download/decifração falhar, `url` vem ausente e `download_error` explica o motivo. * `video`: `seconds`, `is_gif`. `audio`: `ptt` (voice note) e `seconds`. `document`: `file_name`, `title`, `page_count`. `sticker`: `animated`. * `view_once: true` em mídia de visualização única — o WhatsApp não permite reencaminhar; trate como sensível. ```json theme={"system"} "location": { "latitude": -23.5505, "longitude": -46.6333, "name": "Praça da Sé", "address": "Sé, São Paulo - SP", "url": "" } ``` ```json theme={"system"} "contact": { "display_name": "João Silva", "vcard": "BEGIN:VCARD...END:VCARD", "phones": ["5511977776666"] } ``` Vários cartões numa mensagem chegam em `contacts` (array com o mesmo formato). ```json theme={"system"} "reaction": { "value": "👍", "time": 1786968400000, "reaction_by": "5511988887777", "referenced_message": { "message_id": "3EB0A9C6D2F1E4B5A7C8", "from_me": true, "phone": "5511988887777" } } ``` `value` vazio significa que a reação foi removida. ```json theme={"system"} "poll": { "question": "Qual horário?", "poll_max_options": 1, "options": [{ "name": "9h" }, { "name": "14h" }] } ``` ```json theme={"system"} "poll_vote": { "poll_message_id": "3EB0A9C6D2F1E4B5A7C8", "options": [{ "name": "14h" }] } ``` Votos só são decifrados para enquetes que o engine viu (enviadas pela API ou recebidas desde o último restart). Resposta do contato a botões ou lista que você enviou: ```json theme={"system"} "buttons_response": { "button_id": "yes", "message": "Sim" } ``` ```json theme={"system"} "list_response": { "selected_row_id": "plano_pro", "title": "Plano Pro", "message": "Plano Pro" } ``` `reference_message_id` aponta para a mensagem interativa original. Mensagens interativas **enviadas por outras contas** (um negócio, por exemplo) chegam em `buttons` (`message`, `title`, `footer`, `buttons[]` com `label`, `type`, `url`/`phone`) ou `list` (`sections[].rows[]`). ```json theme={"system"} "event": { "name": "Reunião de alinhamento", "description": "Sala 2", "start_at": "2026-09-10T14:00:00.000Z", "end_at": "2026-09-10T15:00:00.000Z", "location": { "name": "Escritório" }, "canceled": false } ``` ```json theme={"system"} "event_response": { "event_message_id": "3EB0A9C6D2F1E4B5A7E1", "response": "going", "extra_guests": 1 } ``` `product` traz o snapshot do card enviado (`product_id`, `title`, `price`, `currency`, `business_phone`…); `order` traz o pedido feito pelo cliente a partir do catálogo (`order_id`, `token`, `item_count`, `status`, `total`…). Use `order_id` + `token` em `GET /business/orders/{id}` para os itens. A imagem do produto não é baixada. Convite para administrar um canal: `newsletter_id`, `name`, `caption`. Sem conteúdo de mensagem; `notification` diz o que aconteceu e `notification_parameters` traz os envolvidos: | `notification` | Significado | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `REVOKE` | Mensagem apagada para todos (`reference_message_id` diz qual) | | `GROUP_CREATE`, `GROUP_CHANGE_SUBJECT`, `GROUP_CHANGE_DESCRIPTION`, `GROUP_CHANGE_ICON` | Grupo criado / renomeado / descrição / foto | | `GROUP_PARTICIPANT_ADD`, `_REMOVE`, `_PROMOTE`, `_DEMOTE`, `_LEAVE`, `_INVITE` | Mudanças de participantes (`notification_parameters` = números) | | `MEMBERSHIP_APPROVAL_REQUEST` | Alguém pediu para entrar (aprove com `POST /groups/{id}/participants`) | | `CALL_RECEIVED`, `CALL_MISSED`, `CALL_MISSED_VOICE`, `CALL_MISSED_VIDEO` | Chamadas — a API não atende; veja `call_reject_auto` nas configurações | | `E2E_ENCRYPTED`, `CIPHERTEXT` | Aviso de criptografia / mensagem que não pôde ser decifrada ainda | | `PROFILE_NAME_UPDATED`, `PROFILE_PICTURE_UPDATED` | Contato mudou nome/foto | Tipo que o Wabox ainda não mapeia: `"unsupported": { "wa_type": "…" }`. Abra um chamado com o `wa_type` se precisar dele. ## Mensagens enviadas por você Por padrão, `received` **não** inclui o que o próprio número envia. Ligue `notify_sent_by_me` nos [filtros](/webhooks/filters) para receber também as mensagens digitadas no celular e as enviadas pela API (`from_me: true`; `from_api` separa as duas). É útil para espelhar a conversa num CRM. ## Grupos `phone` é o id do grupo (`120363012345678901-group`) e `participant_phone` quem escreveu. Para responder no grupo, use o id do grupo em `phone`; para responder no privado, use `participant_phone`. Se o remetente usa número oculto, `participant_phone` pode vir no formato `...@lid` — ele funciona igual como destino. ## Dicas * Responda 200 e processe depois; um `received` de mídia pode pesar (a mídia em si não vai no payload, só a URL). * Baixe a mídia logo: a URL expira em 24 h. * Ignore `waiting_message: true` (ou mostre "carregando"); o evento definitivo chega em seguida com o mesmo `message_id`. * Para não receber tipos que não usa (áudio, documentos, grupos), use os [filtros](/webhooks/filters) em vez de descartar no seu lado.