WhatsApp API oficial: notificações integradas ao sistema

Quando se fala em WhatsApp na empresa, a conversa vai direto para chatbot. Mas boa parte do valor está num lugar menos vistoso: a mensagem que o seu sistema manda sozinho, na hora certa, porque algo aconteceu. Pedido faturado, entrega a caminho, consulta amanhã, boleto vencendo, senha redefinida.

Essas mensagens são curtas, previsíveis e úteis para o cliente. Ainda assim, muita empresa as envia por e-mail que ninguém abre, por SMS genérico ou, pior, pelo celular de um funcionário. Este texto mostra como integrar a API oficial do WhatsApp ao seu sistema para esse tipo de envio, e onde estão as regras que derrubam projetos feitos às pressas.

Mensagem transacional: o caso de uso mais subestimado

Mensagem transacional é aquela disparada por um evento do sistema, não por uma campanha. Ela existe porque o cliente fez alguma coisa ou porque algo mudou no que ele contratou. Alguns exemplos:

• Pedido e entrega: pedido recebido, pagamento aprovado, nota emitida, saiu para entrega, entregue.
• Agenda: confirmação de horário, lembrete na véspera, aviso de remarcação.
• Financeiro: fatura disponível, vencimento próximo, pagamento identificado.
• Conta e acesso: código de verificação, alteração de cadastro, novo dispositivo.
• Serviço: técnico a caminho, ordem de serviço concluída, laudo disponível.

O que essas mensagens têm em comum é que o cliente espera recebê-las. Isso muda tudo: a taxa de leitura tende a ser alta, a chance de denúncia é baixa e cada mensagem economiza uma ligação ao seu atendimento perguntando "e o meu pedido?".

A parte conversacional, com IA ou atendentes, é outro projeto, com outras decisões. Tratamos dela em atendimento no WhatsApp com IA. Aqui o foco é o sistema falando primeiro.

API oficial ou solução não oficial: o risco do número bloqueado

Existem ferramentas que automatizam o WhatsApp simulando um navegador ou um aparelho conectado ao WhatsApp Web. Elas são baratas de começar e funcionam no primeiro dia. O problema aparece depois.

Elas violam os termos de uso do WhatsApp. A plataforma detecta padrões de automação e bloqueia números. Quando isso acontece, você perde o número que o cliente já conhece, o histórico de conversas e o canal inteiro, de uma vez, sem aviso e sem a quem recorrer.

Elas são tecnicamente frágeis. Qualquer mudança no aplicativo pode quebrar a automação. A sessão cai, alguém precisa escanear o QR code de novo, e as mensagens da madrugada não saíram.

Elas não dão garantia sobre o dado. A conversa passa por uma sessão de navegador num servidor que você não controla bem. Para quem trata dado pessoal sob a LGPD, isso é difícil de justificar.

A alternativa é a WhatsApp Business Platform, a API oficial da Meta. O acesso é feito diretamente pela Cloud API, hospedada pela própria Meta, ou por meio de um provedor parceiro (BSP), que costuma oferecer painel, suporte e ferramentas adicionais. Nos dois casos, o número é verificado, vinculado a uma conta comercial, e as regras são públicas. Existe custo por mensagem conforme a categoria, e ele deve entrar na conta desde o início.

Modelos de mensagem, categorias e aprovação

Na API oficial, toda mensagem que a empresa envia fora de uma conversa aberta pelo cliente precisa usar um modelo pré-aprovado (template). O modelo tem texto fixo e variáveis:

Olá, {{1}}. Seu pedido {{2}} saiu para entrega e deve chegar hoje. Acompanhe pelo link abaixo.

O modelo é submetido à Meta, classificado numa categoria e aprovado ou recusado. As categorias atuais são:

• Utilidade: mensagens ligadas a uma transação ou conta existente, como confirmação, atualização de pedido e aviso de cobrança.
• Autenticação: códigos de verificação de uso único.
• Marketing: promoções, ofertas, novidades e qualquer coisa que tente vender.

A categoria afeta custo e regras de envio, e a Meta pode reclassificar um modelo se o conteúdo não corresponder à categoria declarada. Um aviso de pedido com um cupom para a próxima compra no final deixa de ser utilidade.

Na prática, isso pede algumas decisões de projeto:

• Um catálogo de modelos versionado dentro do seu sistema, com o nome e o idioma de cada modelo e o mapeamento das variáveis para campos do sistema.
• Botões e links planejados desde o início: "Confirmar", "Remarcar", "Ver pedido". Botões de resposta rápida viram eventos que o sistema pode tratar.
• Um fluxo interno para criar e revisar modelos, porque a aprovação leva algum tempo e texto mal redigido volta recusado.
• Fallback para quando o modelo for pausado ou desativado por baixa qualidade: o sistema precisa saber disso e usar outro canal.

Janela de atendimento e mensagens iniciadas pela empresa

A outra regra central é a janela de atendimento de 24 horas. Quando o cliente manda uma mensagem, abre-se uma janela em que a empresa pode responder com texto livre, sem modelo. Fechada a janela, só modelos aprovados.

Para mensagens transacionais, isso tem duas consequências práticas:

O sistema deve assumir que a janela está fechada. O aviso de "saiu para entrega" quase sempre chega dias depois da última interação do cliente. Então ele é um modelo, sempre.

A resposta do cliente abre uma janela. Se ele responde "posso receber só à tarde?", essa mensagem precisa ir para algum lugar: uma fila de atendimento humano, um fluxo automatizado ou, no mínimo, uma resposta dizendo onde ele deve falar. Enviar notificação num número que ninguém lê é pior do que não enviar.

Decida antes do lançamento quem responde o que chega nesse número. Muitas empresas usam números separados para notificações e para atendimento, com a mensagem transacional indicando o canal certo.

Opt-in e preferências de contato do cliente

A política da plataforma exige que a empresa tenha consentimento do cliente para contatá-lo pelo WhatsApp, e a LGPD exige base legal e transparência sobre o uso do telefone. Isso não é burocracia de rodapé; é dado que o sistema precisa guardar e consultar:

• Quando e onde o cliente autorizou: no cadastro, no checkout, no balcão, num formulário.
• Para quê ele autorizou: avisos de pedido, lembretes, ofertas. Aceitar notificação de entrega não é aceitar marketing.
• Como ele sai: responder "parar" ou mudar a preferência na área do cliente precisa refletir imediatamente nos envios.

O modelo de dados fica simples quando é pensado desde o começo: uma tabela de preferências por cliente, canal e finalidade, com histórico de alterações. O disparador consulta essa tabela antes de cada envio. Os cuidados mais amplos com dado pessoal estão em LGPD no desenvolvimento de sistemas.

A qualidade do número também depende disso. Clientes que bloqueiam ou denunciam a conta derrubam a classificação de qualidade, e a plataforma pode limitar a quantidade de conversas que você inicia por dia. Mandar só o que o cliente espera é a melhor forma de manter o canal saudável.

Webhooks de status: enviado, entregue, lido e falhou

Quando o sistema chama a API para enviar uma mensagem, a resposta só diz que o pedido foi aceito. O que acontece depois chega por webhook: a plataforma chama um endereço seu a cada mudança de status.

• Enviado: a mensagem saiu da plataforma.
• Entregue: chegou ao aparelho do cliente.
• Lido: o cliente abriu, quando ele não desativou a confirmação de leitura.
• Falhou: não foi possível entregar, com um código de erro que explica o motivo.

O mesmo webhook traz as mensagens recebidas e os cliques em botões de resposta rápida.

O endpoint que recebe esses eventos precisa de alguns cuidados:

• Validar a assinatura de cada chamada, para garantir que ela veio da plataforma.
• Responder rápido e processar depois. Grave o evento numa fila e devolva sucesso; o processamento pesado acontece em segundo plano.
• Ser idempotente. O mesmo evento pode chegar mais de uma vez, e eventos podem chegar fora de ordem. Um "entregue" que chega depois de "lido" não pode rebaixar o status.
• Guardar os códigos de falha. Número inválido, cliente sem WhatsApp, modelo pausado e limite atingido pedem ações diferentes.

Com esses dados, a mensagem deixa de ser "disparada e esquecida". O sistema sabe que o lembrete da consulta não foi entregue e pode tentar SMS ou e-mail, ou avisar a recepção para ligar.

Integrando o disparo aos eventos do seu sistema

O erro de arquitetura mais comum é chamar a API do WhatsApp dentro da tela ou da transação que gerou o evento. O usuário clica em "faturar", o sistema tenta enviar a mensagem, a API demora, e o faturamento fica esperando ou falha por causa de uma notificação.

O desenho que funciona separa as responsabilidades:

1. O sistema registra o evento. "Pedido 4821 faturado" é gravado na mesma transação que muda o status do pedido.
2. Um serviço de notificações consome os eventos. Ele decide se deve notificar, consulta as preferências do cliente, escolhe o modelo e monta as variáveis.
3. O envio passa por uma fila, com retentativa, controle de ritmo e uma chave única por evento e destinatário, para que uma falha de rede não gere mensagem duplicada.
4. O status volta pelo webhook e é gravado junto do evento original.
5. Um painel mostra o que saiu, o que falhou e por quê, para que o suporte responda "a mensagem foi entregue ontem às 14h" em vez de "o sistema manda automático".

Esse serviço de notificações costuma virar o lugar central para todos os canais: WhatsApp, e-mail, SMS e push no app. A regra de negócio ("avisar quando o pedido sair para entrega") fica num lugar só, e o canal vira detalhe de configuração.

Alguns fluxos se beneficiam muito desse desenho. No agendamento, a confirmação com botões reduz a incerteza sobre quem vem; o desenho completo está em sistema de agendamento online. Na cobrança, o aviso de fatura com o link de pagamento entra na régua junto com os outros meios, como mostramos em cobrança recorrente com Pix Automático.

Erros comuns

• Começar pelo número pessoal ou por automação não oficial e descobrir o bloqueio quando o volume cresce.
• Misturar marketing em modelo de utilidade, o que leva a reclassificação e perda de qualidade.
• Não tratar as respostas, deixando o cliente falar sozinho com um número que só envia.
• Disparar dentro da transação, acoplando uma operação crítica a uma API externa.
• Ignorar os webhooks de falha e presumir que tudo foi entregue.
• Enviar tudo: cinco mensagens para um pedido simples cansam o cliente e aumentam o custo.

Como medir se valeu a pena

Meça antes de ligar e compare depois, sempre com seus próprios números:

• Taxa de entrega e de leitura por modelo.
• Volume de contatos ao atendimento sobre status de pedido, horário ou segunda via.
• Ações feitas pela mensagem: confirmações, remarcações, pagamentos pelo link.
• Bloqueios e descadastros por modelo, como sinal de mensagem indesejada.
• Falhas por motivo, para limpar cadastro e ajustar modelos.

Checklist antes do primeiro envio

• Conta comercial verificada e número dedicado registrado na plataforma.
• Lista de eventos que geram mensagem, com o modelo e a categoria de cada um.
• Modelos aprovados, com variáveis mapeadas e botões definidos.
• Consentimento registrado por finalidade, com forma simples de sair.
• Destino definido para as respostas dos clientes.
• Serviço de notificações com fila, idempotência e retentativa.
• Webhook com validação de assinatura e tratamento de falhas.
• Painel de envios acessível ao atendimento.

Notificações sob medida, pelo canal oficial

A Pervian Tech integra a WhatsApp Business Platform ao sistema que você já usa, ou a uma plataforma nova de desenvolvimento web, com serviço de notificações, catálogo de modelos, preferências de contato e rastreio de status. Cada integração é sob medida, porque os eventos, as regras e os sistemas de origem mudam de empresa para empresa.

O trabalho começa por um diagnóstico inicial gratuito dos seus fluxos e sistemas. O investimento é definido sob consulta a partir dele, junto com as fases do projeto. Se o seu cliente ainda liga para saber onde está o pedido, conte como funciona hoje.