Skip to main content

​
Base URL

Toda rota da API pública fica sob a instância:
instance_id e token estão no painel, em Credenciais da instância. O token é a senha da instância. Não o exponha em front-end nem em URLs públicas, e gere um novo se vazar. Por padrão nenhum header de autenticação é necessário. Se o workspace tiver ligado Exigir API key nas rotas de instância, envie também Authorization: Bearer wbx_key_… com uma API key que tenha a permissão instances:operate (o header Client-Token, com o mesmo valor, é aceito como alias). As rotas de Conta (/account/*) autenticam só pela API key, e cada uma pede uma permissão. Veja Account API.
Em TypeScript/JavaScript, o SDK oficial (npm install @wabox/sdk) monta a URL, tipa bodies e respostas e verifica webhooks. Cada endpoint desta referência tem o exemplo em SDK na aba TypeScript.

​
Formato

  • JSON em requests (Content-Type: application/json) e responses.
  • snake_case em parâmetros, body, response e webhooks.
  • Datas em ISO-8601 UTC (2026-09-03T14:20:00.000Z). Exceção herdada da z-api: momment nos webhooks é epoch em milissegundos.
  • phone: só dígitos com DDI e DDD (5511988887777), ou um id de grupo (...-group), canal (...@newsletter), LID (...@lid) ou status@broadcast. Veja Identificadores.
  • Erros usam { "error": { "code": "...", "message": "..." } }. A lista está em Erros.

​
Dois tipos de endpoint

POST /send-*, reações, encaminhar, fixar, apagar, enquetes. Respondem 200 na hora com:
A mensagem entra na fila da instância e sai depois de um intervalo aleatório (anti-ban). O resultado chega no webhook delivery. Funcionam mesmo com a instância desconectada (a fila espera a reconexão), salvo se disable_enqueue_when_disconnected estiver ligado.

​
Playground

Cada página de endpoint tem um painel Try it. Preencha instance_id e token uma vez; os campos ficam salvos no navegador. As chamadas saem direto do seu navegador para api.wabox.me. Nada passa por servidores da documentação.
As mensagens enviadas pelo playground são reais. Use um número seu como phone.

​
Compatibilidade com a z-api

Rotas no formato da z-api (/create-group, /profile-picture, /modify-chat, /tags…) continuam funcionando como aliases, mas a referência documenta só a rota canônica. A lista completa está em Tabela de rotas.

​
Especificação OpenAPI

O Wabox gera esta referência a partir do código que roda em produção. O arquivo openapi.json serve para importar no Postman e no Insomnia ou para gerar um cliente com o OpenAPI Generator. Veja Postman e clientes.