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.
Se o workspace tiver o Client-Token ativado, envie também o header Client-Token: <valor> em todas as chamadas.
- 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:
{ "error": { "code": "...", "message": "..." } } — lista em Erros.
Dois tipos de endpoint
Envios (fila)
Ações imediatas
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.Consultas e administração: status, contatos, grupos, perfil, chats, privacidade, catálogo, read-message, send-presence. Executam na hora contra o aparelho e exigem instância conectada — caso contrário 409 instance_not_connected. Nada é persistido.
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.
/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
Esta referência é gerada do código que roda em produção. O arquivo está disponível em openapi.json — importe no Postman, Insomnia ou gere um cliente com o OpenAPI Generator. Veja Postman e clientes.
