在应用中保留的号码上,用 Claude Code 或 Codex 构建 WhatsApp 机器人
在 Claude Code 或 Codex 中添加 WhatsApp MCP 服务器,让编程智能体完成设置:它读取号码的 Cloud API 凭证,搭建 Webhook 接收器,把收到的消息路由给它,并向过去 24 小时内来信的人发送测试回复。您最终得到的是自己的智能体,以您的代码运行在您的服务器上。
easyCoexistence 通过 Coexistence 将您保留在应用中的 WhatsApp Business 号码连接到 Meta 的 Cloud API,并为 Claude Code 和 Codex 提供超过 30 个 MCP 工具用于构建:凭证、路由、模板、测试发送和自动化。
Claude Code 的一个参数,可在您的所有项目中加载服务器;默认的 local 作用域仅在添加服务器的项目中加载它。
Codex 的一条命令,用于保存服务器的 OAuth 登录信息;若未提供凭证,Codex 可以不经身份验证进行连接。
直接 Webhook 目标必须使用的协议,并且必须在 Meta 的 GET 握手中回显 hub.challenge。
“Call my webhook”步骤在端点返回 {"reply"} 之前等待的时长,超时后该步骤失败。
用户最后一条消息之后的客户服务窗口;窗口之外,Meta 只接受模板消息。
同时使用 WhatsApp Business 应用和 Cloud API 的号码,其固定吞吐量。
编程智能体构建 WhatsApp 智能体需要什么?
需要四样东西。通过 Coexistence 连接到 Meta 的 Cloud API 的 WhatsApp Business 号码,这样应用可以留在手机上,同时代码能够收发消息。从 Claude Code 或 Codex 到该号码的 MCP 连接,使编程智能体无需您打开控制台即可读取凭证、修改路由并发送测试消息。接收器的公共 HTTPS 地址,可以来自您部署的主机,也可以在开发期间使用隧道。以及您正在构建的智能体所用的模型密钥。
请在心中区分两个智能体。Claude Code 或 Codex 是构建者:只有您在终端中与它协作时它才会工作。它编写的程序负责回答客户,并且在您关闭会话后仍会持续运行。
如何在 Claude Code 和 Codex 中添加 WhatsApp 工具?
两者都只需在终端中输入一个 URL,并通过 OAuth 登录,因此任何密钥都不会写入文件。在 Claude Code 中,使用 --scope user 添加服务器,使其在每个项目中加载,然后启动 claude,运行 /mcp,选择 easycoexistence,并在浏览器中登录。在 Codex 中,添加服务器后运行 codex mcp login 来保存登录信息;codex mcp list 可显示已配置的内容。Codex 将配置保存在 ~/.codex/config.toml 中,ChatGPT 桌面应用和 Codex IDE 扩展同样会读取该文件。
请通过询问只有这些工具才能回答的问题来检查是否成功,例如“列出我的 WhatsApp 号码”。智能体会调用 list_numbers,并获取每个号码的 connection_id,其他所有工具都需要它。
# Claude Code: then start claude and run /mcp to sign in
claude mcp add --transport http easycoexistence --scope user https://easycoexistence.com/api/mcp
# Codex: add, store the OAuth sign-in, check
codex mcp add easycoexistence --url https://easycoexistence.com/api/mcp
codex mcp login easycoexistence
codex mcp list智能体应选择哪种路由?
有三种路由可以把客户的消息传到您的代码,它们在代码需要处理的内容上有所不同。对于第一个版本,“Call my webhook”步骤最简单:easyCoexistence 会跳过重复消息,在您通过手机回复时自动退让,并在调用您的端点之前检查 24 小时窗口,因此您的代码只需编写回复。当智能体需要每一个事件,而不只是自动化筛选出的消息时,再改用 Forward URL 或直接目标。
您应该让编程智能体做什么?
先给出路由、语言和规则,并在它编写代码前要求其提供计划。告诉它可以自行进行哪些工具调用:读取凭证和文档是无害的,而更改消息的去向会影响正在运行的号码。get_docs 会返回 easyCoexistence 的文档,包括接收器如何验证投递,因此智能体可以阅读规则,而不必猜测。像下面这样的请求,会生成一个可以一次审阅完毕的接收器:
Build a WhatsApp agent in Node.js for my number +55 11 4000 1234.
1. Call list_numbers, then get_api_credentials for that number.
Put send_endpoint and access_token in .env, never in code.
2. Scaffold an HTTPS server with POST /wa/<long random path>.
Verify X-EC-Signature (HMAC-SHA256 of "<t>.<raw body>").
Skip message ids already handled.
On smb_message_echoes, stay quiet on that chat for 4 hours.
3. Reply with my model only within 24 hours of the
customer's last message.
4. Write tests for the signature check and the 24-hour rule.
Do not call set_inbound_mode or set_webhook_destination
until I say so.如何连接接收器并进行测试?
先在 Meta 和 easyCoexistence 能通过 HTTPS 访问的地方启动服务器,然后让智能体完成路由设置。对于 Forward URL 路由,它会在 Automations 中将某个号码的模式设为 on,并以您的 URL 调用 set_inbound_mode;转发密钥只返回一次,智能体会将其写入您的 .env。对于直接路由,端点必须先响应 Meta 的 GET 握手,然后智能体再调用 set_webhook_destination,传入 URL、路径中一个很长的随机密钥以及您的验证令牌。
测试时,请用您自己的手机向业务号码发送消息,并观察日志:接收器应当看到该事件,模型应当作出回答,回复应当出现在聊天中。因为您刚刚发了消息,24 小时窗口仍然开启,所以编程智能体也可以尝试向您自己的号码调用 send_message。
完成的智能体仍然需要 MCP 服务器吗?
不需要。MCP 服务器是构建者的工具,以您的身份登录。您部署的智能体通过 Meta Graph API 发送消息,使用 get_api_credentials 返回的 send_endpoint 和 access_token。其中 access_token 是该业务自己的令牌,权限范围限于其 WhatsApp 资产,智能体通过您设置的路由接收消息。如果 access_token 返回为 null,可以从控制台重新连接号码来签发一个令牌,而不会替换仍在正常工作的令牌。
在智能体周边的工作中,请保留 MCP 连接:用 create_template 创建模板,在出现异常时用 get_number_health 检查,以及读取任何将消息交给您代码的自动化的运行日志。
设置方法
- Connect your numberAt easycoexistence.com, run Meta's Embedded Signup and scan the code with the WhatsApp Business app; the app keeps its chats.
- Add the server to your coding agentRun the claude mcp add or codex mcp add command, then sign in with /mcp in Claude Code or codex mcp login in Codex.
- Ask for credentials and a planHave the agent call list_numbers and get_api_credentials, store the values in .env and propose the receiver before writing it.
- Expose the receiver over HTTPSDeploy it, or run a tunnel while developing, and confirm the URL answers from outside your machine.
- Route the messagesLet the agent call set_inbound_mode with a Forward URL, or set_webhook_destination for the direct route, once you approve.
- Test from your phoneSend the business number a message and check that your agent's reply arrives in the same chat.
常见错误
- 在最初 24 小时内将一次性隧道保存为直接目标。Meta 对联系人的一次性导入以及最多 6 个月的聊天记录都会发送到该 URL,隧道关闭后这些数据便会丢失。
- 在运行自动化的号码上设置直接目标。该号码会切换为直接模式,其自动化随即停止;若要两者兼顾,请在 Automations 中使用 Forward URL 模式。
- 提交智能体写入的 .env。请先将其加入 .gitignore,因为任何持有访问令牌的人都能以该业务的名义向客户发送消息。
- 对 24 小时内未曾来信的联系人测试 send_message。Meta 在窗口之外会拒绝自由文本消息,因此请先用您自己的手机向该号码发送消息。
您的智能体随后运行在您自己的服务器上,每个号码全天候监控并附带警报。每个已连接号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,并提供前 3 天免费试用。
常见问题
Cursor 或其他编程工具也能使用吗?
可以。任何通过 OAuth 以 Streamable HTTP 连接远程服务器的 MCP 客户端,都可以使用同一个 URL,包括 Cursor、VS Code、Gemini CLI 和 Antigravity。不同客户端之间只有配置格式有所不同。
智能体应当用哪种语言编写?
任何能够提供 HTTPS 并计算 HMAC-SHA256 的语言都可以。Node.js 和 Python 是常见选择,两者都有经过测试的示例,包含签名校验、重复消息处理和手机暂停功能,见 Node.js 与 Python 智能体页面。
我需要自己的 Meta 应用或 App Review 吗?
不需要。号码通过 easyCoexistence 的 Meta 应用加入 Cloud API,并保留在该业务自己的 Business Portfolio 中。您的代码所使用的令牌属于该业务本身,因此无需涉及您自己的 Meta 应用。
编程智能体能创建智能体所需的模板吗?
可以。使用 create_template 创建模板,然后调用 get_template_status,直到 Meta 作出答复,通常几分钟内完成,最长约 24 小时。您的智能体需要一个已获批准的模板,才能在 24 小时窗口关闭后发起会话或继续发送消息。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间