Notificações transacionais pela API de WhatsApp

Transacional não é campanha

A diferença não é o texto, é o gatilho. Uma campanha é decidida por uma pessoa e vai para uma lista. Uma notificação transacional é decidida pelo sistema, vai para uma pessoa e só existe porque algo aconteceu com ela. Exemplos típicos:

• Pedido recebido, pagamento aprovado ou recusado, nota fiscal emitida.
• Redefinição de senha, novo acesso à conta, alteração de e-mail.
• Mudança de status em chamado, proposta, processo ou entrega.
• Vencimento de plano, cartão expirando, limite de uso atingido.

Como o cliente espera esses avisos, a taxa de leitura no WhatsApp tende a ser alta e o risco de denúncia, baixo. Por outro lado, a tolerância a erro também é baixa: aviso de pagamento que chega duas vezes gera chamado, e aviso que não chega gera desconfiança. O desenho técnico existe para evitar esses dois casos.

A arquitetura que aguenta volume

O erro mais comum é chamar a API de WhatsApp dentro do request que processa o pagamento. Se a chamada demorar, o checkout demora. Se falhar, o pagamento fica num estado estranho. O fluxo recomendado separa as responsabilidades:

1. O domínio publica um evento, por exemplo pagamento.aprovado, e segue a vida. Nada de WhatsApp aqui.
2. Um consumidor lê o evento da fila, monta a mensagem a partir de um modelo e calcula a chave de idempotência.
3. O worker envia para a D-API com async: true. A API responde na hora com um commandId e executa o envio em segundo plano.
4. O resultado chega no webhook command.result. O worker grava o commandId junto da notificação e o webhook atualiza o registro.
5. Entrega e leitura chegam depois, pelos eventos message.delivered e message.read, se você quiser exibir isso no painel.

A chamada do worker fica assim:

curl -X POST https://api.d-api.cloud/api/v1/messages/send/text \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "loja-notificacoes",
    "to": "5511999999999",
    "text": "Pagamento aprovado. Seu pedido 48213 já está em separação.",
    "async": true
  }'

Se o seu sistema preferir consultar em vez de esperar o evento, o resultado também fica disponível em GET /api/v1/commands/{commandId} por cerca de uma hora. Para entrega garantida, a própria documentação recomenda o webhook. Quem já usa RabbitMQ pode receber os eventos direto numa fila, configurada por sessão.

Idempotência: a notificação que não pode chegar duas vezes

Filas entregam pelo menos uma vez, não exatamente uma vez. Um worker que cai depois de enviar e antes de confirmar vai reprocessar a mesma mensagem. A proteção é do seu lado, e é simples:

• Chave derivada do evento, não do horário. Algo como pedido:48213:pago. O mesmo evento sempre gera a mesma chave.
• Restrição de unicidade no banco. Grave a chave numa tabela de notificações com índice único antes de chamar a API. Se a gravação falhar por duplicidade, o envio já aconteceu ou está em curso.
• Estado explícito. pendente, enviado com o commandId, confirmado ou falhou. Retentativa só para o que está em falhou, com intervalo crescente e limite de tentativas.
• Webhook também é idempotente. A D-API reenvia um webhook até 7 vezes se o seu servidor não responder, e deduplica eventos numa janela curta. Seu handler deve aceitar o mesmo evento repetido sem efeito colateral.

Os detalhes de formato e reenvio dos eventos estão em webhook de WhatsApp.

API oficial ou não oficial para notificações

Os dois caminhos funcionam para transacional, com regras diferentes. Na D-API eles usam a mesma integração, então a escolha pode ser revista sem reescrever o worker.

No template oficial, as partes variáveis vão em bodyVariables, e o nome e o idioma do template são obrigatórios. Para aprofundar a escolha, veja API oficial vs não oficial e a página da API oficial de WhatsApp.

Boas práticas de conteúdo

• Identifique a empresa na primeira linha. O cliente precisa saber quem fala antes de ler o resto.
• Uma notificação, um assunto. Não aproveite aviso de pagamento para oferecer produto.
• Inclua o identificador que o cliente reconhece: número do pedido, protocolo, final do cartão.
• Agrupe eventos próximos. Três mudanças de status em dois minutos viram uma mensagem só.
• Respeite horário. Aviso que não é urgente pode esperar a manhã seguinte.

Dois casos específicos têm guias próprios: código de verificação e rastreio de pedidos. Se as notificações vão sair de sistemas internos como ERP ou monitoramento, veja também API de WhatsApp para operação interna. O trial de 3 dias dá para montar o fluxo completo, do evento ao webhook de confirmação.