Skip to main content
A Partner API é para quem embute o Wabox no próprio produto (um CRM, um omnichannel, uma plataforma de atendimento) e quer criar um número de WhatsApp para cada cliente sem passar pelo painel. Cada instância criada por ela pertence ao seu workspace Partner e é cobrada por você ao seu cliente; o Wabox não aplica trial nem 402.
O programa Partner é ativado pela equipe do Wabox. Depois disso, o token aparece em Segurança › Partner API no painel. Fale com a gente em wabox.me/partners.

​
Autenticação

Todas as rotas ficam sob https://api.wabox.me/partner e usam o header Partner-Token:
  • O token é mostrado uma única vez ao ser gerado (só o hash fica guardado). Perdeu? Gere outro; o anterior para de valer na hora.
  • A allowlist de IPs do workspace vale também aqui. O Client-Token não: o Partner-Token já é a credencial.
  • Rate limit por workspace Partner, com os mesmos headers e 429 da API pública.
  • Erros no mesmo formato: { "error": { "code": "partner_token_required" | "ip_not_allowed" | "instance_not_found" | ... } }.

​
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, webhooks (inclusive o secret para verificar a assinatura) e subscription_status: "partner". Guarde id, token e secret junto do cliente no seu banco.
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 connected avisa quando o número entrou.
3

Opere o número como qualquer instância

POST {api_url}/send-text, webhooks received/delivery/message_status, grupos, contatos… tudo igual à documentação da API. Recomendação: 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 /partner/instances/{id} desconecta o aparelho no celular do cliente, para a sessão e remove a instância (a fila é descartada).

​
Rotas

A referência completa, com exemplos de request e response, está em API Reference › Partner.

​
Boas práticas para integradores

  • Um webhook por evento, com a assinatura verificada. O secret é por instância; 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 deixar instâncias órfãs.
  • Não exponha o Partner-Token no front-end nem em ferramentas no-code. Ele cria instâncias no seu nome.
  • Trate disconnected com reason: logged_out mostrando o QR de novo ao cliente; banned não volta e precisa de um número novo.
  • Limites por instância continuam valendo: fila de 1.000 mensagens, intervalo anti-ban, 60 req/s. Com muitos clientes, o gargalo é sempre o número, nunca a Partner API.