登录开始免费试用
easyCoexistence 官方 API

如何通过 Embedded Signup 和 Coexistence 为您的 SaaS 添加 WhatsApp

SaaS 通过 Meta 的 Embedded Signup 结合 Coexistence,连接每位客户现有的号码,为其添加 WhatsApp。该号码在 WhatsApp Business 应用中继续可用。借助 easyCoexistence 的 Partner API,每位客户对应一次连接会话,并在托管页面上运行该流程。Meta 将号码的消息投递至您的 webhook_url,您的后端则使用客户自己的访问令牌,通过 Cloud API 回复。

20 mps

同时使用 WhatsApp Business 应用和 Cloud API 的号码,吞吐量固定。

2.24.17

客户号码可通过 Coexistence 连接的 WhatsApp Business 应用最低版本。

180 days

Meta 在入驻时可共享的聊天记录回溯期限,且须在 24 小时内完成同步。

24 hours

用户发送消息或来电后,WhatsApp 客户服务窗口的时长;每条新消息都会重置该窗口。

October 15, 2026

Meta 停止支持 Embedded Signup v2 和 v3 的日期,集成已迁移至 v4。

一套 WhatsApp 集成由哪些部分组成?

共五个部分,easyCoexistence 负责第一部分和最后一部分。您的产品负责对话逻辑、收件箱,以及您的模型或客户员工撰写的内容;Meta 负责号码与您的服务器之间的消息传递:

1ConnectEmbedded Signup with Coexistence on a hosted page
2Routewebhook_url set on the number as it connects
3ReceiveMeta posts messages and echoes to your server
4ReplyCloud API calls with the customer's token
5WatchStatus events when the number drops or returns

Coexistence 对您的客户有什么改变?

客户保留自己的号码和手机。WhatsApp Business 应用与 Cloud API 并行运行,因此员工可以在手机上回复,而您的产品通过 API 回复。员工从应用发出的消息会以 smb_message_echoes 的形式到达您的 Webhook。该方案有三项限制:号码的发送速率固定为每秒 20 条消息;只有 API 可以发送模板;若手机持续约 14 天未活跃,Meta 会断开该号码。

连接步骤在您的产品中是什么样的?

一个“连接 WhatsApp”按钮,由您的后端调用 POST /connect-sessions,传入 redirect_url、客户的 id 作为 external_ref,以及 webhook_url 和 webhook_verify_token,这样 Meta 从第一分钟起就会把号码路由到您这里。客户在托管页面上确认一份简短清单,运行 Meta 的弹窗,用 WhatsApp Business 应用扫描二维码,然后带着 connection_id 返回您的产品。若改为在您自己的 Tech Provider 应用中运行 Embedded Signup,请参阅 Embedded Signup 指南中的权衡说明。

消息如何到达您的后端?

消息直接从 Meta 发送至 webhook_url,不经过 easyCoexistence,也不保留任何副本。messages 字段包含客户发来的内容以及您所发消息的状态,smb_message_echoes 则包含员工从应用中发送的内容。Meta 使用 easyCoexistence 的应用密钥为每次投递签名,该密钥从不共享,因此 URL 路径中一段足够长的随机密钥即可用于验证身份。同一 WhatsApp Business 账户中的两个号码共用一个目标地址,请根据 value.metadata.phone_number_id 进行路由。

您的后端如何回复和发送模板?

通过 Meta 的 Graph API,并使用 GET /connections/{id}?credentials=1 返回的客户访问令牌,该接口同时返回 send_endpoint。自由文本只能在用户最后一条消息之后的 24 小时内发出;超过此时限后,只能发送 Meta 已批准的模板:

  • 回复:在窗口期内,使用 type 为 text 的 POST /<PHONE_NUMBER_ID>/messages。
  • 模板:相同的调用,type 为 template,并附带模板名称及其语言代码。
  • 创建模板:POST /<WABA_ID>/message_templates,然后轮询其状态,因为审核结果不会送达您的 webhook_url。
  • 媒体:POST /<PHONE_NUMBER_ID>/media 上传;接收到的媒体以 ID 形式到达,使用同一令牌获取。
Reply inside the customer service window
curl -X POST "$SEND_ENDPOINT" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511987654321",
    "type": "text",
    "text": { "body": "Your table for 4 is booked for 8 pm." }
  }'

您的产品能否导入客户现有的聊天记录?

只能导入一次,在连接时进行。在会话上设置 webhook_url 后,easyCoexistence 会请求 Meta 发送该号码的联系人;若客户在应用中同意,还会发送最多 180 天的聊天记录,以 smb_app_state_sync 和 history 类 Webhook 的形式到达。Meta 仅允许在连接后 24 小时内导入,因此在发送连接链接之前,请确保端点已能正常响应。聊天记录指南介绍了负载格式。

Meta 的消息费用由谁承担?

由您的客户承担。您的后端通过 API 发送的消息由 Meta 计入客户自己的 WhatsApp Business 账户,费用从客户在该账户中添加的付款方式扣除;没有付款方式的商家无法发送营销模板。easyCoexistence 按每个已连接号码向您的账户收费,不对消息收费,也不加价 Meta 的价格。

号码断开时会怎样?

您的事件 URL 会收到 connection.disconnected 事件,并在已知时附带 Meta 给出的原因。PRIMARY_INACTIVITY 对应上述 14 天规则;为该客户创建新的连接会话即可让同一号码恢复。connection.token_missing 表示号码连接时未携带客户的访问令牌,因此它能接收消息,但在新会话重新连接之前无法发送。

常见错误

  • 在您的 Webhook 端点响应之前发送连接链接。历史记录导入只会执行一次,且须在连接后 24 小时内完成;在您的 URL 可用之前发送的内容将会丢失。
  • 在窗口关闭后仍用自由文本回复。用户最后一条消息发出满 24 小时后,只有经批准的模板才能送达。
  • 以全速从一个号码发送营销活动。Coexistence 号码的发送速率为每秒 20 条消息,因此请按此速率为每个号码排队发送。
  • 期望员工从手机发送模板。在 Coexistence 中只有 API 可以发送模板,因此请在您的产品中实现模板发送。
使用 EasyCoexistence 完成这些操作

easyCoexistence 借助 Meta 的 Embedded Signup 和 Coexistence,在显示您名称的托管页面上为您的 SaaS 添加 WhatsApp:客户保留自己的号码和 WhatsApp Business 应用,Meta 将消息投递至您的服务器,并以已签名事件的形式送达您。同一 API 还可连接 Instagram、Facebook、TikTok、YouTube、LinkedIn 以及更多渠道。每个连接每月 US$ 9 至 US$ 0.75,连接越多单价越低,前 3 天免费。

常见问题

客户能否连接已在其他 WhatsApp API 服务商上的号码?

在该号码仍绑定其他服务商时不能。托管清单要求号码上没有其他 API 服务商或自动化工具,因此客户需先在该服务商处断开连接。

我的 SaaS 能否为客户发送 WhatsApp 模板?

可以,通过 Cloud API 并使用每位客户的访问令牌:先在其 WhatsApp Business 账户中创建模板,等待 Meta 审核,然后发送。

easyCoexistence 会读取我客户的 WhatsApp 消息吗?

不会。Meta 将号码的消息直接投递至您设置的 webhook_url。未设置 webhook_url 的号码会回退到 easyCoexistence 的回调地址,消息在该处被丢弃,不作存储。

easyCoexistence 每个 WhatsApp 号码的费用是多少?

每个号码每月 US$ 9 至 US$ 0.75,按您全部连接数所在的档位计价,前 3 天免费。Meta 的消息费用由各客户自己的 WhatsApp Business 账户承担。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间