使用 Vercel AI SDK 构建 WhatsApp 智能体

路由处理器如何接收 WhatsApp 消息？

在同一路由上实现两个方法，并将其设为该号码的 Webhook 目标，路径中带有一段较长的随机密钥。

GET 用于应答 Meta 的验证。从查询中读取 hub.mode、hub.verify_token 和 hub.challenge，比对令牌，然后以纯文本返回 challenge。通过 JSON 辅助函数返回是典型的错误：响应体会带上引号，Meta 就不会开始投递。

POST 用于接收事件。请尽快返回 200，之后再调用模型，因为 Meta 会重试响应较慢的请求，而在冷启动时同步运行模型，可能会对同一条消息回复两次。在响应发出后即结束函数的平台上，请把工作交给队列，或使用平台提供的响应后处理机制。

路径中的密钥就是身份验证。Meta 使用 Tech Provider 应用的密钥为每次投递签名，因此您这一侧无法校验 X-Hub-Signature-256 标头。

AI SDK 如何加载 WhatsApp 工具？

使用来自 @ai-sdk/mcp 的 createMCPClient 和 HTTP 传输，AI SDK 文档推荐在生产环境中使用这种方式。该传输接受服务器 URL 和 authProvider，EasyCoexistence MCP 服务器正是通过 authProvider 的 OAuth 完成授权：它发布 OAuth 元数据，支持动态客户端注册和 PKCE，并在登录后签发自己的令牌。无需在标头中放置 API 密钥。

客户端的工具可直接传入 generateText 或 streamText。随后模型会看到 list_numbers、send_message、send_template、get_number_health 等工具，其描述中注明了 24 小时窗口。调用结束后请关闭客户端：流式调用在 onEnd 回调中关闭，其他情况在 finally 块中关闭，这也是 AI SDK 文档的要求。

适用于需要由模型自行决定的场景。若只是回复刚收到的消息，在处理器中直接调用 Cloud API 更简短。

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://easycoexistence.com/api/mcp",
    authProvider, // your OAuthClientProvider implementation
  },
});

try {
  const tools = await mcp.tools();
  // pass tools to generateText({ model, tools, prompt })
} finally {
  await mcp.close();
}

号码使用 Coexistence 后有什么变化？

有两点代码需要知道。第一，可能已有真人在对话中。WhatsApp Business 应用在该号码上仍可使用，在手机上输入的每条回复都会以回显事件的形式送达路由。处理器在收到回显后，对该联系人暂停调用模型，就能避免模型盖过真人的回复。

第二，该号码的发送速率固定上限为每秒 20 条消息。对话型智能体远不会触及这个上限，但用 Promise.all 遍历联系人列表编写的群发循环会触及，所以请分批发送。

其余都是普通的 Cloud API。客户最后一条消息后的 24 小时内，允许发送自由文本。超过之后，只有已获批准的模板才能发出，自由文本会返回错误 131047，而客户不会看到任何内容。

常见错误

• 用 JSON 响应辅助函数返回 challenge。外层的引号会导致 Meta 的验证失败。
• 在响应 Meta 之前就运行 generateText。冷启动时，重试会产生第二条答复。
• 忘记关闭 MCP 客户端。每个请求都会留下一个未关闭的连接，直到平台将其终止。

常见问题

继续阅读