Para testar a API do WhatsApp antes de registrar um número, peça uma chave de API do sandbox pelo WhatsApp, conecte um webhook HTTPS e envie mensagens e modelos para o seu próprio celular. O sandbox é gratuito e fica disponível na hora.[9] Um desenvolvedor pode começar a criar a integração no mesmo dia, sem número comercial, aprovação de conta ou reunião com vendas. Cada teste roda no celular do próprio desenvolvedor e fica longe dos clientes reais. Quando a empresa estiver pronta para entrar no ar, o código testado vai junto, com um novo endereço de servidor, uma nova chave de API e um novo webhook.
Principais conclusões
- A chave de API do sandbox chega como resposta no WhatsApp a uma única mensagem START, sem número registrado nem reunião com vendas.
- Cada chave do sandbox cobre até 200 mensagens, incluindo as requisições rejeitadas, todas enviadas a um único destinatário fixo: o WhatsApp do próprio testador.
- O sandbox verifica a autenticação do código, os eventos de webhook recebidos e o formato das requisições de mensagens e modelos.
- Testes que precisam das regras de um número comercial padrão devem rodar em um número 555 fornecido pela Meta, cobrado pelas tarifas padrão como qualquer número comum.
- A 360Dialog, Official Meta Solution Partner, oferece o sandbox e o acesso de produção à WhatsApp Business API.
O que é o sandbox da API do WhatsApp?
O sandbox da API do WhatsApp é um ambiente de teste da 360Dialog que envia mensagens em formato livre e modelos para um único destinatário fixo: a conta de WhatsApp do próprio testador.[1] O desenvolvedor usa o sandbox para validar o caminho do código: o cabeçalho de autenticação, o webhook e o formato das requisições. Cada conta de teste recebe a sua própria chave de API, vinculada a esse único destinatário.
Esse destinatário é o número de telefone do testador, mesmo que seja um telefone fixo com WhatsApp. Quando o testador não compartilha o número, o destinatário é um ID de usuário vinculado à empresa (“Business-Scoped User ID”, BSUID). No celular de teste, o testador faz o papel do cliente: envia mensagens ao sandbox e recebe as respostas.
Como conseguir uma chave de API do sandbox?
Envie a palavra START pelo WhatsApp para o número do sandbox da 360Dialog, e a chave de API do sandbox chega como resposta. Uma mensagem do celular de teste já é o pedido completo. A partir daí, cada chamada à API do sandbox leva essa chave no cabeçalho.
O número do sandbox está na página Sandbox da nossa documentação, junto com um link de conversa com um clique e um código QR. START precisa estar em letras maiúsculas. O WhatsApp pode pedir que o testador compartilhe os dados de contato. Se ele recusar ou responder tarde, a chave chega mesmo assim em até 5 minutos, junto com um BSUID.
Essa conta não tem número de telefone vinculado. Cada requisição dela leva o BSUID no campo recipient e deixa de fora o campo to. Conferir qual identificador a chave usa evita uma rodada de erros HTTP 403.
Como configurar o webhook do sandbox?
O webhook do sandbox é o endereço HTTPS em que o código recebe as mensagens do testador e uma atualização de status para cada mensagem que a API envia. Uma única chamada à API faz o registro. Com o webhook configurado primeiro, cada teste seguinte aparece como um evento que o código consegue processar.
Registre o endereço no host do sandbox com a chave no cabeçalho:
curl -X POST https://waba-sandbox.360dialog.io/v1/configs/webhook \
-H 'Content-Type: application/json' \
-H 'D360-API-KEY: <YOUR_API_KEY>' \
-d '{"url": "<YOUR_HTTPS_WEBHOOK_URL>"}'Uma chamada bem-sucedida retorna HTTP 200 com a URL. Um endereço http simples falha com HTTP 400 e a mensagem “url must be HTTPS”. Para testes rápidos, o webhook.site e o RequestBin fornecem endereços HTTPS temporários, e o ngrok cria um túnel para uma porta local. A mesma chamada troca o endereço do webhook a qualquer momento.
Para confirmar que o webhook funciona, envie outra mensagem ao número do sandbox pelo celular de teste. Um evento de entrada chega em entry[].changes[].value, e os status de enviada, entregue e lida chegam depois de cada mensagem de saída. Contas com número de telefone recebem wa_id, from e recipient_id. Contas com BSUID recebem user_id, from_user_id e recipient_user_id no lugar desses campos.
Como enviar a sua primeira mensagem e o seu primeiro modelo?
Envie um texto curto pela API para o WhatsApp do testador e, em seguida, envie um modelo pela mesma chamada. Um texto e um modelo entregues confirmam que a autenticação, o formato das requisições e os eventos de status funcionam de ponta a ponta.
O texto vai para /v1/messages no host do sandbox, com os mesmos dois cabeçalhos:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<YOUR_PHONE_NUMBER>",
"type": "text",
"text": { "body": "Hello from the sandbox" }
}Toda requisição precisa do campo messaging_product. O valor de to precisa ser exatamente o número vinculado à chave, e as contas com BSUID enviam "recipient": "<YOUR_BUSINESS_SCOPED_USER_ID>" no lugar dele. Qualquer outro valor, ou a falta dos dois campos, retorna HTTP 403. Uma requisição válida retorna HTTP 201 com um ID de mensagem.
O sandbox oferece três modelos fixos:
| Modelo | O que ele permite testar |
|---|---|
disclaimer | Uma mensagem de texto fixa, sem parâmetros e com a lista components vazia |
first_welcome_messsage | Um parâmetro no corpo que personaliza o nome do destinatário |
interactive_template_sandbox | Um modelo com dois botões |
Uma requisição de modelo define "type": "template", o nome do modelo e o código de idioma en.
O que não dá para fazer no sandbox?
O sandbox não envia mensagens para ninguém além do seu destinatário fixo, não envia modelos fora do seu conjunto de três, não carrega nem recupera mídia por ID de mídia e não passa de 200 mensagens. Conhecer esses limites de antemão mostra quais testes devem rodar em um número registrado.
Cada requisição que chega à API de mensagens consome uma das 200, mesmo quando a mensagem é rejeitada. Depois que as 200 acabam, o sandbox retorna HTTP 429. Conferir o corpo de cada requisição antes do envio preserva o saldo para os testes reais.
Um número em produção trata cada limite de outro jeito:
| Limite do sandbox | Em um número em produção |
|---|---|
| Um destinatário fixo | Clientes: mensagens em formato livre dentro de uma janela de atendimento ao cliente aberta, modelos fora dela[2] |
| Três modelos predefinidos | Os modelos da própria empresa, cada um aprovado antes do uso (por que os modelos são rejeitados) |
| Sem mídia por ID de mídia | Carregamento, recuperação e exclusão por ID de mídia, com os arquivos armazenados por 30 dias após o último uso[3] |
| 200 mensagens | Os limites de mensagens da Meta para o número |
Sandbox ou número 555 fornecido pela Meta: qual usar?
O sandbox serve para uma primeira verificação do código com a API, e um número 555 fornecido pela Meta serve para testes que precisam de um número comercial padrão na Plataforma do WhatsApp Business. A escolha define o que o teste comprova e o que precisa ser refeito depois.
| Pergunta | Sandbox | Número 555 fornecido pela Meta |
|---|---|---|
| O que comprova | Autenticação, tratamento do webhook e formato das requisições | Comportamento sob as regras de um número comercial padrão |
| Quem emite | 360Dialog | A Meta, que também faz a gestão do número |
| Melhor para | Verificações de código | Integração de clientes, avaliação, testes de integração, demonstrações e controle de qualidade interno |
| Para onde pode ir | Fica vinculado a um único destinatário de teste | Não pode ser transferido para outra WhatsApp account nem sair da Plataforma do WhatsApp Business |
Empresas elegíveis podem obter até dois números 555 da Meta durante o Embedded Signup, cada um com o código de país +1 dos EUA e o código de área 555.[4] Um número 555 é verificado automaticamente e segue as regras de preço e as classificações de qualidade padrão. O nome de exibição dele ainda precisa de aprovação antes da primeira mensagem. Cobramos cada um pelas tarifas padrão, como um número comum, e não reembolsamos números 555 integrados por engano.[5] O tráfego real de clientes deve ficar em um número comum, porque a configuração e o histórico de um número 555 não podem ser transferidos para outro número.
O que muda quando você passa do sandbox para um número em produção?
A passagem para um número em produção muda o endereço do servidor, a chave de API e o webhook. O cabeçalho de autenticação continua o mesmo. Planejar essas mudanças antes da troca mantém o código do sandbox reutilizável.
Um número em produção precisa de uma conta do WhatsApp Business (WABA) aprovada, um número de telefone registrado, uma chave de API e um webhook HTTPS. A Meta está dividindo a WABA em uma WhatsApp account, que contém o número de telefone, e uma Messaging account, que contém os modelos, o faturamento e as assinaturas de webhook.[6] A Meta registra os números integrados pelo Embedded Signup apenas para a WhatsApp Cloud API. Três coisas mudam no código e na configuração:
- Host e caminho: As mensagens vão para
https://waba-v2.360dialog.io/messages, que dispensa o prefixo/v1do caminho do sandbox. O cabeçalhoD360-API-KEYcontinua o mesmo. - Chave de API: Cada número de telefone recebe a sua própria chave no 360Dialog Hub.[7] Salve a chave assim que ela aparecer, porque o Hub mostra a chave uma única vez. Criar uma nova chave revoga todas as anteriores. Para clientes de parceiros, quem cria a chave é o parceiro de integração.
- Webhook: Substitua o endereço temporário do webhook.site, do RequestBin ou do ngrok por um ponto de extremidade HTTPS estável, com um certificado SSL válido. O domínio dele não pode ter sublinhados nem portas explícitas.[8] Dimensione o ponto de extremidade para as notificações de status, que somam cerca de três vezes o volume de saída ao tráfego de entrada. A Meta tenta reenviar as entregas que falharam por até 7 dias.
Uma rodada no sandbox resolve a autenticação, os webhooks e o formato das requisições antes de envolver qualquer número, revisão de modelo ou cliente. Assim, a equipe passa os primeiros dias no número em produção cuidando das próprias conversas.
O acesso de produção à WhatsApp Business API pela 360Dialog, Official Meta Solution Partner, usa o mesmo cabeçalho D360-API-KEY do sandbox. Clique em Começar a usar a API para registrar um número e apontar o código testado para o host de produção.
Perguntas frequentes
Por que o sandbox do WhatsApp não envia a minha mensagem?
A mensagem falha quando a chave, o destinatário ou o saldo de mensagens foge do que o sandbox espera. HTTP 401 significa que o cabeçalho D360-API-KEY está ausente ou é inválido. Uma resposta 403 indica que o valor de to ou recipient difere do vinculado à chave, ou que o corpo não traz nenhum dos dois. Quando o limite de 200 mensagens se esgota, o sandbox retorna HTTP 429.
HTTP 502 e HTTP 504 significam que a mensagem não chegou à API de mensagens a tempo. Tente enviar a requisição de novo mais tarde.
O sandbox do WhatsApp envia mensagens para mais de um número?
Não, o sandbox do WhatsApp só envia para o destinatário vinculado à chave de API: o número ou o ID de usuário vinculado à empresa do testador. Qualquer outro valor retorna HTTP 403. Testar com o celular de um colega, um aparelho de testes ou um grupo de usuários exige um número na Plataforma do WhatsApp Business, como um número comercial registrado ou um número 555 fornecido pela Meta.
Você pode usar os seus próprios modelos no sandbox do WhatsApp?
Não, o sandbox do WhatsApp envia apenas os seus três modelos predefinidos: disclaimer, first_welcome_messsage e interactive_template_sandbox. Não é possível criar nem editar modelos nele. Para testar o texto, os botões ou os cabeçalhos de mídia dos modelos da própria empresa, é preciso um número em produção, onde cada modelo é aprovado antes do primeiro envio.
O que é um ID de usuário vinculado à empresa no sandbox do WhatsApp?
Um ID de usuário vinculado à empresa (Business-Scoped User ID, BSUID) é o ID que o WhatsApp usa para uma pessoa dentro de uma empresa específica quando o número de telefone dela não é compartilhado. No sandbox, uma chave emitida sem número compartilhado fica vinculada a um BSUID. Cada requisição dessa conta informa o BSUID no campo recipient, e os eventos de webhook identificam o testador por ele.
O sandbox do WhatsApp aceita mensagens de mídia?
O sandbox do WhatsApp não permite carregar nem recuperar arquivos de mídia por ID de mídia. Testes de imagem, vídeo e documento que dependem de mídia carregada precisam de um número em produção. Nele, a API de produção carrega, recupera e exclui mídia por ID de mídia, e os arquivos carregados ficam armazenados por 30 dias após o último uso.
Fontes
[1] 360Dialog Docs, “Sandbox,” https://docs.360dialog.com/docs/get-started/sandbox (accessed October 29, 2026).
[2] 360Dialog Docs, “Send and Receive Messages,” https://docs.360dialog.com/docs/guides/send-and-receive-messages (accessed October 29, 2026).
[3] 360Dialog Docs, “Upload, Retrieve or Delete Media,” https://docs.360dialog.com/docs/messaging/media/upload-retrieve-or-delete-media (accessed October 29, 2026).
[4] Meta for Developers, “Embedded Signup,” section “555 business phone numbers,” https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/overview#555-business-phone-numbers (updated October 27, 2026; accessed October 29, 2026).
[5] 360Dialog Docs, “Meta Provided (555) Phone Numbers,” https://docs.360dialog.com/docs/resources/phone-numbers/meta-provided-555-phone-numbers (accessed October 29, 2026).
[6] Meta for Developers, “Updates to WhatsApp Business accounts,” https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/ (updated September 22, 2026; accessed October 29, 2026).
[7] 360Dialog Docs, “API Key,” https://docs.360dialog.com/docs/hub/api-key (accessed October 29, 2026).
[8] 360Dialog Docs, “Webhook,” https://docs.360dialog.com/docs/messaging/webhook (accessed October 29, 2026).
[9] 360Dialog Docs, “Overview,” https://docs.360dialog.com/docs (accessed October 29, 2026).
