技术开发伙伴入门

在本文档中,您将找到成为 YCloud 技术开发伙伴的详细步骤。

基本术语

在继续之前,您需要了解以下几个术语,以便更好地理解成为 技术开发伙伴 的整个过程:

Solution Partners(BSP)

BSP是Meta 业务合作伙伴,为其他企业提供全方位的 WhatsApp 商业平台服务,例如消息服务、计费、集成支持和客户支持。

解决方案合作伙伴拥有信用额度,可以将其扩展到他们引入的企业客户,这样这些客户就无需在入职过程中输入自己的付款方式。此外,解决方案合作伙伴可以获得直接支持

YCloud正是BSP。

Tech Providers

Tech Providers与BSP类似,他们也可以向其他企业提供全方位的 WhatsApp 商业平台服务,可以自行提供这些服务,也可以与已经提供这些服务的BSP合作。

然而,与BSP不同,Tech Providers没有信用额度。相反,Tech Providers引入的企业客户必须在引入完成后提供自己的付款方式。然后,Meta 将向这些客户收取 API 使用费,而技术提供商将收取其他服务的费用。

此外,技术提供商无法获得直接支持。

技术开发伙伴

作为YCloud平台上的一种合作伙伴类型,与YCloud集成从而获得完整的WhatsApp相关的API。

每个技术开发伙伴都需要先成为 Meta 认证的 Tech Provider 。

由YCloud提供计费,企业客户无需接入Meta付款。技术开发伙伴需要向自己引入的企业客户收取API使用费,然后再付给YCloud。

YCloud为技术开发伙伴提供支持。

嵌入式注册

嵌入式注册是一个身份验证和授权界面,它可以自动为您的企业客户生成所有必需的 WhatsApp 资产,并授权您的应用访问这些资产。

在嵌入式注册的流程中,会出现BSP和Tech Providers双方的品牌名称。

步骤1:提交合作申请

访问 YCloud合作伙伴页面提交申请表单: https://www.ycloud.com/zh/partner

YCloud商务团队会在1个工作日内与您联系。

步骤2:注册YCloud账户

在开始之前,您需要注册一个YCloud账户,并将您注册所使用的邮箱地址告诉YCloud商务团队。我们将为您开通技术开发伙伴权限。

注册链接:https://www.ycloud.com/console/#/entry/register

步骤3:成为Meta Tech Providers

请参考 Get Started for Tech Providers 并在 Meta 平台完 成以下步骤:

Step 1: Create a Business Portfolio

Step 2: Create a Meta App

Step 3: Add the WhatsApp Product

Step 4: Test Business Messaging on WhatsApp

Step 5: Scale your solution

Step 6: Complete Business Verification

步骤4:创建伙伴解决方案

前往 Meta App Dashboard > WhatsApp > Partner Solutions 面板点击 Create a partner solution 按钮。

使用YCloud的应用程序 ID 来完成流程。

Solution name 填入自己公司名称;

Partner App ID 填入 2892949377516980;

提交后等待YCloud团队审核。

一旦审核通过,将生成Solution ID,将通过邮件或BM通知您。

步骤5:配置嵌入式注册

先决条件:Facebook Login for Business 需要 public_profile 高级访问权限,请到 Meta App Dashboard > App Review > Permissions and Features 申请。

接着请 依次 完成以下步骤:

步骤1: Load the Facebook JavaScript SDK

步骤2: Create Facebook Login for Business Configuration,配置 Client OAuth settings(请参照图示开启 Login with the JavaScript SDK、添加 Allowed domains for the JavaScript SDK 等)

步骤3: Set up Facebook Login,并参考 Configuring Embedded Signup 配置 Solution ID

步骤4: Create a Login Button

步骤5: Session Logging

完整网页代码示例如下:

<html>
 
<head>
  <meta charset="utf-8"/>
  <script>
    window.fbAsyncInit = function () {
      // JavaScript SDK configuration and setup
      FB.init({
        appId: '{YOUR-FACEBOOK-APP-ID}', // Facebook App ID
        cookie: true, // enable cookies
        xfbml: true, // parse social plugins on this page
        version: 'v18.0' //Graph API version
      });
    };
 
    // Load the JavaScript SDK asynchronously
    (function (d, s, id) {
      var js, fjs = d.getElementsByTagName(s)[0];
      if (d.getElementById(id)) {
        return;
      }
      js = d.createElement(s);
      js.id = id;
      js.src = "https://connect.facebook.net/en_US/sdk.js";
      fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'facebook-jssdk'));
 
    // Facebook Login with JavaScript SDK
    function launchWhatsAppSignup() {
      // Launch Facebook login
      FB.login(function (response) {
        if (response.authResponse) {
          const code = response.authResponse.code;
          console.log('User authResponse code:', code);
          // The returned code must be transmitted to your backend,
          // which will perform a server-to-server call from there to our servers for an access token
        } else {
          console.log('User cancelled login or did not fully authorize.');
        }
      }, {
        config_id: '{YOUR-CONFIGURATION-ID}',
        response_type: 'code',    // must be set to 'code' for System User access token
        override_default_response_type: true, // when true, any response types passed in the "response_type" will take precedence over the default types
        extras: {
          sessionInfoVersion: 3,
          setup: {
            solutionID: '{YOUR-SOLUTION-ID}'
          }
        },
      });
    }
 
    const sessionInfoListener = (event) => {
      if (event.origin == null) {
        return;
      }
      
      // Make sure the data is coming from facebook.com
      if (!event.origin.endsWith("facebook.com")) {
        return;
      }
      
      try {
        const data = JSON.parse(event.data);
        if (data.type === 'WA_EMBEDDED_SIGNUP') {
          // if user finishes the Embedded Signup flow
          if (data.event === 'FINISH') {
            const {phone_number_id, waba_id} = data.data;
            console.log("Phone number ID ", phone_number_id, " WhatsApp business account ID ", waba_id);
          }
          // if user reports an error during the Embedded Signup flow
          else if (data.event === 'ERROR') {
            const {error_message} = data.data;
            console.error("error ", error_message);
          }
          // if user cancels the Embedded Signup flow
          else {
           const {current_step} = data.data;
           console.warn("Cancel at ", current_step);
          }
        }
      } catch {
        // Don’t parse info that’s not a JSON
        console.log('Non JSON Response', event.data);
      }
    };
    
    window.addEventListener('message', sessionInfoListener);
 
  </script>
</head>
 
<body>
<button onclick="launchWhatsAppSignup()"
        style="background-color: #1877f2; border: 0; border-radius: 4px; color: #fff; cursor: pointer; font-family: Helvetica, Arial, sans-serif; font-size: 16px; font-weight: bold; height: 40px; padding: 0 24px;">
  Launch Embedded Signup
</button>
</body>
 
</html>

注意

  1. 请将上面示例代码中的 appId、config_id、solutionID 替换为实际值

  2. 前端获取到 waba_id 和 phone_number_id 要传给后端,用于获取 WABA 和注册号码, 详见后文。

更多相关参考:

步骤6:获取 WABA 和注册号码

客户完成嵌入式注册后,您的前端会拿到 waba_idphone_number_id ,将其传给后端用于后续接口调用。

获取 WABA

调用 YCloud Retrieve a WABA 接口获取 WABA 详情,然后将其与您系统的客户的账号关联在一起。

请求示例:

curl 'https://api.ycloud.com/v2/whatsapp/businessAccounts/{{waba_id}}' \
-H 'X-API-Key: {{YOUR-API-KEY}}'

成功响应示例:

{
  "id": "{{waba_id}}",
  "name": "WABA name",
  "accountReviewStatus": "APPROVED",
  "paymentMethodAttached": true,
  "currency": "EUR",
  "timezoneId": "1"
}

注意:响应字段 paymentMethodAttachedtrue 表明 YCloud 已成功关联支付方式给此 WABA,否则,请联系 YCloud Team解决该问题

注册号码

调用 YCloud Register a phone number 接口注册号码,接口响应 HTTP status 200 即成功。

一般地,号码注册成功后状态会由 PENDING 转为 CONNECTED,即可使用该号码发送消息。

请求示例:

curl -XPOST 'https://api.ycloud.com/v2/whatsapp/phoneNumbers/{{waba_id}}/{{phone_number_id}}/register' \
-H 'X-API-Key: {{YOUR-API-KEY}}'

成功响应示例:

{
  "phoneNumber": "+8613800008888",
  "wabaId": "{{waba_id}}",
  "verifiedName": "Phone number name",
  "qualityRating": "GREEN",
  "messagingLimit": "TIER_250",
  "status": "CONNECTED"
}

步骤7:将WhatsApp API能力集成到自有应用中

作为YCloud技术开发伙伴,您将能够使用直接 API 来管理引入客户 WABA 和电话号码。您还将收到这些号码收到的消息的 webhook。

配置 Webhook

请参考 YCloud Configure Webhooks,订阅所有 WhatsApp 相关事件(以 whatsapp. 开头),并与您的系统集成。

更多 API 参考

WABA 相关接口:https://docs.ycloud.com/reference/whatsapp-business-accounts

消息相关接口:https://docs.ycloud.com/reference/whatsapp-messages

号码相关接口:https://docs.ycloud.com/reference/whatsapp-phone-numbers

模板相关接口:https://docs.ycloud.com/reference/whatsapp-templates

接口请求和 Webhook 推送示例:https://docs.ycloud.com/reference/examples

步骤8: App Review

当你Meta App 的模式为 Development 时,只有测试用户 (见 App Dashboard > App roles > Roles / Test users) 可以走通嵌入式注册流程。为了让它对所有人可用,需切换模式为 Live 并完成 App Review.

点击 Review app settings 以检查您保存的设置,并确保在开始应用检查之前选择了应用图标、隐私政策网址和应用类别。

最后,您的应用必须经过应用审核,并获得应用所需的任何权限的高级访问批准。

App 审核技巧

作为审核流程的一部分,您必须为请求中的每个权限提供单独的文字说明和视频。创建说明和视频时请遵循以下指南。

请注意,您必须针对每个权限提交不同的视频。每次提交相同的视频将导致您的提交被拒绝。

启动应用审核流程

您可以在 App Dashboard 中启动 App Review 流程:

应用程序仪表板> WhatsApp >快速入门>继续入职(按钮)>开始应用程序审核(按钮)

更多细节可参考:

步骤9: Go Live

当一切准备就绪,你可以告诉你的企业客户应该如何使用。

常见问题

如何判断嵌入式注册配置是否正确?

您配置了 solutionID,客户在 Facebook 授权时将看到 Solution Partner 对应的真实名称,若没有,说明配置未生效。请确保完成 App Review

什么情况 YCloud 无法给 WABA 关联支付方式?

用户可能选择了一个原有的 WABA 而非新建的 WABA,而原有的 WABA 可能有支付方式未解除。

嵌入式注册报错 App not active

打开嵌入式注册页面提示:

App not active

This app is not currently accessible and the app developer is aware of the issue. You will be able to log in when the app is reactivated.

App 模式为 Development 时,只有测试用户拥有权限时(到 App Dashboard > App roles > Roles / Test Users 查看)才可打开。

解决方案:将 App 模式切换为 Live,到 Meta Apps 点击对应的 App 进入 Dashboard 进行操作;或者为当前用户授权,详见 Assign business assets to people in your business portfolio

嵌入式注册报错 Feature unavailable

打开嵌入式注册页面提示:

Feature unavailable

Facebook Login is currently unavailable for this app as we are updating additional details for this app. Please try again later.

请到 App Dashboard > App Review > Permissions and Features 申请 public_profile 高级访问权限。

嵌入式注册报错 It looks like this app isn't available

检查嵌入式注册代码配置是否正确,如 config_id。

Last updated