跳转到主要内容
Partner Direct Link (TP Lite) 是面向经批准的 YCloud 技术合作伙伴的集成选项。在您的技术合作伙伴申请获得批准后即可使用,且您无需成为 Meta 合作伙伴。 在您的服务器上创建短期有效的入驻链接。您的客户可以直接打开该链接,或通过您网站上的按钮打开。建议先通过 Direct Link 测试集成,如果您希望客户在弹窗中完成注册,则可以使用 SDK 按钮。

集成概述

  1. 准备您的账户。 成为 YCloud 技术合作伙伴,创建 API 密钥,并配置您的 Webhook 接收端。
  2. 配置入口点。 打开 合作伙伴 > 技术合作伙伴 > Partner Direct Link ,设置您的品牌信息、重定向 URL 或 SDK 源域。
  3. 创建链接。 您的服务器为您系统中的客户请求入驻链接。
  4. 让客户完成连接。 客户打开托管页面或 SDK 弹窗并完成 Meta 授权。
  5. 确认结果。 您的后端接收 Webhook 并将 WABA 与客户关联。

开始之前

  1. 成为经批准的 YCloud 技术合作伙伴。随后 Partner Direct Link 将自动可用。
  2. 在 开发者 > API 密钥 中创建 API 密钥。
  3. 在 开发者 > Webhook 中配置接收端并订阅 whatsapp.business_account.updated。
从您的服务器调用链接创建 API。切勿将 API 密钥放入浏览器或移动应用代码中。将每个入驻 URL 视为临时凭证:避免出现在公开页面、分析工具和公开日志中。
  1. 打开已批准技术合作伙伴账户的 YCloud 控制台。
  2. 打开 合作伙伴 > 技术合作伙伴。
  3. 选择 Partner Direct Link 标签页。
包含 Meta 技术提供商和 Partner Direct Link 标签页的技术合作伙伴页面

After approval, open Partner > Tech Partner and select Partner Direct Link.

该页面包含用于配置品牌信息的 基本设置 ,以及用于创建链接、集成入口点和订阅 Webhook 的 集成 。使用 托管页面预览 可查看面向客户的页面。

配置品牌与入口点

在 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 时,请创建一个新链接。 在您的客户应用程序中添加一个连接按钮。当客户点击该按钮时,从您的服务器请求一个入驻链接并跳转到 onboardingUrl 或在新窗口中打开它。您也可以通过安全的一对一渠道将其私密发送给目标客户。 客户打开托管页面并点击 Continue with Meta。他们使用具有管理其业务权限的 Facebook 账户,并在 Meta 中选择或创建其业务、WABA 和电话号码。YCloud 完成绑定并显示结果。
Direct Link 集成,带有入驻 URL 占位符和客户注册页面的预览

Direct Link integration and the hosted page preview. This example has no generated onboarding link.

如果您配置了重定向 URL,注册成功后将重定向到该地址,并在查询参数中附带 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 确认绑定

展示 whatsapp.business_account.updated Webhook 事件的 Partner Direct Link 集成步骤

Subscribe to whatsapp.business_account.updated in Developers > Webhooks to receive the binding result.

绑定成功后,YCloud 会将 whatsapp.business_account.updated 发送到您配置的 Webhook 接收端。以下摘录显示了您的集成所使用的字段:
当 updateEvent 为 PARTNER_ADDED 时,将 WABA 作为新添加项处理。将 partnerCustomerId 与您的客户进行匹配,并保存 WABA id。paymentMethodAttached 的值为 true 表示信用额度绑定成功;false 表示尚未完成。 使用事件 id 对接收到的推送进行去重,并在成功接收后返回 HTTP 2xx。接收端设置请参见 Webhooks。