Este guia usa uma chave de sandbox (bz_sandbox_): ela não chama a Meta, não consome quota e só envia para os números sintéticos do sandbox. É o caminho mais rápido para conhecer a API antes de conectar um número de verdade. O caminho principal desta e de todas as outras páginas de guia é a API REST (curl/TypeScript/JavaScript); veja a nota sobre o SDK Node ao final.
Gere uma chave de sandbox
No painel da BotoZap, abra Chaves de API, gere uma chave nova e escolha o ambiente Sandbox. Guarde o valor num lugar seguro: ele é mostrado uma vez só. Exporte a chave no seu ambiente:
export BOTOZAP_KEY="bz_sandbox_..."A conta é derivada da chave, então você nunca passa um id de conta. O isolamento multi-tenant é garantido no servidor. Detalhes em Autenticação.
Envie a primeira mensagem
Faça um POST para /api/v1/messages usando o número mágico +5500000000001. Ele simula todo o ciclo de vida (entregue, depois lida) e sempre tem a janela de atendimento aberta:
Enviar uma mensagem de texto (sandbox)
Testa o envio ponta a ponta sem credenciais Meta e sem custo, usando o número mágico de happy path do sandbox.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "text",
"text": {
"body": "Oi! 👋 Tudo bem?"
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"status": "sent",
"sandbox": true
}Chave de ambiente sandbox (`bz_sandbox_`) nunca chama a Meta, nunca consome quota e só envia pelo número sintético da conta.
Depois do 201, o BotoZap simula o ciclo de vida (delivered → read) e dispara seu webhook assinado, como em produção — veja `docs/sandbox.md`.
Envie um template
No sandbox qualquer nome de template é aceito (a Meta não é chamada para validar o catálogo). Em produção, o template precisa existir e estar aprovado na WABA:
Enviar um template (sandbox)
No sandbox, qualquer nome de template é aceito — a Meta não é chamada, então não há catálogo para validar contra.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "template",
"template": {
"name": "boas_vindas",
"language": {
"code": "pt_BR"
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"status": "sent",
"sandbox": true
}Em produção (chave live), o nome do template precisa existir e estar APPROVED na WABA.
Liste suas mensagens
Listar mensagens
Lista as mensagens da conta, mais recentes primeiro, paginado por cursor.
curl https://botozap.com.br/api/v1/messages?limit=2 \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": [],
"paging": {
"cursors": {
"before": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"after": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
},
"next": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"previous": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
}
}Próximos passos
- Enviar mensagens: a janela de 24h, telefone vs. BSUID e todos os cenários do sandbox.
- Webhooks: receba eventos de mensagem e status de entrega, inclusive os que o sandbox simula.
- Confiabilidade e entrega: o que a API garante (e o que não garante) sobre duplicatas, ordem e retries.
- Quando estiver pronto para um número real, troque a chave por uma
bz_live_. O mesmo código funciona, só o ambiente muda.
Prefere Node.js? O @botozap/sdk já está publicado no npm (ver SDK Node). Ele é um envelope tipado sobre a mesma API REST usada nos exemplos acima.