{"id":3042,"date":"2026-10-30T11:43:33","date_gmt":"2026-10-30T11:43:33","guid":{"rendered":"https:\/\/360dialog.com\/blog\/?p=3042"},"modified":"2026-11-06T09:38:40","modified_gmt":"2026-11-06T09:38:40","slug":"sandbox-api-whatsapp-como-testar","status":"publish","type":"post","link":"https:\/\/360dialog.com\/blog\/br\/sandbox-api-whatsapp-como-testar\/","title":{"rendered":"Sandbox da API do WhatsApp: como testar a API antes de registrar um n\u00famero"},"content":{"rendered":"\n

Para testar a API do WhatsApp antes de registrar um n\u00famero, pe\u00e7a uma chave de API do sandbox pelo WhatsApp, conecte um webhook HTTPS e envie mensagens e modelos para o seu pr\u00f3prio celular.<\/strong> O sandbox \u00e9 gratuito e fica dispon\u00edvel na hora.[9] Um desenvolvedor pode come\u00e7ar a criar a integra\u00e7\u00e3o no mesmo dia, sem n\u00famero comercial, aprova\u00e7\u00e3o de conta ou reuni\u00e3o com vendas. Cada teste roda no celular do pr\u00f3prio desenvolvedor e fica longe dos clientes reais. Quando a empresa estiver pronta para entrar no ar, o c\u00f3digo testado vai junto, com um novo endere\u00e7o de servidor, uma nova chave de API e um novo webhook.<\/p>\n\n\n\n

<\/p>\n\n\n\n

Principais conclus\u00f5es<\/h2>\n\n\n\n
    \n
  1. A chave de API do sandbox chega como resposta no WhatsApp a uma \u00fanica mensagem START, sem n\u00famero registrado nem reuni\u00e3o com vendas.<\/li>\n\n\n\n
  2. Cada chave do sandbox cobre at\u00e9 200 mensagens, incluindo as requisi\u00e7\u00f5es rejeitadas, todas enviadas a um \u00fanico destinat\u00e1rio fixo: o WhatsApp do pr\u00f3prio testador.<\/li>\n\n\n\n
  3. O sandbox verifica a autentica\u00e7\u00e3o do c\u00f3digo, os eventos de webhook recebidos e o formato das requisi\u00e7\u00f5es de mensagens e modelos.<\/li>\n\n\n\n
  4. Testes que precisam das regras de um n\u00famero comercial padr\u00e3o devem rodar em um n\u00famero 555 fornecido pela Meta, cobrado pelas tarifas padr\u00e3o como qualquer n\u00famero comum.<\/li>\n\n\n\n
  5. A 360Dialog, Official Meta Solution Partner, oferece o sandbox e o acesso de produ\u00e7\u00e3o \u00e0 WhatsApp Business API.<\/strong><\/li>\n<\/ol>\n\n\n\n

    <\/p>\n\n\n\n

    O que \u00e9 o sandbox da API do WhatsApp?<\/h2>\n\n\n\n

    O sandbox da API do WhatsApp \u00e9 um ambiente de teste da 360Dialog que envia mensagens em formato livre e modelos para um \u00fanico destinat\u00e1rio fixo: a conta de WhatsApp do pr\u00f3prio testador.[1] O desenvolvedor usa o sandbox para validar o caminho do c\u00f3digo: o cabe\u00e7alho de autentica\u00e7\u00e3o, o webhook e o formato das requisi\u00e7\u00f5es. Cada conta de teste recebe a sua pr\u00f3pria chave de API, vinculada a esse \u00fanico destinat\u00e1rio.<\/p>\n\n\n\n

    Esse destinat\u00e1rio \u00e9 o n\u00famero de telefone do testador, mesmo que seja um telefone fixo com WhatsApp. Quando o testador n\u00e3o compartilha o n\u00famero, o destinat\u00e1rio \u00e9 um ID de usu\u00e1rio vinculado \u00e0 empresa (\u201cBusiness-Scoped User ID\u201d, BSUID). No celular de teste, o testador faz o papel do cliente: envia mensagens ao sandbox e recebe as respostas.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Como conseguir uma chave de API do sandbox?<\/h2>\n\n\n\n

    Envie a palavra START pelo WhatsApp para o n\u00famero do sandbox da 360Dialog, e a chave de API do sandbox chega como resposta. Uma mensagem do celular de teste j\u00e1 \u00e9 o pedido completo. A partir da\u00ed, cada chamada \u00e0 API do sandbox leva essa chave no cabe\u00e7alho.<\/p>\n\n\n\n

    O n\u00famero do sandbox est\u00e1 na p\u00e1gina Sandbox da nossa documenta\u00e7\u00e3o<\/a>, junto com um link de conversa com um clique e um c\u00f3digo QR. START precisa estar em letras mai\u00fasculas. 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\u00e9 5 minutos, junto com um BSUID.<\/p>\n\n\n\n

    Essa conta n\u00e3o tem n\u00famero de telefone vinculado. Cada requisi\u00e7\u00e3o dela leva o BSUID no campo recipient<\/code> e deixa de fora o campo to<\/code>. Conferir qual identificador a chave usa evita uma rodada de erros HTTP 403.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Como configurar o webhook do sandbox?<\/h2>\n\n\n\n

    O webhook do sandbox \u00e9 o endere\u00e7o HTTPS em que o c\u00f3digo recebe as mensagens do testador e uma atualiza\u00e7\u00e3o de status para cada mensagem que a API envia. Uma \u00fanica chamada \u00e0 API faz o registro. Com o webhook configurado primeiro, cada teste seguinte aparece como um evento que o c\u00f3digo consegue processar.<\/p>\n\n\n\n

    Registre o endere\u00e7o no host do sandbox com a chave no cabe\u00e7alho:<\/p>\n\n\n\n

    curl -X POST https:\/\/waba-sandbox.360dialog.io\/v1\/configs\/webhook \\\n  -H 'Content-Type: application\/json' \\\n  -H 'D360-API-KEY: <YOUR_API_KEY>' \\\n  -d '{\"url\": \"<YOUR_HTTPS_WEBHOOK_URL>\"}'<\/code><\/pre>\n\n\n\n
    Uma chamada bem-sucedida retorna HTTP 200 com a URL. Um endere\u00e7o http simples falha com HTTP 400 e a mensagem “url must be HTTPS”. Para testes r\u00e1pidos, o webhook.site e o RequestBin fornecem endere\u00e7os HTTPS tempor\u00e1rios, e o ngrok cria um t\u00fanel para uma porta local. A mesma chamada troca o endere\u00e7o do webhook a qualquer momento.<\/p>\n\n\n\n
    Para confirmar que o webhook funciona, envie outra mensagem ao n\u00famero do sandbox pelo celular de teste. Um evento de entrada chega em entry[].changes[].value<\/code>, e os status de enviada, entregue e lida chegam depois de cada mensagem de sa\u00edda. Contas com n\u00famero de telefone recebem wa_id<\/code>, from<\/code> e recipient_id<\/code>. Contas com BSUID recebem user_id<\/code>, from_user_id<\/code> e recipient_user_id<\/code> no lugar desses campos.<\/p>\n\n\n\n
    <\/p>\n\n\n\n
    Como enviar a sua primeira mensagem e o seu primeiro modelo?<\/h2>\n\n\n\n
    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\u00e7\u00e3o, o formato das requisi\u00e7\u00f5es e os eventos de status funcionam de ponta a ponta.<\/p>\n\n\n\n
    O texto vai para \/v1\/messages<\/code> no host do sandbox, com os mesmos dois cabe\u00e7alhos:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"<YOUR_PHONE_NUMBER>\",\n  \"type\": \"text\",\n  \"text\": { \"body\": \"Hello from the sandbox\" }\n}<\/code><\/pre>\n\n\n\n
    Toda requisi\u00e7\u00e3o precisa do campo messaging_product<\/code>. O valor de to<\/code> precisa ser exatamente o n\u00famero vinculado \u00e0 chave, e as contas com BSUID enviam \"recipient\": \"<YOUR_BUSINESS_SCOPED_USER_ID>\"<\/code> no lugar dele. Qualquer outro valor, ou a falta dos dois campos, retorna HTTP 403. Uma requisi\u00e7\u00e3o v\u00e1lida retorna HTTP 201 com um ID de mensagem.<\/p>\n\n\n\n
    O sandbox oferece tr\u00eas modelos fixos:<\/p>\n\n\n\n
    Modelo<\/th>O que ele permite testar<\/th><\/tr><\/thead>
    disclaimer<\/code><\/td>Uma mensagem de texto fixa, sem par\u00e2metros e com a lista components<\/code> vazia<\/td><\/tr>
    first_welcome_messsage<\/code><\/td>Um par\u00e2metro no corpo que personaliza o nome do destinat\u00e1rio<\/td><\/tr>
    interactive_template_sandbox<\/code><\/td>Um modelo com dois bot\u00f5es<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    Uma requisi\u00e7\u00e3o de modelo define \"type\": \"template\"<\/code>, o nome do modelo e o c\u00f3digo de idioma en<\/code>.<\/p>\n\n\n\n
    <\/p>\n\n\n\n
    O que n\u00e3o d\u00e1 para fazer no sandbox?<\/h2>\n\n\n\n
    O sandbox n\u00e3o envia mensagens para ningu\u00e9m al\u00e9m do seu destinat\u00e1rio fixo, n\u00e3o envia modelos fora do seu conjunto de tr\u00eas, n\u00e3o carrega nem recupera m\u00eddia por ID de m\u00eddia e n\u00e3o passa de 200 mensagens. Conhecer esses limites de antem\u00e3o mostra quais testes devem rodar em um n\u00famero registrado.<\/p>\n\n\n\n
    Cada requisi\u00e7\u00e3o que chega \u00e0 API de mensagens consome uma das 200, mesmo quando a mensagem \u00e9 rejeitada. Depois que as 200 acabam, o sandbox retorna HTTP 429. Conferir o corpo de cada requisi\u00e7\u00e3o antes do envio preserva o saldo para os testes reais.<\/p>\n\n\n\n
    Um n\u00famero em produ\u00e7\u00e3o trata cada limite de outro jeito:<\/p>\n\n\n\n
    Limite do sandbox<\/th>Em um n\u00famero em produ\u00e7\u00e3o<\/th><\/tr><\/thead>
    Um destinat\u00e1rio fixo<\/td>Clientes: mensagens em formato livre dentro de uma janela de atendimento ao cliente aberta, modelos fora dela[2]<\/td><\/tr>
    Tr\u00eas modelos predefinidos<\/td>Os modelos da pr\u00f3pria empresa, cada um aprovado antes do uso (por que os modelos s\u00e3o rejeitados<\/a>)<\/td><\/tr>
    Sem m\u00eddia por ID de m\u00eddia<\/td>Carregamento, recupera\u00e7\u00e3o e exclus\u00e3o por ID de m\u00eddia, com os arquivos armazenados por 30 dias ap\u00f3s o \u00faltimo uso[3]<\/td><\/tr>
    200 mensagens<\/td>Os limites de mensagens da Meta<\/a> para o n\u00famero<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    <\/p>\n\n\n\n
    Sandbox ou n\u00famero 555 fornecido pela Meta: qual usar?<\/h2>\n\n\n\n
    O sandbox serve para uma primeira verifica\u00e7\u00e3o do c\u00f3digo com a API, e um n\u00famero 555 fornecido pela Meta serve para testes que precisam de um n\u00famero comercial padr\u00e3o na Plataforma do WhatsApp Business. A escolha define o que o teste comprova e o que precisa ser refeito depois.<\/p>\n\n\n\n
    Pergunta<\/th>Sandbox<\/th>N\u00famero 555 fornecido pela Meta<\/th><\/tr><\/thead>
    O que comprova<\/td>Autentica\u00e7\u00e3o, tratamento do webhook e formato das requisi\u00e7\u00f5es<\/td>Comportamento sob as regras de um n\u00famero comercial padr\u00e3o<\/td><\/tr>
    Quem emite<\/td>360Dialog<\/td>A Meta, que tamb\u00e9m faz a gest\u00e3o do n\u00famero<\/td><\/tr>
    Melhor para<\/td>Verifica\u00e7\u00f5es de c\u00f3digo<\/td>Integra\u00e7\u00e3o de clientes, avalia\u00e7\u00e3o, testes de integra\u00e7\u00e3o, demonstra\u00e7\u00f5es e controle de qualidade interno<\/td><\/tr>
    Para onde pode ir<\/td>Fica vinculado a um \u00fanico destinat\u00e1rio de teste<\/td>N\u00e3o pode ser transferido para outra WhatsApp account nem sair da Plataforma do WhatsApp Business<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    Empresas eleg\u00edveis podem obter at\u00e9 dois n\u00fameros 555 da Meta durante o Embedded Signup, cada um com o c\u00f3digo de pa\u00eds +1 dos EUA e o c\u00f3digo de \u00e1rea 555.[4] Um n\u00famero 555 \u00e9 verificado automaticamente e segue as regras de pre\u00e7o e as classifica\u00e7\u00f5es de qualidade padr\u00e3o. O nome de exibi\u00e7\u00e3o dele ainda precisa de aprova\u00e7\u00e3o antes da primeira mensagem. Cobramos cada um pelas tarifas padr\u00e3o, como um n\u00famero comum, e n\u00e3o reembolsamos n\u00fameros 555 integrados por engano.[5] O tr\u00e1fego real de clientes deve ficar em um n\u00famero comum, porque a configura\u00e7\u00e3o e o hist\u00f3rico de um n\u00famero 555 n\u00e3o podem ser transferidos para outro n\u00famero.<\/p>\n\n\n\n
    <\/p>\n\n\n\n
    O que muda quando voc\u00ea passa do sandbox para um n\u00famero em produ\u00e7\u00e3o?<\/h2>\n\n\n\n
    A passagem para um n\u00famero em produ\u00e7\u00e3o muda o endere\u00e7o do servidor, a chave de API e o webhook. O cabe\u00e7alho de autentica\u00e7\u00e3o continua o mesmo. Planejar essas mudan\u00e7as antes da troca mant\u00e9m o c\u00f3digo do sandbox reutiliz\u00e1vel.<\/p>\n\n\n\n
    Um n\u00famero em produ\u00e7\u00e3o precisa de uma conta do WhatsApp Business (WABA) aprovada<\/a>, um n\u00famero de telefone registrado, uma chave de API e um webhook HTTPS. A Meta est\u00e1 dividindo a WABA em uma WhatsApp account, que cont\u00e9m o n\u00famero de telefone, e uma Messaging account, que cont\u00e9m os modelos, o faturamento e as assinaturas de webhook.[6] A Meta registra os n\u00fameros integrados pelo Embedded Signup apenas para a WhatsApp Cloud API<\/a>. Tr\u00eas coisas mudam no c\u00f3digo e na configura\u00e7\u00e3o:<\/p>\n\n\n\n