Este guia leva uma instância nova da API de WhatsApp da ProxyBox da criação até a primeira mensagem enviada. A API não é a oficial da Meta: o WhatsApp pode bloquear qualquer número, por isso use um número que você possa perder e leia a política de uso aceitável antes de começar.
Posso testar antes, sem número e sem pagar?
Pode. O sandbox é uma instância de teste grátis, já conectada, uma por conta, por 30 dias e com 100 envios por dia. Nada sai para o WhatsApp; as respostas vêm marcadas com "sandbox": true, e você simula mensagens recebidas para testar o seu receptor de avisos. Os passos 4 e 5 abaixo valem igual para o sandbox. Recurso em beta: pode mudar.
O que preciso antes de começar?
Você precisa de três coisas: o celular do número, com chip ativo e WhatsApp instalado; uma conta na ProxyBox com uma instância contratada; e, se for receber avisos, um endereço https do seu sistema.
- O celular do número com o chip ativo e o WhatsApp instalado.
- Uma conta na ProxyBox e uma instância contratada (a página API de WhatsApp mostra os planos).
- Um endereço https do seu sistema, se for receber avisos (veja o guia do aviso automático).
1. Como crio a instância?
Pelo painel, em API de WhatsApp: dê um nome que você reconheça e a instância aparece como Preparando por alguns instantes.
No painel, abra API de WhatsApp e crie a instância com um nome que você reconheça, como "Atendimento da loja". Cada instância é um número, tem uma chave só dela e aparece como Preparando por alguns instantes.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátis2. Como conecto o número?
Leia o QR do painel em Aparelhos conectados no WhatsApp do número, ou digite o código de pareamento. Pela API, o passo a passo está em conectar por QR, código e passkey.
Quando o estado mudar para Aguardando a leitura do QR:
- No celular do número, abra o WhatsApp e entre em Configurações > Aparelhos conectados.
- Toque em Conectar um aparelho e leia o QR que aparece no painel. Se a câmera não ler, escolha Conectar com número de telefone e digite o código de pareamento que o painel mostra.
- O estado muda para Conectado e o número aparece no painel.
O QR vale poucos segundos e se renova sozinho. Se o painel mostrar Desconectado, repita o passo.
3. Onde guardo a chave?
Em um cofre ou numa variável de ambiente do seu sistema. A chave aparece uma vez, na criação da instância, e abre só aquela instância.
A chave tem o formato pbwa_ seguido de 40 caracteres e aparece uma vez, quando a instância é criada. Guarde em um cofre ou em uma variável de ambiente do seu sistema. Se perder ou suspeitar de vazamento, use Gerar chave nova: a anterior para de funcionar na hora.
4. Como envio a primeira mensagem?
Com POST /messages/text, a chave no cabeçalho apikey e o destino com código do país e DDD, só dígitos. A base da API é https://proxybox.com.br/api/whatsapp/v1.
A base da API é https://proxybox.com.br/api/whatsapp/v1 e a chave vai no cabeçalho apikey. O número de destino vai com o código do país e o DDD, só com dígitos.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Olá! Teste da API de WhatsApp."}'
const resp = await fetch("https://proxybox.com.br/api/whatsapp/v1/messages/text", {
method: "POST",
headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ to: "5547999999999", text: "Olá! Teste da API de WhatsApp." }),
});
console.log(resp.status, await resp.json());
Python
Use
requests(como abaixo). O agente padrão dourllibdo Python pode receber403do Cloudflare; se usarurllib, defina umUser-Agentpróprio.
import os, requests
r = requests.post(
"https://proxybox.com.br/api/whatsapp/v1/messages/text",
headers={"apikey": os.environ["WA_KEY"]},
json={"to": "5547999999999", "text": "Olá! Teste da API de WhatsApp."},
timeout=30,
)
print(r.status_code, r.json())
<?php
$ch = curl_init('https://proxybox.com.br/api/whatsapp/v1/messages/text');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['apikey: ' . getenv('WA_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['to' => '5547999999999', 'text' => 'Olá! Teste da API de WhatsApp.']),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', curl_exec($ch);
O texto aceita de 1 a 4.096 caracteres, reply_to (id de uma mensagem para responder) e mentions (telefones a mencionar, ou "everyone" em grupo). O destino também pode ser um grupo, pelo id que termina em @g.us.
Resposta de sucesso:
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-10T14:03:22-03:00" }
O painel também tem o botão Enviar mensagem de teste, que faz esta mesma chamada com a sua chave.
5. Como vejo o estado da instância?
Com GET /instance, que devolve o estado, o número, os limites e o uso do dia.
curl "https://proxybox.com.br/api/whatsapp/v1/instance" -H "apikey: SUA_CHAVE"
A resposta traz o estado (connected, disconnected, awaiting_qr...), o número, os limites e o uso do dia. Use esta rota antes de rotinas longas para saber se a instância está conectada. Para conferir se o WhatsApp responde de verdade, use GET /health: ele faz uma ida e volta real e informa se a instância está conectada mas sem resposta. [Recurso em beta: pode mudar.]
Quais são os limites e os erros mais comuns?
No padrão, cada instância envia até 10 mensagens por minuto e 500 por dia, com pausa de 3 a 10 segundos entre uma e outra; você pode deixar mais devagar, nunca mais rápido.
No padrão, cada instância envia até 10 mensagens por minuto e 500 por dia, com pausa de 3 a 10 segundos entre uma e outra. Você pode deixar mais devagar no painel, nunca mais rápido.
| Código | error |
O que fazer |
|---|---|---|
| 401 | invalid_key |
Conferir a chave; se trocou, atualizar o sistema |
| 403 | instance_paused |
A equipe pausou a instância; fale com o suporte |
| 403 | ip_not_allowed |
A chave tem IPs permitidos e este IP não está na lista |
| 403 | status_disabled |
O status vem desligado; ligue nos ajustes |
| 202 | (aprovação) | A mensagem ficou pendente de aprovação humana; não é erro |
| 409 | not_connected |
Ler o QR de novo no painel |
| 409 | new_contacts_locked |
O WhatsApp restringiu contatos novos; esperar retry_after |
| 422 | invalid_request |
Corrigir os campos indicados em fields |
| 422 | number_not_on_whatsapp |
O telefone de destino não tem WhatsApp |
| 429 | rate_limited ou daily_limit |
Esperar retry_after segundos |
| 501 | unsupported |
O recurso não está disponível nesta instância |
| 502 | engine_unavailable |
Tentar de novo; nada foi enviado |
| 503 | instance_preparing |
Aguardar a instância ficar pronta |
A tabela completa, com os erros de mídia, grupos e agendamento, está em erros e limites.
Que cuidados mantêm o número saudável?
Escrever só para quem espera receber, respeitar o ritmo e variar o texto. Nenhum cuidado garante que o WhatsApp não bloqueie o número.
- Peça consentimento e deixe fácil sair da lista. Mensagem para quem não conhece você gera denúncia, e denúncia gera bloqueio.
- Não repita o mesmo texto para muita gente. Varie e personalize.
- Use
Idempotency-Keynas chamadas de envio para não duplicar mensagem quando o seu sistema tentar de novo. - Respeite o 429. Esperar o
retry_afteré mais barato do que perder o número. - Trate o 409. Se a instância desconectou, pare as filas até conectar de novo.
Para entender o que o WhatsApp considera comportamento de risco, leia WhatsApp banido: causas na API e no Business.
Para onde vou depois da primeira mensagem?
Com a primeira mensagem enviada, escolha o próximo guia pelo que você precisa fazer. Em 12/11/2026 foram provados em aparelho real, pela API pública: texto, texto temporário (expires_in), texto citando (reply_to), imagem por base64, documento (PDF), voz e áudio como arquivo, figurinha, localização, contato, link (sai como texto com o endereço), enquete, botões de resposta e de ação (link, copiar código e ligar), reação (colocar e tirar), editar, apagar para todos, encaminhar, marcar como lida, ler conversa, não perturbe, aprovação humana, agendamento de uma mensagem, etiquetas, ajustes e proteções (IP permitido, status desligado), eventos por consulta e as rotas no estilo da Evolution (sendText, sendButtons, whatsappNumbers) e da Z-API (send-text). Não funcionam lista (menu) e carrossel. Ainda não foram provados: botão de localização, vídeo, status (stories), grupos além de listar, avisos de mensagens recebidas (voto de enquete, resposta de botão, reação, texto, foto e voz), recusa de chamada, S3, Chatwoot, bots e imagem por URL. Tudo da versão 1.2 que não está na lista de provados segue em beta: pode mudar.
- Mandar arquivo: imagem, vídeo, áudio, voz, documento e figurinha.
- Enquete, reação, editar e apagar: mensagens e ações.
- Grupos e canais: criar e administrar.
- Conferir um número antes de enviar: contatos.
- Ler conversas e baixar o que o cliente mandou: conversas e mídia recebida.
- Enviar numa hora marcada: agendar uma mensagem.
- Todas as rotas num só lugar: referência.
- Botões de resposta e de ação: botões (provados em 12/11/2026; lista e carrossel não funcionam).
- Receber sem endereço público: receber por consulta.
- Responder sozinho com um bot ou IA: bots e aprovação humana.
- Atender em equipe: Chatwoot e equipe e papéis.
- Proteger a chave: IPs permitidos e segurança.
- Ligar a outras ferramentas: integrações, modelos prontos e nós do n8n.
- Já usa a Evolution ou a Z-API: migrar da Evolution e migrar da Z-API.
- Trabalha com um assistente de IA: Claude e Cursor.
Veja também
- Sandbox da API de WhatsApp: testar sem número
- Referência da API de WhatsApp v1.2: rotas
- Webhook da API de WhatsApp: eventos e assinatura
- Erros e limites da API de WhatsApp
Índice completo: todos os guias.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra o catálogo da versão 1.2 da API.