如何通过 Embedded Signup 和 Coexistence 为您的 SaaS 添加 WhatsApp
SaaS 通过 Meta 的 Embedded Signup 结合 Coexistence,连接每位客户现有的号码,为其添加 WhatsApp。该号码在 WhatsApp Business 应用中继续可用。借助 easyCoexistence 的 Partner API,每位客户对应一次连接会话,并在托管页面上运行该流程。Meta 将号码的消息投递至您的 webhook_url,您的后端则使用客户自己的访问令牌,通过 Cloud API 回复。
同时使用 WhatsApp Business 应用和 Cloud API 的号码,吞吐量固定。
客户号码可通过 Coexistence 连接的 WhatsApp Business 应用最低版本。
Meta 在入驻时可共享的聊天记录回溯期限,且须在 24 小时内完成同步。
用户发送消息或来电后,WhatsApp 客户服务窗口的时长;每条新消息都会重置该窗口。
Meta 停止支持 Embedded Signup v2 和 v3 的日期,集成已迁移至 v4。
一套 WhatsApp 集成由哪些部分组成?
共五个部分,easyCoexistence 负责第一部分和最后一部分。您的产品负责对话逻辑、收件箱,以及您的模型或客户员工撰写的内容;Meta 负责号码与您的服务器之间的消息传递:
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 形式到达,使用同一令牌获取。
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 借助 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 监控
验证时间