用 Node.js 实现 WhatsApp 接单智能体
教程将 WhatsApp Cloud API、Node.js webhook 与支持工具调用的大模型串联,实现查菜单、创建订单和生成支付链接。模型负责选择工具,服务端执行函数并回传结果,数据库访问由代码控制。
AI 深度解读
顾客在 WhatsApp 上问「今天晚上 6 点能送 2 公斤 paneer 吗」,菜单机器人通常得让他重新选商品、填数量、挑时间。作者给出了一套约 150 行核心代码的 Node.js 示例,让顾客按平时说话的方式点单,由模型理解消息,服务端查价、建单并生成付款链接。
这套方案最值得看的是模型和业务代码怎么分工。读完你可以带走一套工具调用的写法,也能看清这个演示离真正接单还缺哪些环节。
一条 WhatsApp 消息怎么变成订单?
顾客发消息给商家号码,Meta 的 WhatsApp Cloud API 把消息推到 Express 的 POST /webhook。服务端取出文字,把它和可用工具一起交给 Claude。模型可以直接回一句话,也可以请求查菜单、建单或生成付款链接。服务端执行工具,再把结果交回模型。拿到最终回复后,服务端通过 Cloud API 发回 WhatsApp。
跑通这个链路需要 Node.js 18 或更高版本,用的是内置 fetch。在 Meta 开发者应用里添加 WhatsApp 产品后,仪表盘会提供测试号码、Phone Number ID 和临时访问令牌。本地联调还需要一个公开的 HTTPS 地址,作者举的是 ngrok 和 Cloudflare Tunnel。项目初始化用 mkdir wa-agent && cd wa-agent、npm init -y 和 npm install express dotenv @anthropic-ai/sdk,再给 package.json 加上 "type": "module",入口是 node server.js。
示例的 .env 用 WA_TOKEN、WA_PHONE_ID 和自选的 WA_VERIFY_TOKEN 配置 WhatsApp,用 ANTHROPIC_API_KEY 和 MODEL=claude-sonnet-5-5 配置模型,服务监听 PORT=3000。原文写的是 GRAPH_VERSION=v21.0,同时建议以 Meta 仪表盘显示的版本为准。
为什么 Webhook 一收到消息就回 200?
Meta 先用 GET /webhook 验证回调地址。代码检查 hub.mode 是否为 subscribe,以及 hub.verify_token 是否等于 WA_VERIFY_TOKEN。通过就返回 200 和 hub.challenge,失败则返回 403。在 Meta 后台给公开 HTTPS 地址加上 /webhook,填入同一个验证令牌,再订阅 messages 字段,后续消息就由 POST 推过来。
收到 POST 后,代码先回 200,再取出事件里的第一条消息,只处理 text,并用内存里的 Set 按 msg.id 去重。早点应答是为了避免模型调用拖慢回调,导致 Meta 把请求当成失败再推一次。这里的 200 表示服务端已经应答。查价、写订单和发回复都发生在应答之后,任何一步失败都需要应用自己处理。
出站消息走另一个接口。sendText 用 fetch 向 https://graph.facebook.com/${process.env.GRAPH_VERSION}/${process.env.WA_PHONE_ID}/messages 发 POST,通过 WA_TOKEN 做 Bearer 认证,请求体把 messaging_product 设为 whatsapp、type 设为 text。示例遇到发送失败只写日志。订单已经创建、顾客却没有收到回复,是这个流程里可能出现的状态。
模型能选工具,订单金额由谁决定?
get_menu 返回商品、单位和单价。create_order 接收 items 和 delivery_time,其中每个商品项都需要 product 和 quantity。payment_link 接收 order_id,查到订单后拼出 UPI 链接。工具描述和系统提示都要求先确认商品和送达时间再建单。实际算钱时,runTool 查服务端的 MENU,按单价乘数量汇总,所以示例里的 paneer 每公斤 420 印度卢比,2 公斤就是 ₹840。
下面这段把模型的工具请求交给本地代码,并把运行结果送回同一轮对话。
if (res.stop_reason !== 'tool_use') {
history.set(customer, trimHistory(messages));
return res.content
.filter((b) => b.type === 'text')
.map((b) => b.text)
.join('\n');
}
// Run every tool the model asked for and send the results back
const results = res.content
.filter((b) => b.type === 'tool_use')
.map((b) => ({
type: 'tool_result',
tool_use_id: b.id,
content: JSON.stringify(runTool(b.name, b.input, customer)),
}));
messages.push({ role: 'user', content: results });
留意 tool_use_id: b.id 这一行。模型一次可以请求多个工具,这个 ID 让每份结果都能对应到原来的那次调用。外层循环最多调用模型 5 次,每次设置 max_tokens: 1024。用完 5 次就返回兜底文案,示例没有接上实际的人工转接。
对话历史用手机号作为 Map 的键,正常返回时保留最近约 30 条,并从一条纯文本用户消息开始截取,避免留下缺少前文的工具结果。重启会清掉这些历史,示例里的订单数组也一样。作者给出的历史持久化选项包括 Postgres、MongoDB 和 Redis。
我的判断
这里做对的是把自由文本理解和业务规则放在各自擅长的位置。固定菜单适合选项少、步骤稳定的业务,也更容易预估流程成本。顾客经常把商品、数量和时间塞进一句话,或者在英语、印地语和 Hinglish 之间切换时,模型解析才更有用。原文给了测试号的试跑方式和 ₹840 的预期结果,没给实测日志、多语言样本、成功率、延迟或与菜单机器人的对照数据。三种语言可以共用同一套代码是作者的方案描述,各语言下的接单准确率仍待验证。
真正的缺口在写操作。系统提示要求顾客先确认,但 create_order 没有检查独立的确认状态,也没校验数量必须是有限正数。payment_link 按 order_id 查找,查到以后还应该验证订单属于当前顾客,否则工具只要收到别人的有效订单号就可能返回那笔订单的付款链接。示例生成的是 upi://pay 链接,原文没有展示支付结果回调。对于一般团队,可以让模型把自然语言整理成待确认订单,再复用现有购物车或结算流程完成写入。这种做法少交给模型一些决定,代价是要接好确认状态和原有的订单接口。
能拿来做什么
- 用 WhatsApp 测试号跑通「报价、确认、建单」三步。让顾客在确认前把 2 公斤改成 1 公斤,检查最终写入的商品数量、送达时间和金额是否一致。
- 在 Node.js 的
runTool里复用已有的商品和订单校验。建单前检查确认状态和数量,生成付款链接前检查订单归属,最后让模型按工具返回的结果组织回复。 - 如果要让真实顾客下单,把 Webhook 改成先持久化待处理消息再回
200,并给建单加持久化幂等键。这样即使同一事件重复处理,或订单写入后回复发送失败,也能重试而不重复建单。