自动将 WhatsApp 对话发送到您的 CRM
要自动将 WhatsApp 对话发送到 CRM,请把收到的消息以已签名的 Webhook 形式投递到您的后端或工作流工具,按电话号码查找或创建联系人,并将该消息作为活动记录记在该联系人下。把 WhatsApp 消息 ID 用作活动记录的唯一键,这样重试的投递会更新同一条记录,而不会新建第二条。
easyCoexistence 通过 Coexistence 将您在应用中保留的 WhatsApp Business 号码连接到 Meta 的 Cloud API。
转发的 POST 请求的请求头中包含投递 ID,同一投递的每次重试,该 ID 都相同。
7 次转发尝试的时间跨度,分别约在 1、5、30、120、360 和 1,440 分钟后进行。
Call my webhook 步骤只会调用您的 URL 一次;超时或出错会使本次运行失败,并向您发送电子邮件。
业务范围用户 ID(BSUID),例如 US.13491208655302741918,可与电话号码一同或代替电话号码,通过 user_id 和 from_user_id 发送。
自动化运行日志中触发消息、回复和各步骤的保留时长。
哪些事件应该发送到 CRM?
在 Coexistence 号码上,一段对话由三类消息组成,并通过两条路径传送。按号码设置的 Forward URL 会发送客户的来信,以及您的团队在 WhatsApp Business 应用中输入的消息,这些都以 Meta 的原始事件形式传送,并在 CRM 响应之前持续重试。自动化发出的回复通过 API 到达 Meta,只以投递状态的形式回报,不含文本;如要记录其内容,请在自动化末尾加一个 Call my webhook 步骤,其历史记录中包含本次运行刚发送的回复。一个端点可以同时接收两者:X-EC-Event 请求头在步骤事件中为 automation.step,在转发事件中则为 Meta 的字段名。
如何将 WhatsApp 发送方与 CRM 联系人匹配?
按电话号码,并经过标准化处理。WhatsApp 发送的是带国家代码、不带加号的数字,例如 5511987654321;转发时位于 messages[].from,Webhook 步骤中位于 contact.wa_id。由人工录入的 CRM 记录通常是 +55 11 98765-4321 或 (11) 98765-4321,因此请保留一个专用属性,存放纯数字形式,并以该属性进行搜索。没有匹配项时,则用 WhatsApp 个人资料名称和号码创建联系人。
也要保存业务范围用户 ID。一位拥有 WhatsApp 用户名、且在 30 天内未与您的号码联系过的用户,可能只携带 BSUID,出现在 from_user_id 和 contacts[].user_id 中。转发中会带有该 ID;Webhook 步骤则携带电话号码。
每条 CRM 记录应包含哪些内容?
一个联系人,包含各项标识符;以及每条消息一条活动记录,包含方向、文本、时间和唯一键。下图展示了每个值在两条路径中的位置。转发中的消息时间是 Meta 提供的 Unix 秒数;Webhook 步骤发送的则是 ISO 日期。媒体在转发中以类型和 ID 的形式到达,在 Webhook 步骤中则以 [image] 等占位符加上说明文字的形式出现,因此请记录一个简短标签,而不必尝试存储文件。
| 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 |
如何防止重试产生重复记录?
快速应答,然后为所有记录设置键。转发请求若在 10 秒内没有收到 2xx 响应,就会以相同的 X-EC-Delivery ID 重试,最多 7 次;因此,若 CRM 调用耗时 12 秒,就会执行两次,除非活动记录按 wamid 进行 upsert。先回复 200,再在队列或后台任务中执行 CRM 操作。
Webhook 步骤不会重试,Meta 自身的重复投递也会在自动化运行前被过滤,因此每条消息最多只会调用您一次。其历史记录条目不含消息 ID:自动回复应以 run_id 加上其在运行中的位置作为键。来自 Try it 的测试携带 dry_run true 和示例联系人 15550000000;请跳过这些测试,确保测试运行不会创建 CRM 记录。
Node.js 中的接收程序是什么样的?
一个 Express 路由同时处理两类事件。它读取原始请求体,根据 X-EC-Event 请求头选择密钥,验证 X-EC-Signature,立即返回 200,并把工作交给后台函数。crm 对象代表您的 CRM API 客户端:按纯数字电话号码对联系人执行 upsert,并按唯一键对活动记录执行 upsert。同样的结构也适用于 n8n 工作流:用一个 Code 节点完成签名验证,之后接上您 CRM 的节点即可。
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);CRM 能否根据 AI 所了解的内容更新线索?
可以,在您的工作流中实现。携带 Call my webhook 步骤到达的聊天记录包含 AI 提出的问题以及客户的回答,因此 n8n 中的模型节点,或您后端中的一次调用,可以提取需求、预算、时间或地点,将其写入线索字段,然后推进其阶段。不要返回回复,因为客户已收到 AI 的消息。当工作流判断某条线索值得电话跟进时,可以为销售人员创建任务,或向团队发出警报。或者让 easyCoexistence 来完成提取:agent 或 AI saves details 步骤会把需求、预算和时间写入联系人字段,Call an API 步骤则可以将它们发送到您的 CRM,其请求体中使用 {{contact.budget}} 这类令牌。线索资格认定页面提供了该配置的访谈说明和 JSON 负载示例。
设置方法
- 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.
常见错误
- 在 CRM 中按自由文本电话字段搜索。WhatsApp 的纯数字格式很少与人工输入的内容一致,每次未命中都会产生重复联系人;请搜索经过标准化的纯数字属性。
- 在回应转发之前调用 CRM。若 CRM 耗时超过 10 秒,easyCoexistence 就会重试;如果没有按 wamid 进行 upsert,活动记录就会被记录两次。
- 只记录转发,却期待自动化回复出现在其中。API 发送的回复以不含文本的状态形式返回;在回复之后添加 Call my webhook 步骤,才能携带其文字内容。
- 让测试进入 CRM。Try it 会以 dry_run true 和示例联系人 15550000000 真正调用您的 URL;请在任何 upsert 之前丢弃这些事件。
它的 Forward URL 将客户消息和电话回复以 Meta 原始事件的形式传送到您的 CRM,按号码签名,并在 CRM 停机时重试约 33 小时;Call my webhook 步骤则补充自动回复的内容。转发和自动化功能均包含在套餐中。每个号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,前 3 天免费试用。
常见问题
哪些 CRM 可以使用此功能?
任何提供 API 的 CRM 都可以,既可以通过您自己的后端连接,也可以通过 n8n、Make 或 Zapier 等工作流工具连接,只要这些工具提供相应节点。HubSpot 有一个 Communications 对象,其中包含专为记录这类消息而设计的 WhatsApp 渠道类型;HubSpot 页面展示了相关调用方法。
团队能否在 CRM 中回复客户?
可以,前提是 CRM 通过 Meta 的 Cloud API 发送,使用号码的发送端点以及 get_api_credentials 返回的访问令牌:在客户最后一条消息之后 24 小时内可发送自由文本,此后只能发送已获批准的模板。这些消息也会显示在手机应用中的聊天线程里。
以往的对话能否导入 CRM?
只能通过 Meta 的历史记录导入功能,每个连接仅可一次性地将最多 6 个月的一对一聊天发送到在连接后 24 小时内保存的直接 Webhook 目的地。设置为 “Through easyCoexistence” 的号码,会从转发开始的那一刻起开始记录。
easyCoexistence 在过程中会保存什么?
转发的变更会进入队列等待重试,并在 7 天后删除。在通过 easyCoexistence 处理的号码上,消息文本还会在 Conversations 中以及作为 AI 上下文按您选择的期限保留,可选 30、90 或 365 天;运行日志保留 30 天。永久记录由 CRM 保存。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间