​

Visao geral

​

Sinais do ciclo de entrega

• sms.otp
• message.queued
• message.sent
• message.delivered
• message.scheduled
• message.failed
• message.canceled
• message.batch

​

Praticas de maior impacto

• Envie apenas para numeros E.164 validos que o seu projeto pode usar.
• Mantenha OTP e mensagens transacionais curtas.
• Use Idempotency-Key nas operacoes de create/send.
• Persista payloads de webhook e deduplique por id de evento.
• Retorne 2xx rapidamente no handler de webhook.

​

Estrategia de template e conteudo

• Prefira templates quando o mesmo fluxo se repete.
• Mantenha nomes de placeholders estaveis em todas as variantes.
• Coloque contexto de marca no inicio da mensagem.
• Mantenha a cobertura de locale alinhada com os paises para os quais voce realmente envia.
• Use tags para segmentar por caso de uso ou campanha.

{
  "to": "+5511999999999",
  "content": "Rewrite: seu codigo de verificacao e 123456",
  "tags": {
    "use_case": "otp_login",
    "template_version": "v3"
  }
}

​

Tratamento de falhas

• Retente apenas cenarios 429 e 5xx transientes.
• Trate 400 de validacao como falha permanente ate corrigir o payload.
• Trate 403 de assinatura/faturamento como bloqueio operacional, nao como retry de envio.
• Inspecione o payload de message.failed para ver detalhes do erro de provider.

​

Guias relacionados

• Erros e retentativas
• i18n de templates
• Introducao de webhooks