Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Começar

Como testar a API de WhatsApp sem número e sem enviar nada?

Ambiente de teste da API de WhatsApp: 1 por conta, 30 dias, 100 envios por dia, sem número e sem enviar nada ao WhatsApp. Simule mensagens recebidas.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
O sandbox é uma instância de teste grátis, já conectada, com o número fictício 5500000000000: uma por conta, por 30 dias, com até 100 envios por dia. Os envios devolvem id começando com sandbox_ e sandbox: true, e as leituras devolvem dados fictícios sempre iguais. Para testar o recebimento, POST /sandbox/simulate/receive gera uma mensagem recebida de mentira. Nada sai para o WhatsApp.

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á.

bash
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"}'
json
{ "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átis

Como simulo uma mensagem recebida?

Com POST /sandbox/simulate/receive, informando quem "escreveu" e o texto:

bash
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:

  1. cadastre o endereço do aviso e use Testar aviso no painel;
  2. chame a rota de simulação;
  3. confira no seu sistema se o message.received chegou, com a assinatura válida;
  4. responda por POST /messages/text e veja o sandbox: 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

python
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)
js
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

Í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.

Perguntas frequentes

O sandbox envia mensagens de verdade?
Nunca. Nenhuma mensagem sai para o WhatsApp, nenhum número é usado e nenhum IP é consumido. As respostas são geradas pela própria ProxyBox.
Quantos sandboxes posso ter?
Um por conta, mesmo que o anterior tenha vencido ou sido cancelado. Dura 30 dias.
Posso testar o aviso automático no sandbox?
Sim. Cadastre o endereço, chame a rota de simulação e o aviso message.received de mentira chega ao seu sistema pelo mesmo caminho e com a mesma assinatura dos avisos reais.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp