O registro automático de atendimentos do WhatsApp no CRM começa no webhook da WhatsApp Business Platform: quando o cliente escreve, a Meta envia uma requisição HTTP com um payload JSON para o servidor que você indicou, e um processo interno converte esse payload em contato, atividade e histórico no CRM, sem digitação manual. O registro automático fica confiável quando o sistema trata reentregas, usa o número do cliente como chave única e guarda o identificador de cada mensagem recebida. Este guia mostra os campos que chegam, a fila de gravação recomendada e o custo por mensagem no Brasil.
O que o webhook entrega
A plataforma usa webhooks para avisar o seu servidor sobre mensagens recebidas, status das mensagens enviadas e outros eventos da conta. Cada aviso de mensagem chega com o número do cliente (wa_id), o nome do perfil, o identificador único e o carimbo de tempo de cada mensagem — é daí que sai o conteúdo do registro no CRM. O payload pode chegar com até 3 MB, o que cobre mensagens longas, mas exige que o seu endpoint responda rápido e grave o conteúdo bruto para processar depois.
Para quem ainda não opera na plataforma oficial, os requisitos de verificação e a estrutura de cobrança por conversa estão no guia sobre a API do WhatsApp no Brasil.
Campos mínimos do registro
Nem tudo do payload precisa ir para o CRM. A tabela abaixo reúne o conjunto mínimo que sustenta um atendimento rastreável:
| Campo | Origem no payload | Uso no CRM |
|---|---|---|
| Número do cliente | contacts.wa_id | Chave para buscar ou criar o contato sem duplicar |
| Nome do perfil | contacts.profile.name | Preenche o cadastro quando o contato é novo |
| ID da mensagem | messages.id | Idempotência: impede registrar a mesma mensagem duas vezes |
| Data e hora | messages.timestamp | Data da atividade e do histórico |
| Tipo e conteúdo | messages.type, text.body | Resumo da conversa no cartão do cliente |
| Número da empresa | metadata.phone_number_id | Separa registros quando há mais de um número em operação |
Fila de atualização do CRM
Gravar direto dentro do handler do webhook é o erro mais comum. O caminho estável passa por uma fila de processamento:
- Assine o campo de webhooks de mensagens na configuração do aplicativo.
- Responda 200 imediatamente e salve o payload bruto no seu armazenamento.
- Coloque o evento em uma fila consumida por um trabalhador separado.
- Busque o contato pelo wa_id; se não existir, crie com o nome do perfil.
- Crie a atividade de atendimento com data, tipo e resumo do conteúdo.
- Grave o ID da mensagem antes de confirmar o processamento, para não repetir o registro em reentregas.
- Monitore a fila: eventos que falham ficam retidos e precisam de reprocessamento manual.
Do lado do CRM, as APIs públicas seguem padrões que facilitam esse fluxo. A API do Pipedrive é REST, devolve JSON e valida cada requisição por um token de acesso; a do HubSpot usa endpoints versionados por data, como /crm/objects/2026-09/contacts, o que obriga a fixar a versão usada pela integração. Ambas permitem criar e atualizar contatos e atividades por requisição, que é tudo o que a fila precisa. Em picos de demanda, como um plano de vendas de Black Friday no WhatsApp, a fila evita perder registros quando o volume de mensagens sobe de uma hora para outra.
Custo por mensagem registrada
O registro em si não tem cobrança separada: o que a Meta cobra é a mensagem entregue. Desde 1º de outubro de 2026, a Meta cobra por mensagem entregue as service messages, ou seja, as respostas enviadas dentro da janela de atendimento de 24 horas aberta pela mensagem do cliente. Para usuários no Brasil, a Meta publica taxa de entrega de 0.68 centavo de dólar por mensagem, com base na tarifa de utilidade e autenticação vigente desde 1º de julho de 2026. Mensagens de utilidade enviadas em resposta ao cliente dentro da janela também passam a ser cobradas na mesma data.
Em um cenário ilustrativo próprio — não é estatística de mercado —, uma operação que responde três mensagens por atendimento e faz mil atendimentos por mês paga pela entrega de três mil service messages. O valor exato sai da tarifa vigente na fatura da plataforma, então o acompanhamento do custo pertence ao relatório de analytics, não a estimativas fixas.
Erros comuns e como evitar
- Registrar duas vezes: se o seu endpoint não devolver 200, a Meta repete a entrega com frequência decrescente por até 7 dias — grave o ID da mensagem antes de confirmar o processamento.
- Telefone mal formatado: a documentação de mensagens da plataforma avisa que, no Brasil e no México, o prefixo extra do número pode ser modificado pela Cloud API; normalize o número antes de usá-lo como chave do contato.
- Aplicativo em modo de teste: alguns webhooks só são enviados com o aplicativo em modo de produção; validar apenas em ambiente de desenvolvimento esconde o problema até a go-live.
- Ignorar a janela de atendimento: a janela de 24 horas reinicia a cada mensagem do cliente; registrar a janela calculada no CRM ajuda a equipe a saber quando a resposta exige template aprovado.
