Primeiros passos

Crie a conta e uma instância

Cadastre-se em app.wabox.me/signup. Cada instância representa um número de WhatsApp. Clique em Nova instância, dê um nome e abra a instância criada.Na aba Dados da instância, em Credenciais, você encontra o ID da instância e o Token da instância. Eles formam a base de todas as chamadas:

https://api.wabox.me/instances/{instance_id}/token/{token}

A conta tem um período de teste, que começa ao criar a primeira instância (uma instância no teste). Quando ele termina, os endpoints de envio respondem 402 subscription_required até você assinar um plano; leitura, status e webhooks continuam funcionando. O plano é por slots, e cada slot é uma instância que a conta pode ter ao mesmo tempo.

Conecte o número

No celular que vai ser conectado, abra o WhatsApp em Configurações › Aparelhos conectados › Conectar aparelho e leia o QR code mostrado no painel.Prefere fazer isso pela API? O QR muda a cada ~20 segundos; consulte-o em loop enquanto o status for qr. Se ninguém ler em cerca de 13 minutos, a instância para de gerar QR (fica disconnected); chamar GET /qr-code de novo recomeça o pareamento:

curl https://api.wabox.me/instances/{instance_id}/token/{token}/qr-code
# { "value": "data:image/png;base64,...", "expires_at": "...", "connected": false }

curl -o qr.png https://api.wabox.me/instances/{instance_id}/token/{token}/qr-code/image

curl https://api.wabox.me/instances/{instance_id}/token/{token}/phone-code/5511999998888
# { "value": "ABCD-EFGH" } → digite em "Conectar com número de telefone"

Confirme com GET /status:

{ "connected": true, "smartphone_connected": true, "status": "connected", "phone": "5511999998888", "error": null }

Envie a primeira mensagem

Use um número seu para testar. phone é só dígitos, com DDI e DDD.

curl -X POST https://api.wabox.me/instances/{instance_id}/token/{token}/send-text \
  -H "Content-Type: application/json" \
  -d '{ "phone": "5511988887777", "message": "Olá! Mensagem enviada pelo Wabox." }'

const res = await fetch(`https://api.wabox.me/instances/${instanceId}/token/${token}/send-text`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "5511988887777", message: "Olá! Mensagem enviada pelo Wabox." }),
});
console.log(await res.json());

import requests

r = requests.post(
    f"https://api.wabox.me/instances/{instance_id}/token/{token}/send-text",
    json={"phone": "5511988887777", "message": "Olá! Mensagem enviada pelo Wabox."},
)
print(r.json())

$ch = curl_init("https://api.wabox.me/instances/$instanceId/token/$token/send-text");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["phone" => "5511988887777", "message" => "Olá! Mensagem enviada pelo Wabox."]),
]);
echo curl_exec($ch);

A resposta chega na hora, antes de a mensagem sair do aparelho:

{ "id": "3EB0A9C6D2F1E4B5A7C8", "message_id": "3EB0A9C6D2F1E4B5A7C8", "wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01", "status": "queued" }

message_id já é o id definitivo da mensagem no WhatsApp e é o mesmo que aparece nos webhooks. O envio em si é assíncrono. Ele passa pela fila com um pequeno intervalo aleatório (anti-ban), e o resultado chega no webhook delivery.

Receba mensagens por webhook

No painel, em Webhooks e configurações gerais, informe a URL que vai receber cada tipo de evento. Ou faça pela API:

curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "received_url": "https://seu-servidor.com/wabox/received",
    "delivery_url": "https://seu-servidor.com/wabox/delivery",
    "message_status_url": "https://seu-servidor.com/wabox/status"
  }'

Responda qualquer mensagem para o número conectado e o seu endpoint recebe um POST como este:

{
  "type": "received",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968300000,
  "message_id": "3EB0A9C6D2F1E4B5A7C8",
  "phone": "5511988887777",
  "from_me": false,
  "is_group": false,
  "chat_name": "Maria",
  "sender_name": "Maria",
  "status": "RECEIVED",
  "text": { "message": "Olá! Tudo bem?" }
}

Responda 200 rápido e processe depois. Para testar sem servidor público, use um túnel (ngrok, Cloudflare Tunnel) ou um serviço de “request bin”.

Próximos passos

Conceitos

Instância, fila, webhooks e os identificadores que aparecem em tudo.

Assinatura dos webhooks

Verifique que cada entrega veio do Wabox.

Tipos de mensagem

Mídia, localização, contatos, enquetes, reações e edição.

Aba Testes

Rode o checklist automático da sua instância pelo painel.

Começar

Autenticação e segurança

Webhooks

Guias

Migrando do z-api

Integrações

Conta

Referências

Primeiros passos

Próximos passos

Conceitos

Assinatura dos webhooks

Tipos de mensagem

Aba Testes

​Próximos passos

Conceitos

Assinatura dos webhooks

Tipos de mensagem

Aba Testes

Próximos passos