登录开始免费试用
Meta Tech Provider

自动将 WhatsApp 对话发送到您的 CRM

要自动将 WhatsApp 对话发送到 CRM,请把收到的消息以已签名的 Webhook 形式投递到您的后端或工作流工具,按电话号码查找或创建联系人,并将该消息作为活动记录记在该联系人下。把 WhatsApp 消息 ID 用作活动记录的唯一键,这样重试的投递会更新同一条记录,而不会新建第二条。

easyCoexistence 通过 Coexistence 将您在应用中保留的 WhatsApp Business 号码连接到 Meta 的 Cloud API。

X-EC-Delivery

转发的 POST 请求的请求头中包含投递 ID,同一投递的每次重试,该 ID 都相同。

About 33 hours

7 次转发尝试的时间跨度,分别约在 1、5、30、120、360 和 1,440 分钟后进行。

1 attempt

Call my webhook 步骤只会调用您的 URL 一次;超时或出错会使本次运行失败,并向您发送电子邮件。

BSUID

业务范围用户 ID(BSUID),例如 US.13491208655302741918,可与电话号码一同或代替电话号码,通过 user_id 和 from_user_id 发送。

30 days

自动化运行日志中触发消息、回复和各步骤的保留时长。

哪些事件应该发送到 CRM?

在 Coexistence 号码上,一段对话由三类消息组成,并通过两条路径传送。按号码设置的 Forward URL 会发送客户的来信,以及您的团队在 WhatsApp Business 应用中输入的消息,这些都以 Meta 的原始事件形式传送,并在 CRM 响应之前持续重试。自动化发出的回复通过 API 到达 Meta,只以投递状态的形式回报,不含文本;如要记录其内容,请在自动化末尾加一个 Call my webhook 步骤,其历史记录中包含本次运行刚发送的回复。一个端点可以同时接收两者:X-EC-Event 请求头在步骤事件中为 automation.step,在转发事件中则为 Meta 的字段名。

Customer messagesForward URL, event messages, in value.messages
Replies typed on the phoneForward URL, event smb_message_echoes, in value.message_echoes
Automated repliesCall my webhook as the last step: history entries with direction out
Lead detailsSaved by an agent or an AI saves details step, or extracted by your workflow from the chat; see lead qualification

如何将 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 phonemessages[].fromcontact.wa_id
Contact namecontacts[].profile.namecontact.name
BSUIDcontacts[].user_id, messages[].from_user_idNot sent
Activity texttext.body, or the media typemessage.text and history[].text
Directionmessages = in, smb_message_echoes = outhistory[].direction: in, out or echo
Timetimestamp, Unix secondsmessage.at and history[].at, ISO 8601
Unique keymessages[].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 的节点即可。

Express receiver: forwards and Call my webhook steps into a 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 负载示例。

设置方法

  1. 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.
  2. Deploy the receiverPublish the endpoint or n8n workflow on public HTTPS, with the CRM upserts keyed on the phone and the message id.
  3. Save the Forward URLPaste the receiver's URL into Forward URL (optional), click Save forward URL and store the signing secret shown once.
  4. 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.
  5. 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 之前丢弃这些事件。
使用 EasyCoexistence 完成这些操作

它的 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,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间