> ## 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. # Criar instância > Cria uma instância no workspace Partner e já inicia a sessão. A resposta traz `id`, `token` e `api_url`: use-os na API pública normal para obter o QR (`GET /qr-code`), status e enviar mensagens. `webhooks` e `settings` são opcionais e aceitam os mesmos campos de `PUT /webhooks` e `PUT /settings`. Instâncias Partner não têm trial nem `402`. ## OpenAPI ````yaml openapi.json POST /partner/instances 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: /partner/instances: post: tags: - Partner summary: Criar instância description: >- Cria uma instância no workspace Partner e já inicia a sessão. A resposta traz `id`, `token` e `api_url`: use-os na API pública normal para obter o QR (`GET /qr-code`), status e enviar mensagens. `webhooks` e `settings` são opcionais e aceitam os mesmos campos de `PUT /webhooks` e `PUT /settings`. Instâncias Partner não têm trial nem `402`. operationId: partnerInstances.create parameters: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 80 description: Nome da instância (rótulo interno). webhooks: description: Webhooks e filtros, como em `PUT /webhooks`. type: object properties: received_url: nullable: true type: string format: uri delivery_url: nullable: true type: string format: uri message_status_url: nullable: true type: string format: uri connected_url: nullable: true type: string format: uri disconnected_url: nullable: true type: string format: uri chat_presence_url: nullable: true type: string format: uri single_url_enabled: type: boolean description: >- `true` = todos os eventos vão para `single_url`; as `*_url` por tipo são ignoradas. single_url: nullable: true description: >- URL única para todos os eventos (quando `single_url_enabled`). type: string format: uri notify_sent_by_me: type: boolean ignore_groups: type: boolean ignore_private: type: boolean ignore_text: type: boolean ignore_image: type: boolean ignore_video: type: boolean ignore_audio: type: boolean ignore_document: type: boolean ignore_received_callback: type: boolean ignore_delivery_callback: type: boolean ignore_message_status_callback: type: boolean ignore_connected_callback: type: boolean ignore_disconnected_callback: type: boolean ignore_chat_presence_callback: type: boolean use_workspace_webhooks: type: boolean description: >- `true` = a instância usa as URLs e filtros configurados no workspace (painel › Webhooks) e ignora os campos próprios; o `secret` continua sendo da instância. Definir uma URL não nula na instância desliga isso automaticamente, salvo se `use_workspace_webhooks` vier junto. settings: description: Configurações, como em `PUT /settings`. type: object properties: auto_read_message: type: boolean auto_read_status: type: boolean call_reject_auto: type: boolean call_reject_message: nullable: true type: string maxLength: 1000 disable_enqueue_when_disconnected: type: boolean queue_max_age_hours: type: integer minimum: 1 maximum: 168 delay_message_min_ms: type: integer minimum: 0 maximum: 15000 delay_message_max_ms: type: integer minimum: 0 maximum: 15000 proxy_url: nullable: true type: string format: uri history_enabled: type: boolean required: - name examples: basico: summary: Só o nome value: name: Loja Centro completo: summary: Com webhooks e configurações value: name: Loja Centro webhooks: received_url: https://kinbox.example/wabox/received delivery_url: https://kinbox.example/wabox/delivery message_status_url: https://kinbox.example/wabox/status connected_url: https://kinbox.example/wabox/connected disconnected_url: https://kinbox.example/wabox/disconnected notify_sent_by_me: true settings: call_reject_auto: true call_reject_message: Não atendemos chamadas. responses: '201': description: Instância criada. content: application/json: schema: $ref: '#/components/schemas/Instance' example: id: 8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b name: Loja Centro token: 3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E status: qr status_reason: null connected: false phone: null profile_name: null platform: null connected_at: null disconnected_at: null subscription_status: partner trial_ends_at: '2026-09-15T12:00:00.000Z' due_at: null settings: auto_read_message: false auto_read_status: false call_reject_auto: false call_reject_message: null disable_enqueue_when_disconnected: false queue_max_age_hours: 12 delay_message_min_ms: 1000 delay_message_max_ms: 3000 proxy_url: null webhooks: received_url: https://kinbox.example/wabox/received delivery_url: https://kinbox.example/wabox/delivery message_status_url: https://kinbox.example/wabox/status connected_url: https://kinbox.example/wabox/connected disconnected_url: https://kinbox.example/wabox/disconnected chat_presence_url: null notify_sent_by_me: true ignore_groups: false ignore_private: false ignore_text: false ignore_image: false ignore_video: false ignore_audio: false ignore_document: false ignore_received_callback: false ignore_delivery_callback: false ignore_message_status_callback: false ignore_connected_callback: false ignore_disconnected_callback: false ignore_chat_presence_callback: false secret: whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0 api_url: >- https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E created_at: '2026-09-15T12:00:00.000Z' updated_at: '2026-09-15T12:00:00.000Z' '401': description: '`Partner-Token` ausente ou inválido.' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: partner_token_required message: Invalid Partner-Token security: - PartnerToken: [] x-codeSamples: - lang: typescript label: TypeScript (@wabox/sdk) source: > import { createWaboxPartner } from "@wabox/sdk"; const partner = createWaboxPartner({ partnerToken: process.env.WABOX_PARTNER_TOKEN! }); const { data, error } = await partner.POST("/partner/instances", { body: { name: "Loja Centro" }, }); if (error) throw new Error(error.error.message); console.log(data); components: schemas: Instance: type: object properties: id: type: string name: type: string token: description: Token da instância. Presente em `GET /me` e na Partner API. type: string status: type: string enum: - created - starting - qr - connecting - connected - disconnected - logged_out - banned - stopped status_reason: nullable: true type: string connected: type: boolean phone: nullable: true description: Número conectado (só dígitos). type: string profile_name: nullable: true type: string platform: nullable: true type: string connected_at: nullable: true description: ISO-8601 (UTC). type: string disconnected_at: nullable: true description: ISO-8601 (UTC). type: string subscription_status: type: string enum: - trial - active - past_due - canceled - expired - partner trial_ends_at: type: string description: ISO-8601 (UTC). due_at: nullable: true description: ISO-8601 (UTC). type: string settings: type: object properties: auto_read_message: type: boolean auto_read_status: type: boolean call_reject_auto: type: boolean call_reject_message: nullable: true type: string disable_enqueue_when_disconnected: type: boolean queue_max_age_hours: type: integer minimum: -9007199254740991 maximum: 9007199254740991 delay_message_min_ms: type: integer minimum: -9007199254740991 maximum: 9007199254740991 delay_message_max_ms: type: integer minimum: -9007199254740991 maximum: 9007199254740991 proxy_url: nullable: true type: string history_enabled: type: boolean required: - auto_read_message - auto_read_status - call_reject_auto - call_reject_message - disable_enqueue_when_disconnected - queue_max_age_hours - delay_message_min_ms - delay_message_max_ms - proxy_url - history_enabled additionalProperties: false webhooks: type: object properties: use_workspace_webhooks: type: boolean description: >- `true` = usa as URLs e filtros do workspace (painel › Webhooks) e ignora os campos abaixo; o `secret` é sempre da instância. received_url: nullable: true description: URL http(s) ou `null` (desligado). type: string delivery_url: nullable: true description: URL http(s) ou `null` (desligado). type: string message_status_url: nullable: true description: URL http(s) ou `null` (desligado). type: string connected_url: nullable: true description: URL http(s) ou `null` (desligado). type: string disconnected_url: nullable: true description: URL http(s) ou `null` (desligado). type: string chat_presence_url: nullable: true description: URL http(s) ou `null` (desligado). type: string single_url_enabled: type: boolean description: >- `true` = todos os eventos vão para `single_url`; as `*_url` por tipo são ignoradas. single_url: nullable: true description: URL única para todos os eventos (quando `single_url_enabled`). type: string notify_sent_by_me: type: boolean ignore_groups: type: boolean ignore_private: type: boolean ignore_text: type: boolean ignore_image: type: boolean ignore_video: type: boolean ignore_audio: type: boolean ignore_document: type: boolean ignore_received_callback: type: boolean ignore_delivery_callback: type: boolean ignore_message_status_callback: type: boolean ignore_connected_callback: type: boolean ignore_disconnected_callback: type: boolean ignore_chat_presence_callback: type: boolean secret: nullable: true description: >- Chave HMAC do header `X-Wabox-Signature` quando a instância usa a própria configuração; `null` = entregas não assinadas. Herdando do workspace (`use_workspace_webhooks`), as entregas usam o `secret` do workspace. type: string required: - use_workspace_webhooks - received_url - delivery_url - message_status_url - connected_url - disconnected_url - chat_presence_url - single_url_enabled - single_url - notify_sent_by_me - ignore_groups - ignore_private - ignore_text - ignore_image - ignore_video - ignore_audio - ignore_document - ignore_received_callback - ignore_delivery_callback - ignore_message_status_callback - ignore_connected_callback - ignore_disconnected_callback - ignore_chat_presence_callback - secret additionalProperties: false api_url: type: string description: Base da API pública desta instância. created_at: type: string description: ISO-8601 (UTC). updated_at: type: string description: ISO-8601 (UTC). required: - id - name - status - status_reason - connected - phone - profile_name - platform - connected_at - disconnected_at - subscription_status - trial_ends_at - due_at - settings - webhooks - api_url - created_at - updated_at 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 securitySchemes: PartnerToken: type: apiKey in: header name: Partner-Token description: >- Credencial da Partner API (workspace › Segurança › Partner API). Só nas rotas `/partner/*`. ````