集成概述
- 准备您的账户。 成为 YCloud 技术合作伙伴,创建 API 密钥,并配置您的 Webhook 接收端。
- 配置入口点。 打开 合作伙伴 > 技术合作伙伴 > Partner Direct Link ,设置您的品牌信息、重定向 URL 或 SDK 源域。
- 创建链接。 您的服务器为您系统中的客户请求入驻链接。
- 让客户完成连接。 客户打开托管页面或 SDK 弹窗并完成 Meta 授权。
- 确认结果。 您的后端接收 Webhook 并将 WABA 与客户关联。
开始之前
- 成为经批准的 YCloud 技术合作伙伴。随后 Partner Direct Link 将自动可用。
- 在 开发者 > API 密钥 中创建 API 密钥。
- 在 开发者 > Webhook 中配置接收端并订阅
whatsapp.business_account.updated。
在控制台中找到 Partner Direct Link
- 打开已批准技术合作伙伴账户的 YCloud 控制台。
- 打开 合作伙伴 > 技术合作伙伴。
- 选择 Partner Direct Link 标签页。

After approval, open Partner > Tech Partner and select Partner Direct Link.
配置品牌与入口点
在 YCloud 控制台中打开 合作伙伴 > 技术合作伙伴 > Partner Direct Link 。完成 基本设置:
对于 SDK 源域,请输入准确的协议(scheme)、域名和可选端口,不要包含路径。请分别添加每个子域名或端口;不支持通配符。生产环境中请使用 HTTPS。仅在
localhost 开发时允许使用 HTTP。Direct Link 无需配置允许的 SDK 源域即可工作;SDK Button 则必须配置。
在服务器上创建入驻链接
- WhatsApp 商业平台 (
WHATSAPP_BUSINESS_PLATFORM):选择此模式可通过 API 和您的软件连接号码进行消息收发。 - WhatsApp Business App 共存 (
WHATSAPP_BUSINESS_APP):当客户希望继续使用该应用并在同一号码上增加 API 消息收发功能时,针对符合条件的现有 Business App 号码选择此模式。
en_US(英语)、zh_CN(简体中文)、es_ES(西班牙语)、pt_BR(巴西葡萄牙语)、id_ID(印度尼西亚语)和 ru_RU(俄语)。值区分大小写。传入其他值将返回 HTTP 400。
响应示例:
expiresAt 是以毫秒为单位的 Unix 时间戳形式的过期时间。链接的默认有效期为两小时。每个链接将一位客户连接到一个 WABA。在注册完成之前,只要链接仍然有效,客户就可以刷新、重试或在另一个浏览器中打开该链接。绑定成功后,该链接无法再绑定其他 WABA。当客户需要更改或添加 WABA 时,请创建一个新链接。
选项 1:Direct Link
在您的客户应用程序中添加一个连接按钮。当客户点击该按钮时,从您的服务器请求一个入驻链接并跳转到onboardingUrl 或在新窗口中打开它。您也可以通过安全的一对一渠道将其私密发送给目标客户。
客户打开托管页面并点击 Continue with Meta。他们使用具有管理其业务权限的 Facebook 账户,并在 Meta 中选择或创建其业务、WABA 和电话号码。YCloud 完成绑定并显示结果。

Direct Link integration and the hosted page preview. This example has no generated onboarding link.
status=connected。使用此参数来更新面向客户的页面;使用下文的 Webhook 在您的后端确认绑定。
选项 2:SDK 按钮
将您页面的来源(origin)添加到 Allowed SDK origins,然后加载 SDK。您的浏览器代码调用您自己的后端以获取链接。下面的/api/ycloud/onboarding-link 路由是您在服务器上实现的示例路由。
onStatus(result) 上报注册状态:
onError(error) 表示 SDK 无法打开注册页面。其 code 可以是 POPUP_BLOCKED 或 INVALID_ONBOARDING_URL。onClose(event) 仅在客户在获得最终结果前关闭窗口时触发,并带有 reason: "USER_CLOSED"。
这些回调用于更新您的前端。请使用服务端 Webhook 作为最终绑定结果。
通过 Webhook 确认绑定
Subscribe to whatsapp.business_account.updated in Developers > Webhooks to receive the binding result.
whatsapp.business_account.updated 发送到您配置的 Webhook 接收端。以下摘录显示了您的集成所使用的字段:
updateEvent 为 PARTNER_ADDED 时,将 WABA 作为新添加项处理。将 partnerCustomerId 与您的客户进行匹配,并保存 WABA id。paymentMethodAttached 的值为 true 表示信用额度绑定成功;false 表示尚未完成。
使用事件 id 对接收到的推送进行去重,并在成功接收后返回 HTTP 2xx。接收端设置请参见 Webhooks。

