Skip to main content

​
O que é (em uma frase)

O modo sandbox permite usar a mesma API v1 da produção, mas com uma chave que começa com sk_test_. Nada é entregue de verdade em SMS, e-mail, WhatsApp, Telegram, push ou RCS: o resultado aparece na Caixa sandbox do painel (menu Developer) e os webhooks vêm com os mesmos nomes de evento da produção, mais o campo sandbox: true para você separar teste do ambiente ao vivo.

​
Quando usar o sandbox

Use sandbox quando quiser:
  • Desenvolver ou revisar uma integração (backend, CRM, automação) sem gastar crédito nem mandar mensagem para cliente real.
  • Rodar homologação ou CI com respostas previsíveis e tela de inbox, sem depender de operadora.
  • Treinar o time em payloads, templates e webhooks antes de trocar para sk_live_.
  • Reproduzir fluxos (envio → entregue → lido → falha) com os botões de simular na Caixa sandbox e o seu endpoint de webhook.

​
Quando usar a produção (sk_live_)

Troque para chave ao vivo quando precisar:
  • Entregar mensagem em telefone ou caixa de entrada reais.
  • Validar algo que só o provedor resolve (ex.: template no Meta, DNS de domínio de e-mail).
  • Cobrança normal do plano ou operações que só existem com provedor real.
Resumo: sandbox é para ensaiar API + webhooks + painel; produção é para tráfego de verdade.

​
Por onde começar (3 passos)

  1. Criar a chave — No painel: Configurações → API Keys → Nova API Key → escolha Sandbox. Copie o valor sk_test_....
  2. Chamar a API — Mesma URL base e caminhos /v1/... da produção. Envie Authorization: Bearer sk_test_... ou x-api-key: sk_test_.... O ambiente vem da própria chave; não dependa de um cabeçalho extra só para marcar “teste”.
  3. Ver o resultado — Developer → Caixa sandbox: abra uma linha para ver payload, use Liberar agora em agendamentos e os botões de simular para disparar eventos de webhook (entregue, lido, clique, falha etc., conforme o canal).
Para um passo a passo em linguagem bem acessível, há também este artigo no blog: Ambiente sandbox: testar integração sem enviar SMS (nem e-mail) de verdade.

​
Chave e autenticação

  • Chaves de teste começam com sk_test_; as de produção com sk_live_.
  • Envie a chave como hoje: Authorization: Bearer sk_test_... ou x-api-key: sk_test_....
  • O ambiente fica implícito na chave (sem cabeçalho tipo X-Environment) para reduzir risco de misturar teste e produção.

​
Regras principais

AssuntoComportamento
OnboardingObrigatório também no sandbox (igual à API ao vivo).
Plano / trial / bloqueio comercialNo sandbox o fluxo simulado não aplica bloqueio comercial nem débito de saldo/crédito; valem só os limites específicos de sandbox abaixo.
Limite diárioAté 50 mensagens por dia em UTC por workspace; acima disso a API responde 429 com código SANDBOX_DAILY_LIMIT.
RetençãoCada registro na inbox expira em 7 dias (expiresAt).
AgendamentoEm sandbox, itens agendados ficam em SCHEDULED até você clicar em Liberar agora na Caixa sandbox (não há disparo automático por cron).
WebhooksMesmos nomes de evento da produção; o payload inclui sandbox: true (e campos relacionados) para filtrar no mesmo endpoint.

​
Onde ver no painel

  • Developer → Caixa sandbox: lista, detalhe, Liberar agora para itens agendados e botões para simular entrega, leitura, falha etc., disparando os webhooks correspondentes. As opções de simulação dependem do canal da mensagem.

​
O que ainda não entra no sandbox (MVP)

Operações que precisam falar com provedor real (por exemplo criar instância de WhatsApp com QR, verificar domínio de e-mail no provedor) devem retornar erro documentado (SANDBOX_NOT_SUPPORTED, 403 ou 501). Use a Caixa sandbox e chaves sk_test_ para testar fluxo de mensagem e webhooks; use chave sk_live_ quando precisar da rede de verdade ponta a ponta.