AI 智能体的 WhatsApp API:几分钟内获得官方访问权限,无需成为 Tech Provider
AI 智能体通过 Meta 的 Cloud API 获得 WhatsApp 官方访问权限,留在 WhatsApp Business 应用中的号码需通过 Tech Provider 或 Solution Partner 加入。您可以自行成为其中之一,此时需完成企业验证、App Review 视频以及 Embedded Signup 搭建;也可以连接已具备该资格的服务商:号码几分钟内即可加入,智能体获得 MCP 工具或 API 凭证。
easyCoexistence 是一家独立的 Meta Tech Provider:它通过 Coexistence 在几分钟内将 WhatsApp Business 号码连接到 Cloud API,使您的智能体获得官方访问权限,同时企业保留应用。
Meta 要求接入仍留在 WhatsApp Business 应用中的号码的一方,须具备 Tech Provider 或 Solution Partner 身份。
App Review 要求提交两段视频:一段是从您的应用发送消息,另一段是您的应用创建消息模板。
App Review 授予 whatsapp_business_messaging 和 whatsapp_business_management 的权限,两者都是成为 Tech Provider 所必需的。
Meta 弃用 Embedded Signup v2 和 v3,并通知集成方迁移至 v4。
同时使用 WhatsApp Business 应用和 Cloud API 的号码,吞吐量是固定的。
平台通过 Partner API 为客户接入号码时,托管连接链接的有效时长。
AI 智能体要官方使用 WhatsApp,需要什么?
需要 Meta Cloud API 提供的四样东西。第一是电话号码 ID,以及具有 whatsapp_business_messaging 权限的访问令牌,使智能体能够调用 messages 端点。第二是 Webhook 端点,Meta 将收到的消息投递到这里;如果号码与应用共用,还需要 smb_message_echoes,用于接收用户在手机上输入的回复。第三是已获批准的消息模板,因为自由文本消息只能送达过去 24 小时内曾发来消息的用户。第四是能及时发现连接中断的方式,因为即使 API 端已停止,手机上的应用仍可正常工作。
人们最先想到的捷径是 WhatsApp Web 自动化,它以已关联设备的身份登录。无论其上的智能体如何运作,这种做法都违反 WhatsApp 的条款,并使号码面临被封禁的风险。
Tech Provider 路径包含哪些步骤?
按 Meta 规定的顺序进行,依次如下。每个步骤都免费,也无法通过付费加快:审核按 Meta 的排期进行,Meta 未公布时间表,因此在第一位客户的号码接入之前,请以数周而非数天来规划。之后后端必须持续运行:每次注册后的令牌交换、Webhook 接收器、按号码路由,以及监控断线情况,例如 Meta 的 14 天不活跃规则。
更短的路径是什么?
通过一家已完成该流程的服务商连接号码。使用 easyCoexistence 时,企业运行 Meta 的 Embedded Signup,并用 WhatsApp Business 应用扫描二维码,约需两分钟。号码随即加入企业自有的 Business Portfolio 中的 Cloud API,应用仍可继续使用。随后智能体可以以它所用的形式获得访问权限:为 ChatGPT、Claude、Claude Code 或 Codex 等助手提供 MCP 工具,或为您运行的代码提供号码的凭证和 Webhook。
| Connect through easyCoexistence | Become a Tech Provider | |
|---|---|---|
| Meta app and App Review | Not needed: the number joins through ours | Yours to build and pass |
| Embedded Signup | Hosted, with the QR scan in the app | You integrate version 4 and host the flow |
| First number connected | Minutes after signing up | After verification and review |
| Webhook trust | A secret in your URL, or X-EC-Signature on forwarded messages | Your app secret signs Meta's deliveries |
| Disconnection alerts | Every number watched 24/7, 14-day rule included | Monitoring you build and run |
| Who owns the WhatsApp Business Account | The business, in its own portfolio | The business |
智能体如何获取号码的凭证?
通过 get_api_credentials,或从控制台中该号码的页面获取。该工具返回 Graph API 基础 URL、WhatsApp Business 账户 ID、电话号码 ID、发送端点,以及(如果存在)企业自有的访问令牌,且其作用范围限定于该企业的 WhatsApp 资产。若未签发客户端令牌,令牌将以 null 返回,并附带说明:在控制台中重新连接该号码即可签发一个令牌,且不替换仍在工作的令牌。无需获取应用密钥,因为 Meta 使用 easyCoexistence 的应用密钥为 Webhook 签名,该密钥从不共享。该工具需要有效套餐,因为该令牌可用于发送消息。
curl -X POST "$SEND_ENDPOINT" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999998888",
"type": "text",
"text": { "body": "Your order #1042 is ready for pickup." }
}'传入消息如何到达智能体?
每个号码有两种模式,可通过 set_inbound_mode 或号码页面切换。直接发送至您的服务器:set_webhook_destination 将 Meta 直接指向您的 HTTPS 端点,该端点必须响应 Meta 的 GET 握手,且 easyCoexistence 不会接触这些消息,因此自动化功能处于关闭状态。由于 Meta 使用我们的应用密钥为这些投递签名,请在 URL 路径中放置一段足够长的随机密钥,并拒绝不含该密钥的请求。
开启自动化:Meta 将消息投递至 easyCoexistence,自动化可以作出回复;可选的转发 URL 会接收 Meta 的原始负载(位于 "value" 下),并使用 X-EC-Signature: t=<unix>,v1=<HMAC-SHA256 of "<t>.<body>"> 签名,签名密钥仅显示一次。自动化中的「调用我的 Webhook」步骤还会将消息及该聊天最近 10 条消息交给您的智能体;若您的回复为 {"reply": "..."} 且在 20 秒内返回,则会发送该回复。
智能体必须遵守哪些限制?
这些限制来自 Meta,无论通过哪家服务商,都是一致的。提前了解它们的智能体,可避免那些看似是缺陷的故障:
- 每个号码每秒 20 条消息,由 Meta 为与 WhatsApp Business 应用共用的号码所固定。
- 仅能在客户最后一条消息后的 24 小时内发送自由文本消息;此后须使用已获批准的模板。
- 模板只能通过 API 发送,因为 Coexistence 号码上的应用无法发送模板。
- 用户在应用中输入的回复会以
smb_message_echoes形式到达;请对该聊天暂停智能体,否则客户会收到两条回复。 - 群聊不会同步至 API,因此智能体只在一对一聊天中工作。
- 联系人以及最多 6 个月的一对一聊天只会导入一次,且仅当连接后 24 小时内保存了直接 Webhook 目的地时才会导入;开启自动化的号码不会进行导入。
- 语音和视频通话仍可在应用中使用,但 Cloud API 不承载 Coexistence 号码上的通话,因此智能体仅以文本方式工作。
平台能否以这种方式接入其客户的号码?
可以,通过 Partner API。SaaS 或代理机构无需自身拥有 Tech Provider 身份,即可借此为其客户接入号码。使用 create_api_key 创建密钥(以 ec_live_ 开头,且仅显示一次),然后从您的后端调用 POST /api/v1/connect-sessions,或在助手中使用 create_connect_link,以获取有效期为 1 小时的托管链接。客户在该页面完成 Meta 弹窗与二维码扫描,然后带着 connection_id 返回您的 redirect_url。随后 GET /api/v1/connections/:id?credentials=1 会返回客户自己的令牌,而 connection.disconnected 等状态事件则会附带 X-EC-Signature 签名到达。每个号码按相同的按号码计费档位,由您的账户付费。
常见错误
- 在直接目的地上验证 X-Hub-Signature-256。Meta 使用 easyCoexistence 的应用密钥签名,该密钥从不共享,因此真实投递会未通过校验;请信任 URL 中足够长的随机密钥,或使用带 X-EC-Signature 的转发。
- 使用 n8n 的 WhatsApp Trigger 节点接收消息。它要求您自己的 Meta 应用;请改用通用 Webhook 节点,并在其 URL 中放置密钥。
- 忽略 smb_message_echoes。智能体随后会在已经从手机回复过的用户之上再次回复,客户就会看到两条回复。
- 连接后过了数天才保存直接 Webhook 目的地,或让号码保持开启自动化。Meta 对联系人及最多 6 个月聊天的一次性导入,需要在连接后 24 小时内保存直接目的地。
智能体可通过超过 30 个 MCP 工具工作,也可通过每个号码的凭证和 Webhook 工作,每个号码全天候监控并配有警报。每个号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,前 3 天免费试用。
常见问题
需要我自己的 Meta 应用吗?
不需要。号码通过 easyCoexistence 的 Meta 应用接入,并保留在企业自己的 Business Portfolio 和 WhatsApp Business 账户中。您的代码使用 get_api_credentials 返回的企业自有令牌发送,因此除非您以后自行构建,否则不涉及您的应用。
智能体与团队能否同时使用该号码?
可以。Meta 会在 Cloud API 与 WhatsApp Business 应用之间同步消息,因此智能体发送的内容会出现在手机应用的聊天会话中,团队在应用中输入的内容则会以 smb_message_echoes 的形式到达您的系统。
哪些智能体框架可以与它配合使用?
任何通过 OAuth 在 HTTP 上使用 MCP 协议的客户端,如 ChatGPT、Claude、Claude Code、Codex 和 Cursor,以及任何调用 Meta Graph API 的代码:Node.js、Python、n8n、LangChain、OpenAI Agents SDK 或 Vercel AI SDK。底层 API 由 Meta 提供,智能体内部不含任何专有部分。
WhatsApp 是否允许通用型 AI 助手使用?
Meta 的《Business Solution Terms》第 4.7 节禁止通用型 AI 助手提供商在 WhatsApp Business Platform 上提供服务,前提是 AI 是其主要功能(由 Meta 认定),该规定自 2026 年 1 月 15 日起生效。将 AI 用于自身客户、用于支持、销售或预订的企业不属于该限制对象,而欧盟和巴西的监管机构已责令 Meta 暂停或撤回该规定对竞争性助手的适用。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间