登录开始免费试用
Meta Tech Provider

n8n 中的 WhatsApp AI 智能体,回复由您的工作流撰写

自动化步骤会将客户的消息(已签名,并附带聊天中最近的至多 10 条消息)以 POST 方式发送到 n8n 的 Webhook 节点。AI Agent 节点撰写答案,Respond to Webhook 节点在 20 秒内返回 {"reply": "..."},该文本随后从 WhatsApp Business 号码发出,而该号码在应用中仍可正常使用。较慢的智能体会直接接收 Meta 的 Webhook,并通过 Graph API 回复。

easyCoexistence 通过 Coexistence 将您已在应用中使用的 WhatsApp Business 号码连接到 Meta 的 Cloud API,并在该号码上运行自动化。

20 s

“Call my webhook”步骤等待您的工作流返回答复的时长,超时后该步骤失败。

10

随 history 发送的聊天中最近的消息,从早到晚排列,结尾是触发本次运行的那条消息。

4,096

一条 WhatsApp 文本中回复可包含的字符数上限;超出部分会被截断。

6 hours

Webhook 步骤失败时,同一自动化两封失败邮件之间的最短间隔。

2 modules

n8n Cloud 在 Code 节点中允许使用的模块为 crypto 和 moment;自托管的 n8n 需通过 NODE_FUNCTION_ALLOW_BUILTIN 启用 crypto。

24 hours

客户服务窗口是客户最后一条消息之后的时段;此后 Meta 只接受模板消息。

WhatsApp 消息如何到达 n8n AI 智能体?

通过号码上的自动化实现。号码必须通过 easyCoexistence 接收其消息(即“Through easyCoexistence”模式),这样 Meta 才会把消息投递到这里;触发条件为“A message arrives”、步骤为“Call my webhook”的自动化,随后会将消息以 POST 请求发送到您的 n8n Production URL。工作流在同一个 HTTP 响应中作答,其返回的文本会作为 WhatsApp 消息,从您的号码发给客户。

在调用 n8n 之前,本次运行已通过各项防护检查。Meta 重复投递的同一条消息绝不会启动第二次运行;您在应用中手动输入的回复会暂停该聊天中的自动化(默认 4 小时);回复只在客户最后一条消息之后的 24 小时内发出。您的工作流只决定说什么。

1Customer writesTo the number you keep in the WhatsApp Business app
2Call my webhookSigned POST with the message and recent chat
3n8n AI AgentWebhook node, signature check, AI Agent node
4Respond to Webhook{"reply": "..."} within 20 seconds
5Reply sentAlso shown in the app's chat thread

easyCoexistence 会向 n8n Webhook 节点发送什么内容?

一个 JSON POST 请求,其 User-Agent 为 easyCoexistence-automations/1,X-EC-Event 设为 automation.step,并带有 X-EC-Signature 请求头。message 字段包含客户的文本;若为媒体,则为占位符,如 [image](附带说明文字);语音消息则以 [voice message] 加其文字内容的形式到达(需已保存 OpenAI 或 OpenRouter 密钥)。history 字段包含聊天中最多 10 条最近消息,按从早到晚排列,每条都带有 direction:in 表示客户发来的消息,out 表示自动化的回复,echo 表示有人从手机端发出的消息。它覆盖账户保留期内保存的消息(30、90 或 365 天,默认 90 天),且仅限该号码的消息经由 easyCoexistence 传入期间收到的消息。

从编辑器的 Try it 面板进行的测试,会发送相同的 POST 请求,但 dry_run 设为 true,history 为空,联系人为示例号码 15550000000,名称为 Test customer,消息 id 以 test_ 开头。该测试不会发给任何人,但您的工作流会真正运行,因此当 dry_run 为 true 时,应跳过创建订单等副作用操作。

POST body of a Call my webhook step
{
  "event": "automation.step",
  "dry_run": false,
  "automation": { "id": "b7e0c3a2-5d1f-4c8e-9a6b-2f4d8e1c7a90", "name": "Send to my system" },
  "run_id": "0d9f6a41-8c2e-4b7a-a315-6e9c2b8d4f17",
  "channel": {
    "type": "whatsapp",
    "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922"
  },
  "connection": { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "phone": "+1 631-555-0142", "phone_number_id": "106540352242922" },
  "contact": { "id": "5511987654321", "wa_id": "5511987654321", "name": "Ana Souza" },
  "message": {
    "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
    "type": "text",
    "text": "Do you have gluten-free bread today?",
    "at": "2026-11-11T14:02:11.000Z"
  },
  "history": [
    { "direction": "in", "text": "Hi! Are you open today?", "at": "2026-11-11T13:58:40.000Z" },
    { "direction": "out", "text": "Hi Ana! Yes, until 8 pm.", "at": "2026-11-11T13:58:45.000Z" },
    { "direction": "in", "text": "Do you have gluten-free bread today?", "at": "2026-11-11T14:02:11.000Z" }
  ]
}

如何在 n8n 中验证签名?

在 Webhook 节点之后紧接着添加一个 Code 节点。X-EC-Signature 的格式为 t=<unix 秒数>,v1=<十六进制>,其中 v1 是对 t、一个点号和请求正文所做的 HMAC-SHA256 运算结果,密钥为该自动化的“Signing secret”。要复制密钥,请打开已保存的自动化,并选择其 Call my webhook 步骤。每个自动化都有自己的密钥,MCP 工具从不返回该密钥,因此由 AI 创建的自动化仍需从控制台复制这一次密钥。“New secret”按钮会替换该密钥,旧密钥立即失效,而且只有账户所有者能看到它,受邀的团队成员看不到。

拒绝与本地时钟相差超过 5 分钟的 t,使用恒定时间比较,验证失败时抛出错误:工作流随即在 Respond to Webhook 之前报错,n8n 返回 500,且不会发送任何内容。n8n Cloud 允许在 Code 节点中使用 crypto 模块;自托管的 n8n 需要设置 NODE_FUNCTION_ALLOW_BUILTIN=crypto。使用 IF 节点配合 Crypto 节点的 Hmac 操作也可行,但 IF 比较并非恒定时间。

n8n Code node: verify X-EC-Signature
// n8n Code node, mode "Run Once for Each Item", placed right after the Webhook node.
// n8n Cloud allows require('crypto'); self-hosted needs NODE_FUNCTION_ALLOW_BUILTIN=crypto.
const crypto = require('crypto');
const SECRET = 'whsec_...'; // the automation's Signing secret, from its editor page

const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec($json.headers['x-ec-signature'] || '');
if (!m) throw new Error('Missing X-EC-Signature');
if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) throw new Error('Stale signature');

// The body was signed as compact JSON, which JSON.stringify rebuilds from the parsed body.
const mac = crypto.createHmac('sha256', SECRET).update(`${m[1]}.${JSON.stringify($json.body)}`).digest();
if (!crypto.timingSafeEqual(mac, Buffer.from(m[2], 'hex'))) throw new Error('Bad signature');

return { json: $json.body }; // event, dry_run, contact, message, history...

如何设置 AI Agent 节点和回复?

将客户的文本作为 AI Agent 节点的用户消息输入,其余内容全部放入系统消息:包括企业是谁、可引用的事实、语气,以及来自 history 的近期聊天内容,以便后续问题能被正确理解。接入您想用的聊天模型,并可添加工具,例如用于查询订单的 HTTP Request 工具。

最后添加一个 Respond to Webhook 节点,以 JSON 格式响应,并将智能体的文本放入名为 reply 的字段中。easyCoexistence 会去除其首尾空白,忽略为空或非字符串的 reply,并将其余内容作为一条最多 4,096 个字符的 WhatsApp 文本发送,因此请让模型输出普通句子,而非 Markdown。

AI Agent and Respond to Webhook settings
AI Agent node
  Prompt: Define below
  Prompt (User Message): {{ $json.message.text }}
  Options > System Message:
    You answer WhatsApp messages for Bloom Café, 12 Baker St, open Tue to Sun 8:00 to 20:00.
    Reply in 1 to 3 short sentences, in the customer's language, as plain text.
    Never invent prices or stock. If unsure, say a person will reply here soon.
    Recent chat, oldest first:
    {{ $json.history.map(h => (h.direction === 'in' ? 'Customer: ' : 'Business: ') + h.text).join('\n') }}
  Chat Model: your OpenAI, Anthropic or OpenRouter model
  Tools (optional): an HTTP Request tool that looks up orders

Respond to Webhook node
  Respond With: JSON
  Response Body: { "reply": {{ $json.output.toJsonString() }} }

工作流响应缓慢、失败或无返回时会发生什么?

每种结果都会记录在自动化的 Runs 标签页中,并附带步骤的输出或错误,便于您查看以下哪种情况发生了:

  • 20 秒内无应答:步骤失败,报错为“Webhook did not answer”,不发送任何内容,运行状态显示为 Failed。
  • 状态码不在 2xx 范围内(包括重定向):步骤失败,报错为“Webhook answered HTTP”,并附带该状态码。
  • 2xx 但无回复字符串:运行状态为 Done,步骤显示 HTTP 200、无回复,客户不会收到任何自动回复。
  • 失败的运行会发邮件通知您,以便您亲自回复该客户,同一自动化每 6 小时最多发送一次。
  • 在暂停期内您通过手机回复过的聊天(默认 4 小时,可在 Advanced 下设置),会在调用 n8n 之前以 human_active 跳过。
  • 连续发送的多条消息会启动多次运行。在 Call my webhook 之前加入 1 分钟的 Wait 节点,只会应答一次,因为选中同一自动化的较新消息会取代正在等待的运行。

在什么情况下 n8n 应改为直接接收 Meta 的 Webhook?

以下情况需要直接接收:智能体需要超过 20 秒;工作流必须看到每一个事件(状态、您在手机上的回复、媒体 id);需要发送没有任何步骤涵盖的内容,例如 Flow 或目录消息;或企业希望导入 6 个月的历史记录,该导入只会发送到连接后 24 小时内保存的直接目标。直接模式会为该号码关闭自动化:Meta 会将其原始负载直接发送到 n8n,easyCoexistence 不会接触这些消息。

在 n8n 中,请使用普通的 Webhook 节点,而非 WhatsApp Trigger 节点,后者需要您自己的 Meta 应用及其密钥。开启 Allow Multiple HTTP Methods,使一个较长的随机路径同时接收 Meta 的 GET 握手和 POST 请求;将 GET 请求的 hub.challenge 原样以文本形式返回,并通过 set_webhook_destination 保存该 Production URL 与一个验证令牌。此后,回复将通过 HTTP Request 节点发送到发送端点,而去重、手机暂停和 24 小时检查则由您自行负责。

Call my webhook (Automations on)Direct webhook (automations off)
Who calls n8neasyCoexistence, when the automation matchesMeta, for every event on the number
Time to answer20 seconds, reply in the responseNo limit: send later through the Graph API
AuthenticationX-EC-Signature with the automation's secretA long random secret in the URL path
GuardsDedupe, phone pause and 24-hour check built inYours to write
What n8n can sendText in the reply; the other steps of the automation can send buttons, files and templatesAny Cloud API message type, templates included
History importNot availableIf saved within 24 hours of connecting
Kept by easyCoexistenceMessage text for your retention period (90 days by default), run logs 30 daysNothing

设置方法

  1. Turn on automations for the numberOn the number's page, the Automations and incoming messages card shows Automations on or Direct to your server. Click Turn on automations if needed; numbers connected without a webhook URL start with automations on.
  2. Build and publish the workflowWebhook node (POST, Respond: Using 'Respond to Webhook' Node), Code node, AI Agent node, Respond to Webhook node. Publish or activate it and copy the Production URL.
  3. Create the automation, switched OffIn Automations, click New automation and pick Send to my system under Start from an example. Paste the Production URL into Webhook URL, set the switch to Off so it does not answer customers yet, and click Save.
  4. Copy the Signing secret into n8nSelect the Call my webhook step of the saved automation, copy Signing secret and paste it into the Code node.
  5. Test, then switch it OnClick Test, type a sample message in Try it and press Run test: n8n runs with dry_run true and the result shows the reply. When it reads right, switch the automation On and save.

常见错误

  • Webhook 节点的 Respond 选项保持为 Immediately。n8n 会立即回复 Workflow got started,运行记录 HTTP 200、无回复,客户什么也收不到。应选择 Using 'Respond to Webhook' Node。
  • 粘贴了 Test URL(即带有 /webhook-test/ 的那个)。它只在编辑器等待测试事件时监听;自动化需要已发布工作流的 Production URL。
  • 使用号码的转发密钥进行验证。“Call my webhook”是用该自动化自己的 Signing secret 签名的;转发密钥只为转发事件签名,因此真实的步骤会验证失败。
  • 以其他结构返回文本。只有顶层为名为 reply 的字符串的 JSON 正文会被发送;{"output": "..."} 或 text/plain 正文会被记录为无回复。
使用 EasyCoexistence 完成这些操作

其 Call my webhook 步骤会将客户的消息交给 n8n,并回传回复;去重、您在手机上回复时的暂停以及 24 小时检查均已内置,每次运行不另外收费。每个已连接号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,前 3 天免费。

常见问题

ChatGPT 或 Claude 能帮我创建这个自动化吗?

可以。添加 easyCoexistence 连接器后,请 AI 为您的号码创建一个自动化,将收到的消息发送到您的 n8n URL;AI 会调用 create_automation 并附带 call_webhook 步骤,然后调用 test_automation。您可以要求它先将自动化保持停用,待测试通过后再启用。Signing secret 不会通过 MCP 返回,因此请从自动化页面复制它。

工作流能否发送图片、按钮或模板?

不能通过回复字段发送,该字段只承载文本。请改为让自动化来完成:Send a picture or file、Ask a question with buttons 和 Send a template 等步骤可以放在 Call my webhook 之前或之后。对于其他消息类型,请使用 HTTP Request 节点向 Cloud API 发送,所用的发送端点和访问令牌由 get_api_credentials 返回,并且不返回任何回复,以免客户被重复应答。

一个工作流能否应答多个号码?

可以。为每个号码各设置一个自动化,都指向同一个 Production URL,并根据 channel.phone_number_id 或 automation.id 进行分支。每个自动化都有自己的 Signing secret,因此在验证签名之前,请先根据 automation.id 选择对应的密钥。

自托管的 n8n 可以使用吗?

可以,前提是其 Production URL 为公网 HTTPS。保存 URL 时以及每次调用前,easyCoexistence 都会拒绝 http、localhost、私有地址和内部地址,并且不会跟随重定向。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间