Toda integração com WhatsApp começa com a mesma dúvida: dá para testar sem conectar um número? A resposta honesta é não. O envio e o recebimento reais de mensagens só existem com um número de WhatsApp conectado. O que dá para fazer é testar sem arriscar o número principal da sua operação. Este guia mostra como.
O que você consegue validar antes de conectar qualquer número
O seu endpoint de webhook pode ser testado sem nenhuma mensagem real. Depois de configurar a URL, peça um evento de teste:
PUT /v1/instances/SEU_INSTANCE_ID/webhook
Authorization: Bearer tk_seu_token
Content-Type: application/json
{ "url": "https://seu-app.com/webhook" }
POST /v1/instances/SEU_INSTANCE_ID/webhook/test
Authorization: Bearer tk_seu_tokenA resposta do PUT traz o campo webhookSecret, exibido uma única vez: guarde-o. A sua URL recebe então um evento instance.test com o header X-ZapAPI-Signature-256, calculado com essa chave do mesmo jeito que nas entregas reais. Com isso você confirma três coisas antes de envolver o WhatsApp: a URL está acessível, o seu servidor responde 2xx e a sua validação de assinatura confere com a chave guardada.
Use um número secundário para o teste real
Para testar envio e recebimento de verdade, conecte um número que não seja o da operação:
- Um chip separado, com o WhatsApp já em uso normal há alguns dias. Número recém-ativado que começa a disparar chama atenção.
- Destinatários que você controla: o seu próprio celular e o da sua equipe. Não teste com a base de clientes.
- Volume baixo: poucas mensagens bastam para validar o fluxo. Teste de carga em número real é o caminho mais curto para uma restrição.
O período de teste
A conta nova tem 7 dias de teste, sem cartão, com uma instância. É tempo suficiente para conectar o número secundário pelo QR Code, enviar as primeiras mensagens, receber os webhooks e conferir os status de entrega. Durante o teste há um limite diário de envios.
Roteiro sugerido
- Crie a conta e copie o token da instância.
- Configure o webhook e dispare o evento de teste. Só siga quando a sua URL responder 2xx e a assinatura validar.
- Conecte o número secundário pelo QR Code.
- Envie uma mensagem para o seu próprio celular com
POST /v1/instances/SEU_INSTANCE_ID/send. O espelho da mensagem enviada chega ao webhook comomessage.sente, quando ela for entregue, chega omessage.status. Se você configurou filtro de eventos no webhook, inclua esses eventos nele. - Responda pelo celular e confira o
message.received. - Quando o fluxo estiver certo, conecte o número da operação em uma instância própria.
Os campos de cada chamada estão na documentação.
Mantenha teste e produção separados
Depois de entrar em produção, não reaproveite a instância da operação para experimentar. Trocar a URL do webhook de uma instância em uso desvia os eventos reais para o ambiente errado. Use uma instância e um número só para testes, com webhook próprio.
FAQ
- Dá para testar envio e recebimento sem número?
Não. Todo envio e recebimento real usa um número conectado. O que pode ser testado sem número é o seu endpoint de webhook, com o evento de teste. - Preciso de cartão para testar?
Não. São 7 dias de teste sem cartão. - Posso testar com o meu número pessoal?
Pode, mas o recomendado é um número secundário, para que um erro de integração não afete as suas conversas. - Como testo a assinatura do webhook?
Com o evento de teste: ele chega assinado com o segredo do webhook da instância, da mesma forma que as entregas reais.
Criar conta e testar por 7 dias — sem cartão.