Pular para o conteúdo
apiwpp
Caso de uso

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:

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:

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:

EventoO que diz
message.deliveryO status mudou: sent, delivered, read ou failed, com o messageId do WhatsApp
message.send_failedO envio aceito não vai acontecer, com o motivo em reason
message.outgoingA 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

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.