Notificações transacionais e alertas pelo WhatsApp
Avisos de conta, status de serviço e alertas do seu sistema pelo WhatsApp, com templates, clientRef e confirmação de entrega por webhook.
Atualizado em
Todo sistema gera avisos que alguém precisa ler: o serviço contratado ficou instável, a assinatura foi renovada, o limite do plano está perto do fim, o relatório do mês ficou pronto, a senha da conta foi alterada. Por e-mail, esses avisos chegam atrasados na leitura ou nem são abertos. No WhatsApp, o cliente vê a mensagem no mesmo lugar em que conversa com todo mundo.
Esta página mostra como usar a apiwpp para notificações transacionais: mensagens disparadas por um evento do seu sistema, para quem já é seu cliente e espera receber aquele aviso. E também o que ela não é: um canal de entrega com latência garantida.
Que avisos fazem sentido pelo WhatsApp
Notificação transacional é a mensagem que o cliente espera, porque ela é sobre algo que ele fez ou contratou. Alguns exemplos:
- Avisos de conta: cadastro aprovado, dados alterados, assinatura renovada, plano perto do limite, acesso novo à conta.
- Status de serviço: instabilidade, manutenção programada, serviço normalizado.
- Alertas de sistema: um monitoramento que o cliente configurou (estoque baixo, sensor fora da faixa, integração com erro).
- Andamento de um processo: documento pronto, solicitação aprovada, pedido enviado. Para lojas virtuais, veja o caso de e-commerce e o guia de notificações de pedido.
- Cobrança: vencimento, segunda via e confirmação de pagamento, tratados em cobrança e boletos.
O que não entra aqui: campanhas de marketing, promoções para listas frias e qualquer mensagem para quem não pediu para recebê-la. Além de gerar denúncias, isso vai contra o propósito da fila, que limita destinatários novos por dia justamente para impedir disparo em massa.
A fila e o scheduledAt: não é tempo real garantido
Esta é a parte mais importante do desenho. POST /connections/{id}/send não envia na hora: ele coloca a mensagem na fila do número e responde 202 imediatamente com três campos:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790600705000, "position": 1 }
scheduledAt é quando o envio está previsto (unix em milissegundos) e position é o lugar na fila. Com a fila vazia, a mensagem sai assim que o ritmo do número permite. Com a fila cheia, ela espera a vez, porque cada número respeita limites que o protegem de bloqueio: no padrão, 3 mensagens por minuto, 60 por hora e 200 por dia, um intervalo aleatório de 3 a 8 segundos entre envios e pelo menos 30 segundos entre duas mensagens para o mesmo destinatário. Os detalhes estão em fila anti-bloqueio.
Por isso, não use a apiwpp para códigos de verificação (OTP), autenticação em dois fatores ou alertas de emergência, em que um atraso de minutos quebra o fluxo ou traz risco. A fila não garante tempo de entrega, e o próprio WhatsApp pode restringir um número a qualquer momento. Para esses casos, use um canal com garantia de entrega própria e deixe o WhatsApp como aviso complementar.
Três ferramentas ajudam a lidar com a fila:
- Leia o
scheduledAtda resposta. Se a previsão passou do prazo em que o aviso ainda faz sentido, o seu sistema decide o que fazer. - Consulte a fila com
GET /connections/{id}/queue: quantos envios aguardam, os limites atuais do número e quanto deles já foi usado no dia. - Cancele o que ficou velho com
DELETE /connections/{id}/queue/{jobId}. Se o serviço voltou ao normal antes de o aviso de instabilidade sair, cancele-o e mande só o "normalizado".
Templates e clientRef
Avisos transacionais se repetem com poucas variações, o caso ideal para templates com variáveis. Crie o template uma vez na conexão e envie pelo nome:
{
"to": "5511988887777",
"template": "manutencao_programada",
"variables": { "nome": "Carlos", "data": "12/10", "horario": "das 2h às 4h" },
"clientRef": "manutencao-2026-10-12-cliente-4410"
}
Se faltar uma variável, a API responde 400 com a lista em missingVariables e nada é enfileirado.
O clientRef é o identificador do aviso no seu sistema, com até 200 caracteres. Se o evento que gera a notificação for processado duas vezes (um retry do seu worker, um webhook de outro serviço que chegou repetido), a segunda requisição com o mesmo clientRef responde 200 com o job original e "duplicate": true, e o cliente recebe o aviso uma vez só. Monte o valor com o id do evento e do destinatário, como no exemplo. A reserva vale por 7 dias; veja idempotência com clientRef e o guia sobre mensagens duplicadas.
Monitorar a entrega por webhook
Depois do 202, o resultado de cada envio chega ao webhook do projeto, com o seu clientRef:
| Evento | O que diz |
|---|---|
message.delivery | O status mudou: sent, delivered, read ou failed, com o messageId do WhatsApp |
message.send_failed | O envio aceito não vai acontecer, com o motivo em reason |
message.outgoing | A mensagem saiu (opcional, ativado por projeto) |
Os motivos de message.send_failed são attempts_exhausted (as tentativas se esgotaram), lease_expired (o envio travou na última tentativa e pode ter saído mesmo assim), not_on_whatsapp (o número não está no WhatsApp) e reachout_timelocked (o WhatsApp colocou a conta num bloqueio temporário de novas conversas). Com esses eventos, o seu sistema marca o aviso como entregue ou lido e aciona outro canal, como o e-mail, quando o WhatsApp não vai entregar.
Vale monitorar também o próprio número. O evento connection.status avisa quando a conexão fecha, com o motivo e se a apiwpp vai reconectar sozinha (willReconnect). Se o número desconectar sem reconexão automática, os avisos param de sair, e alguém da sua equipe precisa saber na hora. Para acompanhar a plataforma, a página de status pública mostra a saúde de cada componente.
A entrega dos webhooks é at-least-once, com novas tentativas e registro no painel: processe cada evento de forma idempotente pelo messageId. A página de webhooks assinados explica a assinatura e as novas tentativas.
Boas práticas para avisos que o cliente quer ler
- Uma informação por mensagem, com o essencial na primeira linha.
- Agrupe avisos em sequência. Três alertas do mesmo cliente em um minuto viram uma mensagem com os três, até porque a fila espaça mensagens para o mesmo destinatário.
- Verifique os números no cadastro com
POST /connections/{id}/contacts/check, que confere até 100 números de uma vez e evita falhas pornot_on_whatsapp. Veja verificação de números. - Ofereça como desativar os avisos por WhatsApp nas preferências da conta, e respeite o pedido.
- Planeje o volume. Um aviso para toda a base de clientes esbarra no limite diário e no teto de 100 destinatários novos por 24 horas; escolha quem precisa mesmo receber.
Perguntas frequentes
A mensagem sai na hora em que eu chamo a API?
Não necessariamente. A API coloca a mensagem na fila do número e responde com o scheduledAt, a previsão de envio. Com a fila vazia, ela sai assim que o ritmo do número permite; com a fila cheia, espera a vez para respeitar os limites que protegem o número.
Posso usar a apiwpp para enviar códigos de verificação (OTP)?
Não recomendamos. A fila não garante tempo de entrega, e um código que chega minutos depois quebra o login. Use um canal com garantia de entrega para OTP e autenticação em dois fatores, e o WhatsApp para avisos que toleram espera.
Como sei se o cliente leu o aviso?
Pelo webhook message.delivery, que informa os status sent, delivered, read e failed com o seu clientRef. O status read depende de o destinatário não ter desativado a confirmação de leitura no WhatsApp.
O que acontece se o número de destino não tiver WhatsApp?
O envio falha na hora, sem novas tentativas. Se você mandou um clientRef, chega o evento message.sendfailed com reason: noton_whatsapp, e o seu sistema pode avisar por outro canal.
Outros casos de uso
Todos: Casos de uso →Envie o aviso de vencimento, a segunda via do boleto e a confirmação de pagamento a quem já é seu cliente, a partir do seu sistema financeiro, sem risco de mandar a mesma cobrança duas vezes.
Envie confirmação de pedido, boleto ou nota em PDF e código de rastreio no canal que o cliente lê, com templates, clientRef por pedido e status de entrega e leitura no webhook.
Cada mensagem que chega no número da empresa vira um evento no seu sistema: abra o ticket, distribua para a equipe e responda pela API, com texto, mídia, reações e o indicador de digitando.