Envie conversas do WhatsApp para o seu CRM automaticamente
Para enviar conversas do WhatsApp a um CRM automaticamente, faça as mensagens recebidas chegarem como webhooks assinados ao seu backend ou a uma ferramenta de automação de fluxos, encontre ou crie o contato pelo número de telefone e registre a mensagem como uma atividade nesse contato. Use o id da mensagem do WhatsApp como chave única da atividade, para que uma entrega repetida atualize o mesmo registro em vez de criar um segundo.
O easyCoexistence conecta o número do WhatsApp Business que você mantém no app à Cloud API da Meta por meio da Coexistência.
Cabeçalho de um POST encaminhado que traz o id da entrega, idêntico em cada repetição dessa entrega.
Período coberto pelas 7 tentativas de encaminhamento, feitas após cerca de 1, 5, 30, 120, 360 e 1.440 minutos.
Uma etapa Call my webhook chama sua URL uma vez; um timeout ou erro faz a execução falhar e você recebe um e-mail.
ID de usuário com escopo de negócio, como US.13491208655302741918, enviado em user_id e from_user_id junto com o número de telefone ou no lugar dele.
Por quanto tempo o log de execuções da automação guarda a mensagem que a disparou, a resposta e cada etapa.
Quais eventos devem chegar ao CRM?
Três tipos de mensagem formam uma conversa em um número com Coexistência, e duas rotas as transportam. A Forward URL, definida por número, envia o que os clientes escrevem e o que sua equipe digita no app do WhatsApp Business, como eventos originais da Meta, repetindo a entrega até que o seu CRM responda. As respostas enviadas por automações chegam à Meta pela API, que as informa apenas como status de entrega, sem o texto; para registrar o que foi dito, termine a automação com uma etapa Call my webhook, cujo histórico inclui a resposta que a execução acabou de enviar. Um único endpoint pode receber as duas rotas: o cabeçalho X-EC-Event traz automation.step para a etapa e o nome do campo da Meta para os encaminhamentos.
Como associar um remetente do WhatsApp a um contato do CRM?
Pelo número de telefone, normalizado. O WhatsApp envia só dígitos, com o código do país e sem o sinal de +, como 5511987654321, em messages[].from nos encaminhamentos e em contact.wa_id na etapa de webhook. Registros de CRM digitados por pessoas trazem +55 11 98765-4321 ou (11) 98765-4321, então mantenha uma propriedade dedicada com o número só em dígitos e faça a busca por ela. Quando nada corresponder, crie o contato com o nome do perfil do WhatsApp e o número.
Guarde também o ID de usuário com escopo de negócio. Um usuário com nome de usuário no WhatsApp que não fala com o seu número há 30 dias pode chegar apenas com o BSUID em from_user_id e contacts[].user_id. Os encaminhamentos trazem esse ID; a etapa de webhook traz o número de telefone.
O que cada registro do CRM deve conter?
Um contato com os identificadores e uma atividade por mensagem com direção, texto, horário e uma chave única. O mapa abaixo mostra onde fica cada valor em cada rota. Nos encaminhamentos, o horário das mensagens vem da Meta em segundos Unix; a etapa de webhook envia datas ISO. Mídias chegam como um tipo e um id nos encaminhamentos e, na etapa de webhook, como marcadores como [image] acompanhados da legenda, então registre um rótulo curto em vez de tentar armazenar o arquivo.
| Forwarded event (value is Meta's) | Call my webhook step | |
|---|---|---|
| Contact phone | messages[].from | contact.wa_id |
| Contact name | contacts[].profile.name | contact.name |
| BSUID | contacts[].user_id, messages[].from_user_id | Not sent |
| Activity text | text.body, or the media type | message.text and history[].text |
| Direction | messages = in, smb_message_echoes = out | history[].direction: in, out or echo |
| Time | timestamp, Unix seconds | message.at and history[].at, ISO 8601 |
| Unique key | messages[].id (wamid) | message.id; run_id for history entries |
Como evitar que repetições criem registros duplicados?
Responda rápido e use chave em tudo. Um encaminhamento que não recebe um 2xx em 10 segundos é repetido com o mesmo id X-EC-Delivery, em até 7 tentativas; por isso, uma chamada ao CRM que leva 12 segundos roda duas vezes, a menos que a atividade seja gravada com upsert pelo wamid. Responda 200 primeiro e faça o trabalho no CRM em uma fila ou job em segundo plano.
A etapa de webhook não é repetida, e as entregas repetidas da própria Meta são filtradas antes de a automação rodar, então ela chama sua URL no máximo uma vez por mensagem. As entradas do histórico não trazem id de mensagem: use como chave das respostas automáticas o run_id mais a posição de cada uma. Os testes feitos em Try it chegam com dry_run true e o contato de exemplo 15550000000; ignore-os para que testes nunca criem registros no CRM.
Como fica o receptor em Node.js?
Uma única rota Express recebe os dois tipos de evento. Ela lê o corpo bruto, escolhe o segredo pelo cabeçalho X-EC-Event, verifica o X-EC-Signature, responde 200 na hora e passa o trabalho para uma função em segundo plano. O objeto crm representa o cliente da API do seu CRM: um upsert do contato pelo telefone só com dígitos e um upsert da atividade pela chave única. A mesma estrutura funciona em um fluxo do n8n, com um nó Code para a assinatura e os nós do seu CRM depois dele.
import express from "express";
import crypto from "node:crypto";
const FORWARD_SECRET = process.env.EC_FORWARD_SECRET; // the number's, shown once with the Forward URL
const STEP_SECRET = process.env.EC_STEP_SECRET; // the automation's Signing secret
function signed(req, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get("X-EC-Signature") || "");
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
const mac = crypto.createHmac("sha256", secret).update(m[1] + "." + req.body).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
const app = express();
app.post("/whatsapp/crm", express.text({ type: "application/json" }), (req, res) => {
const kind = req.get("X-EC-Event"); // automation.step, or Meta's field name for a forward
if (!signed(req, kind === "automation.step" ? STEP_SECRET : FORWARD_SECRET)) return res.status(401).end();
res.json({}); // no reply field: nothing is sent to the customer
handle(kind, JSON.parse(req.body)).catch(console.error);
});
async function handle(kind, body) {
if (kind === "messages") {
for (const m of body.value.messages ?? []) { // statuses are skipped
const c = (body.value.contacts ?? []).find((x) => x.wa_id === m.from);
const contact = await crm.upsertContact({ phone: m.from, bsuid: m.from_user_id, name: c?.profile?.name });
await crm.upsertActivity({ key: m.id, contact, direction: "in", text: m.text?.body ?? "[" + m.type + "]", at: new Date(m.timestamp * 1000) });
}
} else if (kind === "smb_message_echoes") {
for (const m of body.value.message_echoes ?? []) {
const contact = await crm.upsertContact({ phone: m.to, bsuid: m.to_user_id });
await crm.upsertActivity({ key: m.id, contact, direction: "out", text: m.text?.body ?? "[" + m.type + "]", at: new Date(m.timestamp * 1000) });
}
} else if (kind === "automation.step" && !body.dry_run) {
const contact = await crm.upsertContact({ phone: body.contact.wa_id, name: body.contact.name });
const sentAfter = body.history.filter((h) => h.direction === "out" && h.at >= body.message.at);
for (const [i, h] of sentAfter.entries()) {
await crm.upsertActivity({ key: body.run_id + ":" + i, contact, direction: "out", text: h.text, at: new Date(h.at) });
}
}
}
app.listen(3000);O CRM pode atualizar o lead com o que a IA descobriu?
Sim, no seu fluxo. A conversa que chega com uma etapa Call my webhook traz as perguntas que sua IA fez e as respostas do cliente, então um nó de modelo no n8n ou uma chamada no seu backend pode extrair necessidade, orçamento, prazo ou localização, gravar esses dados nos campos do lead e depois mudar o estágio dele. Não retorne nenhuma resposta, já que o cliente já recebeu a mensagem da IA. Quando o fluxo decidir que um lead merece uma ligação, ele pode criar uma tarefa para um vendedor ou alertar a equipe. Ou deixe o easyCoexistence fazer a extração: um agente ou uma etapa AI saves details grava necessidade, orçamento e prazo nos campos do contato, e uma etapa Call an API pode enviá-los ao seu CRM com tokens no estilo {{contact.budget}} no corpo. A página de qualificação de leads tem as instruções da entrevista e o payload para essa configuração.
Como configurar
- Send the number's messages through easyCoexistenceOn the number's page, the Where incoming messages go card must be set to Through easyCoexistence; choose it if it shows Straight to your system.
- Deploy the receiverPublish the endpoint or n8n workflow on public HTTPS, with the CRM upserts keyed on the phone and the message id.
- Save the Forward URLPaste the receiver's URL into Forward URL (optional), click Save forward URL and store the signing secret shown once.
- Log automated repliesIn each automation that replies, add Call my webhook as the last step with the same URL, save, and copy that automation's Signing secret.
- Check one real conversationWrite to the number from another phone, let the automation answer, reply from the app, and confirm three activities on the contact: in, automated out and phone out.
Erros comuns
- Buscar no CRM pelo campo de telefone em texto livre. O formato só com dígitos do WhatsApp raramente bate com o que a pessoa digitou, e cada falha cria um contato duplicado; busque por uma propriedade normalizada só com dígitos.
- Chamar o CRM antes de responder ao encaminhamento. Um CRM que leva mais de 10 segundos faz o easyCoexistence repetir a entrega, e sem upsert pelo wamid a atividade é registrada duas vezes.
- Registrar só o encaminhamento e esperar encontrar nele as respostas automáticas. Envios pela API voltam como status, sem o texto; uma etapa Call my webhook depois da resposta traz o que foi dito.
- Deixar os testes chegarem ao CRM. O Try it chama de verdade a sua URL com dry_run true e o contato de exemplo 15550000000; descarte esses eventos antes de qualquer upsert.
A Forward URL repassa ao seu CRM as mensagens dos clientes e as respostas enviadas pelo celular como eventos originais da Meta, assinados por número e repetidos por cerca de 33 horas quando o CRM está fora do ar, e uma etapa Call my webhook acrescenta as respostas automáticas. Encaminhamentos e automações estão incluídos no plano. De R$ 29,90 até R$ 3,90 por número por mês, com o valor caindo conforme você adiciona números, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Com quais CRMs isso funciona?
Com qualquer CRM que tenha API, seja pelo seu próprio backend, seja por uma ferramenta de automação como n8n, Make ou Zapier que tenha nós para ele. O HubSpot tem um objeto Communications com um tipo de canal WhatsApp feito para registrar essas mensagens; a página do HubSpot mostra a chamada.
Minha equipe pode responder aos clientes pelo CRM?
Somente se o CRM enviar pela Cloud API da Meta, usando o endpoint de envio e o token do número obtidos em get_api_credentials: texto livre dentro de 24 horas após a última mensagem do cliente e, depois disso, um template aprovado. Essas mensagens também aparecem na conversa do app no celular.
Dá para importar conversas antigas para o CRM?
Somente pela importação de histórico da Meta, que envia até 6 meses de conversas individuais para um destino de webhook direto salvo em até 24 horas após a conexão, uma única vez por conexão. Um número configurado como Through easyCoexistence registra a partir do momento em que o encaminhamento começa.
O que o easyCoexistence guarda no caminho?
As alterações encaminhadas ficam em fila para novas tentativas e são removidas após 7 dias. Em um número que passa pelo easyCoexistence, o texto das mensagens também fica guardado para Conversations e para o contexto da IA pelo tempo que você escolher, 30, 90 ou 365 dias, e os logs de execução ficam guardados por 30 dias. O registro permanente fica no CRM.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em