Pular para o conteúdo principal

​
Integração e operações

  • Valide que o número de WhatsApp está conectado antes de testar envios.
  • Para qualquer resposta não-2xx, registre o statusCode e o corpo da resposta — isso facilita muito a depuração.
  • Para erros 429 e 5xx, tente novamente com backoff exponencial e jitter.
  • Use webhooks para observar todo o ciclo de vida (sent/delivered/read/failed) em tempo real, em vez de fazer polling.

​
Segurança

  • Mantenha a chave de API apenas no backend — nunca a envie para um navegador ou aplicativo móvel.
  • Evite registrar dados sensíveis (a chave completa ou o conteúdo das mensagens, se sua política exigir).

​
FAQ rápido

​
Recebi 403 com o código TENANT_SCOPE_NOT_ALLOWED

Você usou uma chave com escopo de tenant em um endpoint por número (ex.: POST /v1/messages/send). Use a chave com escopo de número da página API Keys (/api-keys).

​
Recebi 403 com o código NUMBER_SCOPE_NOT_ALLOWED

Você usou uma chave com escopo de número em um endpoint exclusivo de tenant (ex.: /v1/numbers/*, /v1/branding). Use a chave com escopo de tenant em Perfil → API.

​
O status READ / message.read nunca chega

O evento de leitura só é disparado quando o destinatário tem os recibos de leitura do WhatsApp ativados (Configurações → Privacidade). Caso contrário, o ciclo de vida para em DELIVERED — isso é um comportamento do WhatsApp, não uma falha de entrega.

​
Relacionados