Envie as conversas do WhatsApp para o seu CRM automaticamente
Para enviar automaticamente as conversas do WhatsApp para um CRM, faça com que as mensagens recebidas sejam entregues como webhooks assinados ao seu backend ou a uma ferramenta de fluxos de trabalho, encontre ou crie o contacto pelo número de telefone e registe a mensagem como uma atividade nesse contacto. Use o id da mensagem do WhatsApp como chave única da atividade, para que uma entrega repetida atualize o mesmo registo em vez de criar um segundo.
A easyCoexistence liga o número do WhatsApp Business que mantém na app à Cloud API da Meta através da Coexistência.
Cabeçalho num POST reencaminhado com o id da entrega, idêntico em cada nova tentativa dessa entrega.
Intervalo das 7 tentativas de reencaminhamento, após cerca de 1, 5, 30, 120, 360 e 1,440 minutos.
Um passo Call my webhook chama o seu URL uma vez; um tempo limite ou erro falha a execução e envia-lhe um email.
ID de utilizador com âmbito do negócio, como US.13491208655302741918, enviado em user_id e from_user_id ao lado ou em vez do número de telefone.
Durante quanto tempo o registo de execução da automação guarda a mensagem que a acionou, a resposta e cada passo.
Que eventos devem chegar ao CRM?
Três tipos de mensagem compõem uma conversa num número em Coexistência, e duas vias transportam-nas. O Forward URL, definido por número, envia o que os clientes escrevem e o que a sua equipa escreve na app WhatsApp Business, como eventos originais da Meta, com novas tentativas até o CRM responder. As respostas enviadas por automatizações chegam à Meta através da API, que as reporta apenas como estados de entrega, sem texto; para registar as palavras, termine a automatização com um passo Call my webhook, cujo histórico inclui a resposta que a execução acabou de enviar. Um só endpoint pode receber ambos: o cabeçalho X-EC-Event indica automation.step para o passo e o nome do campo da Meta para os reencaminhamentos.
Como associar um remetente do WhatsApp a um contacto do CRM?
Pelo número de telefone, normalizado. O WhatsApp envia dígitos com o indicativo do país e sem sinal de mais, como 5511987654321, em messages[].from nos reencaminhamentos e em contact.wa_id no passo do webhook. Os registos do CRM introduzidos por pessoas trazem +55 11 98765-4321 ou (11) 98765-4321; por isso, mantenha uma propriedade dedicada com a forma apenas de dígitos e pesquise por ela. Quando não houver correspondência, crie o contacto com o nome do perfil do WhatsApp e o número.
Guarde também o ID de utilizador com âmbito do negócio. Um utilizador com nome de utilizador do WhatsApp que não contactou o seu número há 30 dias pode chegar apenas com o BSUID em from_user_id e contacts[].user_id. Os reencaminhamentos trazem-no; o passo do webhook traz o número de telefone.
O que deve conter cada registo do CRM?
Um contacto com os identificadores, e uma atividade por mensagem com a direção, o texto, a hora e uma chave única. O mapa abaixo mostra onde está cada valor em cada via. As horas das mensagens nos reencaminhamentos são segundos Unix, dados pela Meta; o passo do webhook envia datas ISO. Os ficheiros multimédia chegam como tipo e id nos reencaminhamentos e como marcadores como [image] com a legenda no passo do webhook; por isso, registe uma etiqueta curta em vez de tentar guardar o ficheiro.
| 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 as repetições criem duplicados?
Responda depressa e depois use chave em tudo. Um reencaminhamento que não recebe um 2xx em 10 segundos é repetido com o mesmo id X-EC-Delivery, até 7 tentativas; por isso, uma chamada ao CRM que demore 12 segundos executa-se duas vezes, a menos que a atividade seja atualizada ou inserida pelo wamid. Responda primeiro com 200 e faça o trabalho no CRM numa fila ou num processo em segundo plano.
O passo do webhook não é repetido, e as entregas repetidas da própria Meta são filtradas antes de a automatização correr; por isso, chama-o no máximo uma vez por mensagem. As entradas do histórico não trazem id de mensagem: identifique as respostas automáticas pelo run_id mais a posição. Os testes feitos em Try it chegam com dry_run true e o contacto de exemplo 15550000000; ignore-os, para que os testes nunca criem registos no CRM.
Como é o recetor em Node.js?
Uma rota Express recebe os dois tipos de evento. Lê o corpo em bruto, escolhe o segredo pelo cabeçalho X-EC-Event, verifica o X-EC-Signature, responde 200 de imediato e entrega o trabalho a uma função em segundo plano. O objeto crm representa o cliente da API do seu CRM: um upsert do contacto pelo telefone apenas com dígitos e um upsert da atividade pela sua chave única. A mesma forma funciona num fluxo de trabalho n8n, com um nó Code para a assinatura e os nós do seu CRM a seguir.
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);Pode o CRM atualizar o lead com o que a IA aprendeu?
Sim, no seu fluxo de trabalho. O chat que chega com um passo Call my webhook contém as perguntas que a sua IA fez e as respostas do cliente; assim, um nó de modelo no n8n ou uma chamada no seu backend pode extrair necessidade, orçamento, prazo ou localização, escrevê-los nos campos do lead e depois mudar a sua fase. Não devolva qualquer resposta, já que o cliente já tem a mensagem da IA. Quando o fluxo decidir que um lead merece uma chamada, pode criar uma tarefa para um vendedor ou alertar a equipa. Ou deixe o easyCoexistence fazer a extração: um agente ou um passo AI saves details escreve necessidade, orçamento e prazo nos campos do contacto, e um passo Call an API pode enviá-los para o seu CRM com tokens do estilo {{contact.budget}} no corpo. A página de qualificação de leads tem as instruções da entrevista e o payload dessa 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
- Pesquisar no CRM pelo campo de telefone em texto livre. O formato só com dígitos do WhatsApp raramente coincide com o que uma pessoa escreveu, e cada falha cria um contacto duplicado; pesquise por uma propriedade normalizada só com dígitos.
- Chamar o CRM antes de responder ao reencaminhamento. Um CRM que demore mais de 10 segundos faz com que a easyCoexistence repita a entrega e, sem um upsert pelo wamid, a atividade fica registada duas vezes.
- Registar apenas o reencaminhamento e esperar que as respostas automáticas constem nele. Os envios pela API voltam como estados, sem texto; um passo Call my webhook após a resposta traz as palavras.
- Deixar que os testes cheguem ao CRM. O Try it chama de facto o seu URL com dry_run true e o contacto de exemplo 15550000000; elimine esses eventos antes de qualquer upsert.
O seu Forward URL transmite as mensagens dos clientes e as respostas por telefone ao CRM como eventos originais da Meta, assinados por número e repetidos durante cerca de 33 horas quando o CRM está em baixo, e um passo Call my webhook acrescenta as respostas automáticas. O reencaminhamento e as automatizações estão incluídos no plano. A partir de US$ 9 por número ligado por mês, descendo até US$ 0.75 à medida que acrescenta números, com os primeiros 3 dias grátis.
Perguntas frequentes
Com que CRMs funciona isto?
Com qualquer CRM que tenha API, seja através do seu próprio backend, seja através de uma ferramenta de fluxos de trabalho como n8n, Make ou Zapier que tenha nós para isso. A HubSpot tem um objeto Communications com um tipo de canal WhatsApp criado para registar estas mensagens; a página da HubSpot mostra a chamada.
A sua equipa pode responder aos clientes a partir do CRM?
Só se o CRM enviar pela Cloud API da Meta, com o endpoint de envio do número e o token obtido em get_api_credentials: texto livre dentro de 24 horas após a última mensagem do cliente, e um template aprovado depois disso. Essas mensagens também aparecem na conversa da app no telemóvel.
É possível carregar conversas antigas no CRM?
Só através da importação do histórico da Meta, que envia até 6 meses de conversas individuais para um destino webhook direto guardado nas 24 horas após a ligação, uma vez por ligação. Um número configurado como Through easyCoexistence regista a partir do momento em que o reencaminhamento começa.
Que dados guarda a easyCoexistence pelo caminho?
As alterações reencaminhadas ficam em fila para novas tentativas e são removidas após 7 dias. Num número que passa pelo easyCoexistence, o texto das mensagens também fica para Conversations e para o contexto da IA durante o tempo que escolher, 30, 90 ou 365 dias, e os registos de execução são mantidos durante 30 dias. O registo permanente fica no CRM.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em