Recurso em beta: pode mudar. O sandbox foi construído e testado em ambiente de teste. Você cria o sandbox pelo painel; a criação por API ainda está desligada (em breve).
Para que serve?
Para construir e testar a sua integração antes de conectar um número e contratar uma instância:
- escrever o código de envio e tratar os erros;
- cadastrar o endereço do aviso automático e conferir a assinatura;
- montar o fluxo no n8n, no Make ou no Zapier;
- mostrar a um cliente ou a um colega como a API se comporta, sem risco para nenhum número.
Como nada toca o WhatsApp, não há risco de bloqueio, de mensagem enviada por engano nem de custo de IP.
O que o sandbox simula?
| Parte | Comportamento no sandbox |
|---|---|
| Estado | Sempre connected, com o número 5500000000000 |
send.* (texto, mídia, enquete...) |
Valida o pedido, aplica limites e devolve id com prefixo sandbox_ e sandbox: true; nada é enviado |
| Leituras (conversas, contatos, grupos) | Dados fictícios, os mesmos a cada chamada |
| Erros | Os mesmos de uma instância real: campos inválidos, limites, Idempotency-Key |
| Aviso automático | Funciona de verdade, para o seu endereço, quando você simula uma mensagem |
| IP brasileiro | Não usa; o sandbox não passa por IP nenhum |
| Limite diário | 100 envios por dia |
Toda resposta, de sucesso ou de erro, traz "sandbox": true no início, para o seu código saber em que ambiente está.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE_DO_SANDBOX" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Teste do sandbox"}'
{ "sandbox": true, "ok": true, "id": "sandbox_01JAB2C3D4", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-12T10:00:00-03:00" }
Como crio o sandbox?
No painel, em API de WhatsApp, escolha criar o ambiente de teste. Você recebe uma chave pbwa_… como em qualquer instância, mas que só abre o sandbox. Cada conta tem direito a um, mesmo que o anterior tenha vencido ou sido cancelado. Para uma instância de verdade, escolha um plano.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo simulo uma mensagem recebida?
Com POST /sandbox/simulate/receive, informando quem "escreveu" e o texto:
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/sandbox/simulate/receive" \
-H "apikey: SUA_CHAVE_DO_SANDBOX" -H "Content-Type: application/json" \
-d '{"from": "5547999999999", "text": "Oi, quero saber do pedido"}'
A ProxyBox gera um aviso message.received de mentira e o entrega pelo mesmo fluxo dos avisos reais: assinado, com histórico, com novas tentativas e, se você ligou o modo de consulta, disponível em GET /events. O limite é de 60 simulações por hora e de 30 chamadas por minuto à rota.
Isso permite testar de ponta a ponta:
- cadastre o endereço do aviso e use Testar aviso no painel;
- chame a rota de simulação;
- confira no seu sistema se o
message.receivedchegou, com a assinatura válida; - responda por
POST /messages/texte veja osandbox: true.
E o vencimento?
Depois de 30 dias a instância de teste deixa de responder: toda chamada devolve 403 sandbox_expired com a mensagem "O seu período de teste de 30 dias acabou. Crie uma instância de verdade para continuar." Um comando diário confere os vencimentos. Os dados do sandbox não migram para uma instância de verdade; só o código de integração que você escreveu.
Como o código muda do sandbox para a instância real?
Quase nada. A base é a mesma (https://proxybox.com.br/api/whatsapp/v1); troque a chave. O que muda no comportamento:
- as respostas deixam de ter
"sandbox": true; - o ritmo real de envio passa a valer (10 por minuto e 500 por dia), com a pausa entre mensagens;
- aparecem os erros que dependem do WhatsApp:
number_not_on_whatsapp,new_contacts_locked,not_connected; - as leituras mostram o que o seu número realmente tem.
O que o sandbox não prova
Seja honesto com a sua própria equipe sobre isto:
- Entrega e leitura. O sandbox não diz se o WhatsApp entregaria a mensagem nem se o número seria restringido.
- Mídia recebida e voz. Não há arquivo de verdade para baixar, nem conversor de áudio.
- Botões, status e enquetes. O sandbox aceita o pedido, mas o desenho no aparelho não é testável aqui. Veja botões.
- Desempenho. O tempo de resposta do sandbox não representa o de uma instância conectada a um número.
Em Python e em Node
import os, requests
B = "https://proxybox.com.br/api/whatsapp/v1"
H = {"apikey": os.environ["WA_SANDBOX_KEY"]}
requests.post(f"{B}/sandbox/simulate/receive", headers=H, json={"from": "5547999999999", "text": "teste"}, timeout=30)
const B = "https://proxybox.com.br/api/whatsapp/v1";
await fetch(`${B}/sandbox/simulate/receive`, {
method: "POST",
headers: { apikey: process.env.WA_SANDBOX_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ from: "5547999999999", text: "teste" }),
});
O próximo passo é o guia de primeiros passos, que vale igual para o sandbox e para a instância real.
Veja também
- Enviar a 1ª mensagem pela API de WhatsApp
- Webhook da API de WhatsApp: eventos e assinatura
- Receber WhatsApp sem webhook e agrupar mensagens
- Referência da API de WhatsApp v1.2: rotas
Índice completo: documentação. Sobre o produto: uma instância de WhatsApp por número.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra o plano sandbox da versão 1.2. Recurso em beta.