Skip to main content
A Account API é para quem quer administrar instâncias sem passar pelo painel, como um CRM, um omnichannel ou uma plataforma de atendimento que cria um número de WhatsApp para cada cliente, ou um time que provisiona canais por script. Ela está disponível para contas com plano. Contas em trial criam a instância pelo painel e recebem 403 plan_required na Account API.

​
Slots: o que o plano compra

O plano do Wabox é cobrado por slot (canal), não por instância. Com um plano de 5 slots, a conta pode ter até 5 instâncias ao mesmo tempo, e pode criar, atualizar e excluir dentro desse limite:
  • Cada instância existente ocupa um slot, conectada ou não, criada pelo painel ou pela API.
  • Com todos os slots em uso, POST /account/instances responde 409 instance_limit_reached.
  • Excluir uma instância libera o slot na hora, e a próxima criação já passa.
  • GET /account/plan mostra instance_slots, instances_used e instances_available.
Contas Partner (integradores com contrato próprio, como o Kinbox) usam a mesma API, sem limite de slots e sem cobrança no Wabox, e instance_slots vem null. Fale com a gente em wabox.me/partners.

​
Autenticação

Todas as rotas ficam sob https://api.wabox.me/account e autenticam por uma API key do workspace em Authorization: Bearer. As keys são criadas em Segurança › API keys no painel (owner ou admin), cada uma com um nome e as permissões que você marcar:
  • O Wabox mostra a key uma única vez, ao criá-la, e guarda só o hash. Se perdeu, crie outra e revogue a antiga. Revogar uma key não afeta as demais.
  • Só Authorization: Bearer é aceito aqui. O alias Client-Token vale apenas nas rotas de instância.
  • A allowlist de IPs do workspace vale também aqui.
  • Rate limit por conta, com os mesmos headers e 429 da API pública.
  • Os erros têm o mesmo formato: { "error": { "code": "api_key_required" | "insufficient_scope" | "plan_required" | "subscription_required" | "instance_limit_reached" | "ip_not_allowed" | "instance_not_found" | ... } }.

​
Permissões por rota

Um provisionador típico usa uma key com instances:read + instances:write. A permissão instances:operate não abre nenhuma rota /account/*. Ela só serve para as rotas de instância quando o workspace exige API key nelas. Nesse caso, inclua-a na mesma key se o seu backend também opera os números.

​
Erros

As API keys substituíram o header Account-Token (act_…), que não é mais aceito. Crie uma key com as permissões necessárias e troque o header por Authorization: Bearer.

​
Fluxo típico: um canal por cliente

1

Crie a instância quando o cliente pedir um número

A resposta é a instância completa, com id, token, api_url e webhooks (inclusive o secret para verificar a assinatura). Guarde id, token e secret junto do cliente no seu banco. Se vier 409 instance_limit_reached, aumente o plano ou exclua uma instância que não é mais usada.
2

Mostre o QR code ao cliente

Use a API pública normal com as credenciais devolvidas: GET {api_url}/qr-code (data URL) ou /qr-code/image (PNG), ou GET {api_url}/phone-code/{phone} para pareamento por código. O webhook instance_status acompanha o ciclo inteiro (qr, connecting e connected) e avisa quando o número entrou e quando voltar a mostrar o QR.
3

Opere o número como qualquer instância

Tudo funciona como na documentação da API: POST {api_url}/send-text, webhooks received/delivery/message_status, grupos, contatos. Recomendamos notify_sent_by_me: true para espelhar no seu produto o que o cliente digitou no celular.
4

Quando o cliente cancelar, exclua a instância

DELETE /account/instances/{id} desconecta o aparelho no celular do cliente, para a sessão, remove a instância (a fila é descartada) e devolve o slot.

​
Rotas

​
Webhooks do workspace

Se todas as instâncias apontam para o mesmo backend, configure uma vez em PUT /account/webhooks (mesmos campos de PUT /webhooks) e crie as instâncias sem webhooks. single_url_enabled com single_url manda todos os eventos para uma URL só. Esse é o modo padrão de um workspace novo, então basta enviar single_url. As instâncias herdam URLs, filtros e o secret do workspace, um só para verificar X-Wabox-Signature, em vez de um por instância. O secret nasce no primeiro PUT. Uma instância que precise de outro destino recebe webhooks próprios no POST/PUT /account/instances. Isso desliga a herança só nela, e ela volta a usar o próprio secret. A referência completa, com exemplos de request e response, está em API Reference › Conta.

​
Boas práticas para integradores

  • Um webhook por evento, com a assinatura verificada. Instâncias com webhooks próprios têm secret próprio; guarde-o ao criar e leia X-Wabox-Instance-Id para saber de qual cliente veio a entrega antes de escolher o segredo.
  • Idempotência do seu lado. Se a criação falhar por rede sem resposta, liste com q=<seu nome único> antes de criar de novo, para não gastar um slot com uma instância órfã.
  • Exclua o que não usa. Instância parada também ocupa slot; ao encerrar um cliente, faça o DELETE.
  • Não exponha a API key no front-end nem em ferramentas no-code. Com instances:write ela cria e apaga instâncias no seu nome; com instances:read ela lê o token de todas.
  • Uma key por sistema, com o mínimo de permissões. Para trocar sem downtime, crie a nova, publique e só então revogue a antiga (Rotação).
  • Mostre o QR de novo ao cliente quando instance_status vier com status: logged_out (ou qr). banned não volta e precisa de um número novo.
  • Limites por instância. Continuam valendo a fila de 1.000 mensagens, o intervalo anti-ban e 60 req/s. Com muitos clientes, o gargalo é sempre o número, nunca a Account API.