Sandbox WhatsApp API: teste sem queimar seu número

Toda integração WhatsApp começa com a mesma dor: você quer testar o fluxo, mas testar significa queimar o seu número. Disparou 50 mensagens de teste para si mesmo? Risco de banimento. Conectou o número de produção em um ambiente que ainda tem bug? Cliente real recebe mensagem fantasma. Mexeu na webhook URL e esqueceu de voltar? Mensagens em produção param.

O Sandbox da ZAP API resolve isso com uma instância isolada que simula recebimento e envio de mensagens sem conexão real com o WhatsApp — ideal para QA, CI/CD, demos e migração entre provedores.

O que o Sandbox faz

• Simula mensagens recebidas — você dispara via API um simulate-inbound e seu webhook recebe o payload exatamente como receberia em produção (mesmo schema, mesma assinatura HMAC).
• Captura mensagens enviadas — quando seu app chama POST /v1/instances/:id/send, o sandbox grava a mensagem em vez de mandar pelo WhatsApp. Você consulta tudo via GET /v1/sandbox/:id/events.
• Não conta no rate limit — limite separado de 100 envios/dia por sandbox, sem afetar suas instâncias reais.
• Não consome instância paga — cada empresa tem 3 sandboxes grátis sempre disponíveis.

Quando usar Sandbox em vez de instância real

Criar um Sandbox

POST /v1/sandbox/instances
Authorization: Bearer tk_seu_token
Content-Type: application/json

{
  "name": "ci-pipeline",
  "webhookUrl": "https://staging.meu-app.com/webhook"
}

// Resposta
{
  "id": "sandbox_8a1b2c",
  "name": "ci-pipeline",
  "type": "sandbox",
  "status": "ready",
  "webhookUrl": "https://staging.meu-app.com/webhook",
  "limits": { "sendsPerDay": 100, "remainingToday": 100 }
}

Simular mensagem recebida (inbound)

Quer testar como seu chatbot reage a "Quero falar com humano"? Não precisa pegar o celular — dispara a simulação:

POST /v1/sandbox/sandbox_8a1b2c/simulate-inbound
Authorization: Bearer tk_seu_token
Content-Type: application/json

{
  "from": "5511999999999",
  "type": "text",
  "body": "Quero falar com humano"
}

// Resultado: seu webhook recebe imediatamente:
//   POST https://staging.meu-app.com/webhook
//   X-ZapApi-Signature: 
//   {
//     "id": "evt_xxx",
//     "type": "message.received",
//     "instanceId": "sandbox_8a1b2c",
//     "from": "5511999999999",
//     "body": "Quero falar com humano",
//     ...
//   }

Ver mensagens "enviadas" pelo seu app

Quando seu app dispara POST /v1/instances/sandbox_8a1b2c/send, a mensagem fica registrada no sandbox. Liste tudo:

GET /v1/sandbox/sandbox_8a1b2c/events
Authorization: Bearer tk_seu_token

// Resposta
{
  "events": [
    {
      "id": "evt_001",
      "direction": "out",
      "to": "5511999999999",
      "type": "text",
      "body": "Olá! Sou um atendente humano...",
      "timestamp": "2026-04-30T12:34:56Z"
    },
    {
      "id": "evt_002",
      "direction": "in",
      "from": "5511999999999",
      "type": "text",
      "body": "Quero falar com humano",
      "timestamp": "2026-04-30T12:34:50Z"
    }
  ]
}

Receita prática: teste E2E do chatbot no Jest

// chatbot.e2e.test.js
const axios = require('axios');
const SANDBOX = 'sandbox_8a1b2c';
const api = axios.create({
  baseURL: 'https://zap-api.tech/v1',
  headers: { Authorization: 'Bearer ' + process.env.ZAP_TOKEN }
});

test('Bot escala para humano quando usuário pede', async () => {
  // 1. Simula a mensagem do cliente
  await api.post(`/sandbox/${SANDBOX}/simulate-inbound`, {
    from: '5511999999999',
    type: 'text',
    body: 'Quero falar com humano'
  });

  // 2. Espera o bot processar
  await new Promise(r => setTimeout(r, 2000));

  // 3. Verifica resposta
  const { data } = await api.get(`/sandbox/${SANDBOX}/events`);
  const outbound = data.events.find(e => e.direction === 'out');

  expect(outbound).toBeDefined();
  expect(outbound.body).toMatch(/atendente humano/i);
});

Migração entre provedores: testar antes de cortar

Trocar de provedor de WhatsApp API é arriscado — se o novo provedor tiver bug em algum tipo de mensagem (ex: lista interativa), seu cliente recebe quebrado. O sandbox permite reproduzir o tráfego real antes de virar a chave:

1. Crie um sandbox apontando para um webhook de espelho.
2. No provedor antigo, configure um fan-out para mandar cópia dos eventos para o sandbox.
3. Compare os payloads recebidos lado a lado por uma semana.
4. Quando 100% dos cenários baterem, vire para a instância real.

Limites e restrições

• Máximo de 3 sandboxes por empresa (peça mais via suporte se precisar).
• 100 envios/dia por sandbox.
• Eventos são retidos por 7 dias e depois apagados.
• Não envia mensagens reais — qualquer payload com "to": "5511..." fica registrado mas nunca sai pelo WhatsApp.

FAQ

• Sandbox conta no preço?
  Não. As 3 sandboxes são grátis em todos os planos, inclusive trial.
• Posso usar HMAC em sandbox?
  Sim — o webhook do sandbox usa o mesmo padrão de assinatura da instância real, então seu validador funciona em ambos.
• Tem como simular mensagem com mídia (imagem, áudio)?
  Sim. Passe "type": "image" e um mediaUrl público no simulate-inbound.
• Posso simular falha de envio?
  Sim — passe "to": "0" no send e o sandbox responde com erro 4xx, igual a um número inválido.
• O sandbox aparece no painel admin?
  Sim, em /dashboard/sandbox com lista de eventos em tempo real.

Criar conta e começar a testar com Sandbox — trial 7 dias, sem cartão.