Partner Direct Link (TP Lite)

Partner Direct Link (TP Lite) 是面向 YCloud 技术合作伙伴的一种集成选项。您需要联系 YCloud 为您的账户启用该功能，但无需成为 Meta 合作伙伴。在您的服务器上创建短期有效的入驻链接。您的客户可以直接打开该链接，也可以通过您网站上的按钮打开。建议先使用 Direct Link 测试集成，若希望客户在弹窗中完成注册，后续可改用 SDK 按钮。

集成概述

准备账户。 联系 YCloud 启用 Partner Direct Link、创建 API 密钥并配置您的 Webhook 接收端。
配置入口点。 在控制台中打开 Partner Direct Link，设置您的品牌信息、重定向 URL 或 SDK 来源。
创建链接。 您的服务器为您系统中的客户请求入驻链接。
让客户进行连接。 客户打开托管页面或 SDK 弹窗并完成 Meta 授权。
确认结果。 您的后端接收 Webhook 并将 WABA 与客户关联。

开始之前

联系 YCloud 为您的账户启用 Partner Direct Link。如果您还不是技术合作伙伴，请申请成为合作伙伴。
在 开发者 > API 密钥中创建 API 密钥。
在 开发者 > Webhooks 中配置接收端并订阅 whatsapp.business_account.updated。

从您的服务器调用链接创建 API。切勿将 API 密钥放入浏览器或移动应用代码中。请将每个入驻 URL 视为临时凭证：避免将其暴露在公开页面、分析工具及公开日志中。

在控制台中查找 Partner Direct Link

打开已启用 Partner Direct Link 的账户对应的 YCloud 控制台。
展开左侧边栏中的 开发者 。
点击 Partner Direct Link 打开配置页面。

带有基础设置和托管注册预览的 Partner Direct Link 页面 — Open Developers > Partner Direct Link to configure your branding and entry point. This example shows the settings before configuration.

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

配置您的品牌信息与入口点

在 YCloud 控制台中打开 开发者 > Partner Direct Link 。完成 基础设置：

设置	要求	用途
显示名称	必填	托管注册页面上显示的合作伙伴名称。
合作伙伴 Logo	可选	托管注册页面上显示的您的 Logo。
重定向 URL（仅限 Direct Link）	可选	注册成功后打开的完整 HTTPS URL。如果不提供，客户将看到带有您品牌信息的成功页面。
允许的 SDK 来源（仅限 SDK 按钮）	SDK 按钮必填	加载 SDK 的页面来源，例如 `https://app.example.com`。

对于 SDK 来源，请输入精确的协议、域名和可选端口，不要包含路径。每个子域名或端口需单独添加；不支持通配符。生产环境中请使用 HTTPS。HTTP 仅允许用于 localhost 开发。Direct Link 无需配置允许的 SDK 来源即可工作；SDK 按钮则必须配置。

在您的服务器上创建入驻链接

curl -X POST 'https://api.ycloud.com/v2/partner/embeddedSignup/links' \
  -H 'X-API-Key: YOUR_YCLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerCustomerId": "customer_001",
    "onboardingType": "WHATSAPP_BUSINESS_PLATFORM",
    "locale": "en_US"
  }'

字段	必填	描述
`partnerCustomerId`	是	您系统中固定的客户 ID。请避免包含敏感信息。YCloud 会在绑定成功的 Webhook 中返回此 ID。
`onboardingType`	是	如下所述，基于 API 的消息收发选择 `WHATSAPP_BUSINESS_PLATFORM`，Business App 共存模式选择 `WHATSAPP_BUSINESS_APP`。
`locale`	否	托管页面的语言。默认为 `en_US`。

WhatsApp Business Platform（WHATSAPP_BUSINESS_PLATFORM）：选择此模式以连接号码，通过 API 和您的软件进行消息收发。
WhatsApp Business App 共存（WHATSAPP_BUSINESS_APP）：当客户希望继续使用现有符合条件的 Business App 号码并在同一号码上增加 API 消息收发时，请选择此模式。

支持的语言区域包括 en_US（英语）、zh_CN（简体中文）、es_ES（西班牙语）、pt_BR（巴西葡萄牙语）、id_ID（印度尼西亚语）和 ru_RU（俄语）。取值区分大小写。其他值将返回 HTTP 400。响应示例：

{
  "onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
  "expiresAt": 1893456000000
}

expiresAt 为 Unix 毫秒时间戳格式的过期时间。默认链接有效期为两小时。每个链接将一位客户连接到一个 WABA。在完成注册之前，只要链接仍然有效，客户就可以刷新、重试或在另一个浏览器中打开该链接。绑定成功后，该链接不能再绑定其他 WABA。当客户需要更改或添加 WABA 时，请创建新链接。

方式 1：直接链接

在您的客户应用程序中添加连接按钮。当客户点击该按钮时，从您的服务器请求接入链接并跳转至 onboardingUrl 或在新窗口中打开。您也可以通过安全的一对一渠道私下将其发送给目标客户。客户打开托管页面并点击 Continue with Meta。他们使用拥有管理其业务权限的 Facebook 账户，并在 Meta 中选择或创建其业务、WABA 和电话号码。YCloud 将完成绑定并显示结果。

包含接入 URL 占位符和客户注册页面预览的 Direct Link 集成 — 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 路由是您在服务器上实现的示例路由。

<script src="https://connect.ycloud.com/open/sdk/v1.js"></script>
<button id="yc-onboarding" type="button">Continue with Meta</button>
<p id="yc-status" role="status"></p>

<script>
  const status = document.getElementById('yc-status');
  document.getElementById('yc-onboarding').addEventListener('click', async function () {
    try {
      const response = await fetch('/api/ycloud/onboarding-link', { method: 'POST' });
      if (!response.ok) throw new Error('Link creation failed');
      const { onboardingUrl } = await response.json();
      YCloudOnboarding.open({
        onboardingUrl,
        onStatus: function (result) {
          status.textContent = result.state === 'CONNECTED'
            ? 'WhatsApp connected. Confirming with your server.'
            : 'Signup is not complete. Follow the instructions in the signup window.';
        },
        onError: function (error) {
          status.textContent = error.code === 'POPUP_BLOCKED'
            ? 'Allow popups for this site, then try again.'
            : 'Unable to open signup. Request a new link.';
        },
        onClose: function () {
          status.textContent = 'Signup window closed before a final result.';
        }
      });
    } catch {
      status.textContent = 'Unable to create a signup link. Please try again.';
    }
  });
</script>

onStatus(result) 报告注册状态：

字段	含义
`state`	`CONNECTED` 表示成功。其他值表示流程未完成或失败，例如 `RETRYABLE_FAILED`。
`wabaId`	WABA ID，仅在成功时返回。
`phoneNumberId`	Meta 电话号码 ID，成功时可能会返回。
`errorCode`	失败时可能返回的错误代码。
`retryable`	客户是否可以在当前注册窗口中重试。
`requestId`	YCloud 请求 ID，排查问题时可提供给技术支持。

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 会向您配置的 Webhook 接收端发送 whatsapp.business_account.updated。以下代码摘录展示了您集成所需的字段：

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "whatsapp.business_account.updated",
  "whatsappBusinessAccount": {
    "id": "EXAMPLE_WABA_ID",
    "updateEvent": "PARTNER_ADDED",
    "paymentMethodAttached": true,
    "partnerCustomerId": "customer_001"
  }
}

当 updateEvent 为 PARTNER_ADDED 时，将该 WABA 作为新增处理。将 partnerCustomerId 与您的客户进行匹配，并保存 WABA id。paymentMethodAttached 值为 true 表示额度附加成功；false 表示尚未完成。使用事件 id 进行消息去重，并在成功接收后返回 HTTP 2xx。有关接收端设置，请参阅 Webhooks。

Partner Direct Link 问题排查

现象	操作
客户关闭 Meta 或中断注册流程。	在原始链接仍然有效的情况下，再次点击 Continue with Meta 。
页面提示链接已过期或无效。	在您的服务器上创建新链接。
SDK 提示源（origin）无效。	检查页面源是否完全匹配并包含在 Allowed SDK origins 中。
创建链接返回 HTTP 429。	等待 `Retry-After` 指定的时间段后再重试。避免频繁重复创建链接。
注册显示成功但您的系统未更新。	检查您的 Webhook 配置、事件订阅和接收端日志。请以 Webhook 作为最终结果。

概览

技术开发合作伙伴

解决方案合作伙伴

推广合作伙伴

Partner Direct Link (TP Lite)

集成概述

开始之前

在控制台中查找 Partner Direct Link

配置您的品牌信息与入口点

在您的服务器上创建入驻链接

方式 1：直接链接

方式 2：SDK 按钮

通过 Webhook 确认绑定

Partner Direct Link 问题排查

​集成概述

​开始之前

​在控制台中查找 Partner Direct Link

​配置您的品牌信息与入口点

​在您的服务器上创建入驻链接

​方式 1：直接链接

​方式 2：SDK 按钮

​通过 Webhook 确认绑定

​Partner Direct Link 问题排查

集成概述

开始之前

在控制台中查找 Partner Direct Link

配置您的品牌信息与入口点

在您的服务器上创建入驻链接

方式 1：直接链接

方式 2：SDK 按钮

通过 Webhook 确认绑定

Partner Direct Link 问题排查