> ## 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. # Mensagens recentes da conversa > Ao parear, o celular envia ao Wabox as conversas recentes com as últimas mensagens de cada uma; o Wabox guarda **até 50 mensagens por conversa** (as mais recentes) em object storage e as devolve aqui no mesmo formato do webhook `received` — sem envelope (`type`, `event_id`, `instance_id`). Mídia vem só com metadados (`download_error` = `media not downloaded (history sync)`), nunca é baixada no sync. Não é histórico completo: mensagens mais antigas que as sincronizadas pelo celular e conversas sem atividade recente podem não existir aqui (`messages` vazio, nunca 404). Depois do pareamento, o tráfego novo chega só pelos webhooks — esta rota **não** acompanha mensagens ao vivo. Não exige a instância conectada. Desligue com `settings.history_enabled = false` (apaga o que já foi guardado); logout e exclusão da instância também apagam. ## OpenAPI ````yaml /openapi.json get /instances/{instance_id}/token/{token}/chats/{phone}/messages openapi: 3.1.0 info: title: Wabox API description: >- API pública do Wabox — WhatsApp via REST + webhooks. Base: `{server}/instances/{instance_id}/token/{token}`. Header `Client-Token` obrigatório quando ativado em Segurança. Tudo em `snake_case`. Datas ISO-8601 (UTC). Erros: `{ "error": { "code": "...", "message": "..." } }`. Envios respondem `{ id, message_id, wabox_id, status: "queued" }` na hora; o resultado chega no webhook `delivery`. `message_id` já é o id definitivo do WhatsApp. version: '1.0' contact: {} servers: - url: https://api.wabox.me security: [] tags: - name: Instance description: >- Conexão (QR code / código de pareamento), status, webhooks e configurações da instância. x-group: Instância - name: Messages description: >- Envio de texto, mídia, localização, contatos, reações, enquetes e ações sobre mensagens. Tudo passa pela fila; o resultado chega no webhook `delivery`. x-group: Mensagens - name: Interactive description: >- Botões, listas, carrossel, PIX, eventos de calendário, status (stories) e convite de canal. Best effort: renderizam no celular; o WhatsApp Web/Desktop não exibe botões, listas nem carrossel. x-group: Interativos - name: Queue description: Mensagens aguardando envio (pacing anti-ban ou instância desconectada). x-group: Fila - name: Chats description: >- Lista de conversas, ações (arquivar, silenciar, fixar, ler) e mensagens temporárias. x-group: Chats - name: Contacts description: Contatos, foto de perfil, verificação de números e bloqueio. x-group: Contatos - name: Profile description: Nome, recado e foto do número conectado. x-group: Perfil - name: Groups description: >- Criar, listar, administrar participantes, links de convite e configurações. x-group: Grupos - name: Communities description: Comunidades e vínculo de grupos. x-group: Comunidades - name: Newsletters description: >- Canais (newsletters): criar, seguir, ler e reagir a posts. Para publicar, use qualquer `send-*` com `phone: @newsletter`. x-group: Canais - name: Privacy description: Configurações de privacidade da conta. x-group: Privacidade - name: Business description: >- Perfil comercial, catálogo de produtos, pedidos e envio de produto/catálogo/pedido. Best effort: depende do protocolo do WhatsApp Web. x-group: Business e catálogo - name: Labels description: Etiquetas (labels) de conversas — só em contas WhatsApp Business. x-group: Etiquetas - name: Partner description: >- Para integradores: criar e administrar instâncias do próprio workspace Partner com o header `Partner-Token` (base `/partner`, sem `instance_id`/`token` na URL). As instâncias criadas aqui são operadas pela API pública normal e não têm trial nem `402`. x-group: Partner - name: Webhooks description: Eventos entregues por `POST` na URL configurada em cada instância. x-group: Webhooks paths: /instances/{instance_id}/token/{token}/chats/{phone}/messages: get: tags: - Chats summary: Mensagens recentes da conversa description: >- Ao parear, o celular envia ao Wabox as conversas recentes com as últimas mensagens de cada uma; o Wabox guarda **até 50 mensagens por conversa** (as mais recentes) em object storage e as devolve aqui no mesmo formato do webhook `received` — sem envelope (`type`, `event_id`, `instance_id`). Mídia vem só com metadados (`download_error` = `media not downloaded (history sync)`), nunca é baixada no sync. Não é histórico completo: mensagens mais antigas que as sincronizadas pelo celular e conversas sem atividade recente podem não existir aqui (`messages` vazio, nunca 404). Depois do pareamento, o tráfego novo chega só pelos webhooks — esta rota **não** acompanha mensagens ao vivo. Não exige a instância conectada. Desligue com `settings.history_enabled = false` (apaga o que já foi guardado); logout e exclusão da instância também apagam. operationId: chats.messages parameters: - name: instance_id required: true in: path description: Id da instância (dashboard › instância › Credenciais). schema: type: string example: 8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b - name: token required: true in: path description: Token da instância. Trate como senha. schema: type: string example: 3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E - name: phone required: true in: path description: Telefone do contato ou id do grupo schema: example: '5511988887777' type: string responses: '200': description: >- Até 50 mensagens, da mais antiga para a mais recente. `messages` vazio quando o celular não sincronizou essa conversa (ou `enabled` = false). content: application/json: schema: $ref: '#/components/schemas/ChatHistory' example: phone: '5511988887777' enabled: true synced_at: '2026-09-16T12:00:05.000Z' messages: - momment: 1789560000000 message_id: 3EB0C767D26A8B1F2C9A phone: '5511988887777' 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: Oi, ainda tem o produto? - momment: 1789560060000 message_id: 3EB0A1B2C3D4E5F60718 phone: '5511988887777' from_me: true from_api: false is_group: false is_newsletter: false is_edit: false forwarded: false broadcast: false waiting_message: false status: READ text: message: Tem sim! Posso separar pra você. '401': description: Instância/token inválidos ou `Client-Token` ausente. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: instance_not_found message: Instance not found or invalid token '402': description: Workspace sem assinatura ativa. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: subscription_required message: Active subscription required '409': description: Instância não está conectada. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: instance_not_connected message: Instance is not connected '503': description: Histórico não configurado neste ambiente. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: history_not_configured message: Chat history is not configured on this server x-codeSamples: - lang: typescript label: TypeScript (@wabox/sdk) source: | import { createWabox } from "@wabox/sdk"; const wabox = createWabox({ instanceId: process.env.WABOX_INSTANCE_ID!, token: process.env.WABOX_TOKEN!, }); const { data, error } = await wabox.GET("/chats/{phone}/messages", { params: { path: { phone: "5511988887777" }, }, }); if (error) throw new Error(error.error.message); console.log(data); components: schemas: ChatHistory: type: object properties: phone: type: string enabled: type: boolean synced_at: nullable: true type: string messages: type: array items: type: object properties: momment: type: integer minimum: 0 maximum: 9007199254740991 message_id: type: string minLength: 1 phone: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ chat_lid: type: string sender_lid: type: string from_me: type: boolean from_api: type: boolean is_group: type: boolean is_newsletter: type: boolean is_edit: type: boolean forwarded: type: boolean broadcast: type: boolean waiting_message: type: boolean status: type: string enum: - PENDING - SENT - RECEIVED - READ - READ_BY_ME - PLAYED chat_name: type: string sender_name: type: string sender_photo: type: string participant_phone: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ participant_lid: type: string reference_message_id: type: string minLength: 1 message_expiration_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 expires_at: type: integer minimum: 0 maximum: 9007199254740991 text: type: object properties: message: type: string title: type: string description: type: string url: type: string thumbnail_url: type: string required: - message additionalProperties: false image: type: object properties: mime_type: type: string url: type: string format: uri download_error: type: string view_once: type: boolean file_size: type: integer minimum: 0 maximum: 9007199254740991 sha256: type: string caption: type: string thumbnail_url: type: string width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - mime_type additionalProperties: false audio: type: object properties: mime_type: type: string url: type: string format: uri download_error: type: string view_once: type: boolean file_size: type: integer minimum: 0 maximum: 9007199254740991 sha256: type: string ptt: type: boolean seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - mime_type - ptt additionalProperties: false video: type: object properties: mime_type: type: string url: type: string format: uri download_error: type: string view_once: type: boolean file_size: type: integer minimum: 0 maximum: 9007199254740991 sha256: type: string caption: type: string thumbnail_url: type: string seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 is_gif: type: boolean required: - mime_type additionalProperties: false document: type: object properties: mime_type: type: string url: type: string format: uri download_error: type: string view_once: type: boolean file_size: type: integer minimum: 0 maximum: 9007199254740991 sha256: type: string file_name: type: string title: type: string caption: type: string page_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - mime_type additionalProperties: false sticker: type: object properties: mime_type: type: string url: type: string format: uri download_error: type: string view_once: type: boolean file_size: type: integer minimum: 0 maximum: 9007199254740991 sha256: type: string animated: type: boolean required: - mime_type additionalProperties: false location: type: object properties: latitude: type: number longitude: type: number name: type: string address: type: string url: type: string required: - latitude - longitude additionalProperties: false contact: type: object properties: display_name: type: string vcard: type: string phones: type: array items: type: string required: - display_name - vcard - phones additionalProperties: false contacts: type: array items: type: object properties: display_name: type: string vcard: type: string phones: type: array items: type: string required: - display_name - vcard - phones additionalProperties: false reaction: type: object properties: value: type: string time: type: integer minimum: 0 maximum: 9007199254740991 reaction_by: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ referenced_message: type: object properties: message_id: type: string minLength: 1 from_me: type: boolean phone: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ participant: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ required: - message_id - from_me - phone additionalProperties: false required: - value - time - reaction_by - referenced_message additionalProperties: false poll: type: object properties: question: type: string poll_max_options: type: integer minimum: -9007199254740991 maximum: 9007199254740991 options: type: array items: type: object properties: name: type: string required: - name additionalProperties: false required: - question - poll_max_options - options additionalProperties: false poll_vote: type: object properties: poll_message_id: type: string minLength: 1 options: type: array items: type: object properties: name: type: string required: - name additionalProperties: false required: - poll_message_id - options additionalProperties: false buttons_response: type: object properties: button_id: type: string message: type: string required: - button_id - message additionalProperties: false list_response: type: object properties: selected_row_id: type: string title: type: string message: type: string required: - selected_row_id additionalProperties: false buttons: type: object properties: message: type: string title: type: string footer: type: string buttons: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - reply - url - call - copy - other url: type: string phone: type: string required: - label - type additionalProperties: false required: - message - buttons additionalProperties: false list: type: object properties: message: type: string title: type: string footer: type: string button_label: type: string sections: type: array items: type: object properties: title: type: string rows: type: array items: type: object properties: id: type: string title: type: string description: type: string required: - id - title additionalProperties: false required: - rows additionalProperties: false required: - message - sections additionalProperties: false event: type: object properties: name: type: string description: type: string start_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ end_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ location: type: object properties: name: type: string latitude: type: number longitude: type: number additionalProperties: false join_link: type: string canceled: type: boolean extra_guests_allowed: type: boolean required: - name - start_at - canceled additionalProperties: false event_response: type: object properties: event_message_id: type: string minLength: 1 response: type: string enum: - going - not_going - maybe - unknown extra_guests: type: integer minimum: 0 maximum: 9007199254740991 required: - event_message_id - response additionalProperties: false newsletter_invite: type: object properties: newsletter_id: type: string name: type: string caption: type: string required: - newsletter_id additionalProperties: false product: type: object properties: product_id: type: string title: type: string description: type: string currency: type: string price: type: number minimum: 0 maximum: 1000000000 sale_price: type: number minimum: 0 maximum: 1000000000 retailer_id: type: string url: type: string business_phone: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ image_count: type: integer minimum: 0 maximum: 9007199254740991 body: type: string footer: type: string required: - product_id - title additionalProperties: false order: type: object properties: order_id: type: string token: type: string item_count: type: integer minimum: 0 maximum: 9007199254740991 status: type: string enum: - inquiry - accepted - declined - unknown title: type: string message: type: string seller_phone: type: string minLength: 1 pattern: >- ^(\d{5,20}|\d+@lid|\d+(-\d+)?-group|\d+@g\.us|\d+@newsletter|\d+@broadcast|status@broadcast)$ total: type: number minimum: 0 maximum: 1000000000 currency: type: string order_request_message_id: type: string minLength: 1 required: - order_id - item_count - status additionalProperties: false notification: type: string enum: - REVOKE - GROUP_CREATE - GROUP_CHANGE_SUBJECT - GROUP_CHANGE_DESCRIPTION - GROUP_CHANGE_ICON - GROUP_PARTICIPANT_ADD - GROUP_PARTICIPANT_REMOVE - GROUP_PARTICIPANT_PROMOTE - GROUP_PARTICIPANT_DEMOTE - GROUP_PARTICIPANT_LEAVE - GROUP_PARTICIPANT_INVITE - MEMBERSHIP_APPROVAL_REQUEST - CALL_RECEIVED - CALL_MISSED - CALL_MISSED_VOICE - CALL_MISSED_VIDEO - E2E_ENCRYPTED - CIPHERTEXT - PROFILE_NAME_UPDATED - PROFILE_PICTURE_UPDATED notification_parameters: type: array items: type: string unsupported: type: object properties: wa_type: type: string required: - wa_type additionalProperties: false required: - momment - message_id - phone - from_me - from_api - is_group - is_newsletter - is_edit - forwarded - broadcast - waiting_message - status additionalProperties: false required: - phone - enabled - synced_at - messages additionalProperties: false ApiError: type: object properties: error: type: object properties: code: type: string description: >- Código estável do erro (`instance_not_found`, `invalid_request`…). message: type: string description: Descrição legível, em inglês. details: description: 'Contexto extra (ex.: `issues` de validação).' type: object additionalProperties: {} required: - code - message additionalProperties: false required: - error additionalProperties: false ````