WhatsApp Business Solution Provider (BSP) 账号对接 Cloud API 接入文档

本文链接：https://blog.csdn.net/hchx0407062010/article/details/145559655

1. 文档概述

本文档详细说明了如何将WhatsApp Business Solution Provider（BSP）账号与Cloud API进行对接，包括接口的对接方法、商务流程、普通账号关联BSP账号流程以及相关的技术准备和测试步骤。

2. 文档范围

本文档适用于希望通过WhatsApp BSP账号接入Cloud API，实现企业级客户服务消息功能的开发者和企业用户。

3. 技术准备

3.1 环境要求

操作系统：建议使用Ubuntu 20.04或以上版本，确保系统支持最新的安全协议。
开发环境：Java 11及以上版本，推荐使用IntelliJ IDEA或Eclipse进行开发。
服务器：推荐使用云服务器（AWS、Google Cloud、阿里云等）进行部署，确保有固定的外部IP地址。
安全要求：
- 启用HTTPS协议，确保API通信的安全性。
- 配置防火墙，仅开放必要的端口（如443和80）。

3.2 API接入准备

创建 Meta for Business账号：
- 访问Meta for Business官网（https://business.facebook.com/）。
- 按照指引创建企业账号，并完成身份验证。
获取 BSP账号和API凭证：
- 登录Meta for Business账号，找到WhatsApp Business API入口。
- 申请BSP账号，并获取以下信息：
  - Business ID（业务ID）
  - API Key（API密钥）
  - API Secret（API密钥秘密）

3.3 证书配置

下载证书：
- 登录WhatsApp Business API管理界面，下载企业的Verbatim SSL证书。
安装证书：
- 将下载的证书安装到服务器的信任存储中，确保API请求能够通过SSL验证。

证书配置示例（Java）：

将证书文件（如WhatsApp_Business_API.crt）放置在项目资源目录下。
在代码中加载证书，配置HTTPS请求的信任库。

import java.io.FileInputStream;
import java.security.KeyStore;

// 以Java为例
public class WhatsAppAPIClient {
    public static void main(String[] args) throws Exception {
        KeyStore trustStore = KeyStore.getInstance("JKS");
        trustStore.load(new FileInputStream("WhatsApp_Business_API.crt"), "changeit".toCharArray());

        TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
        tmf.init(trustStore);

        SSLContext sslContext = SSLContext.getInstance("TLS");
        sslContext.init(null, tmf.getTrustManagers(), null);

        SSLContext.setDefault(sslContext);
    }
}

4. 接口对接

4.1 REST API Endpoint

以下是WhatsApp Business API的主要接口 endpoint：

接口功能	HTTP方法	Endpoint URL
发送消息	POST	`https://waicol.api.whatsapp.com/v1/messages`
接收消息	POST	`https://waicol.api.whatsapp.com/v1/webhooks`
用户更新	POST	`https://waicol.api.whatsapp.com/v1/users`
模板消息	POST	`https://waicol.api.whatsapp.com/v1/messages/template`
上传媒体	POST	`https://waicol.api.whatsapp.com/v1/media`
获取消息状态	GET	`https://waicol.api.whatsapp.com/v1/messages/{message_id}`
获取用户详情	GET	`https://waicol.api.whatsapp.com/v1/users/{user_id}`

4.2 API请求示例

发送文本消息

POST /v1/messages HTTP/1.1
Host: waicol.api.whatsapp.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
    "to": "+1234567890",
    "type": "text",
    "text": {
        "body": "Hello from WhatsApp Business API!"
    }
}

返回示例：

{
    "id": "message_id_123",
    "status": "sent",
    "timestamp": "2025-02-10T15:00:00.000Z"
}

接收消息网页回呼

POST /v1/webhooks HTTP/1.1
Host: waicol.api.whatsapp.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
    "messages": [
        {
            "from": "+1234567890",
            "to": "your_business_number",
            "type": "text",
            "text": {
                "body": "用户发来的消息内容"
            },
            "timestamp": "2025-02-10T15:00:00.000Z"
        }
    ]
}

4.3 异常处理与重试机制

错误处理：
- 检查API返回的错误代码和消息，按需处理。
- 组织错误日志，便于后续排查。

重试机制：
-.failed牌数：建议每次失败后等待1秒重试，最多重试3次。

public boolean sendMessage(RetryingLive punches) {
    for (int retry = 0; retry < 3; retry++) {
        try {
            // 发送消息逻辑
            return true;
        } catch (Exception e) {
            // 等待1秒后重试
            Thread.sleep(1000);
        }
    }
    return false;
}

5. 商务流程

5.1 商务流程概述

WhatsApp BSP账号对接Cloud API后，企业可以通过API接收和发送消息，用于客户服务、营销推广等用途。本节详细说明从接入到收费的商务流程。

5.2 具体流程

提交申请：
- 登录Meta for Business平台，找到WhatsApp Business API的应用节!, 提交开通申请。
- 填写企业信息，包括公司名称、地址、联系方式等。
审核通过：
- Meta审核企业资质后，开通BSP账号。
技术对接：
- 配置API接口，完成证书安装和测试。
费用结算：
- 根据使用的功能和消息数量，计费并结算费用。
监控与预警：
- 定期监控API使用情况和费用消耗，设置预警机制，避免超出预算。
客户支持：
-peror的问题和异常，及时与Meta的技术支持联络。

5.3 商务流程示意图

启动项目 → 提交申请 → 审核通过 → 技术对接 → 费用结算 → 监控预警 → 客户支持

6. 普通账号关联BSP账号流程

6.1 登录流程

登录WhatsApp Business：
- 打开WhatsApp Business应用，输入您的手机号码和密码登录。
进入设置：
- 点击右上角的三点菜单，选择“设置”。
账号与业务工具：
- 在设置页面，选择“账号与业务工具”选项。
关联BSP账号：
- 找到“关联Business Solution Provider账号”选项，点击进入。
- 输入 Your BSP账号信息，完成关联。

6.2 验证与激活

验证邮箱和手机号：
- 确保您的邮箱和手机号码已验证，进入下一步。
接受权限：
- 在关联过程中，系统可能要求您授予某些权限，确保所有权限都已正确授予。
激活服务：
- 完成关联后，系统会自动激活您的BSP账号功能。
- 您可以在设置中查看已激活的服务状态。

7. 测试验证

7.1 对接前的测试

接口测试：
- 使用Postman或其他API测试工具，发送请求到测试环境，确保接口返回预期结果。
回调地址验证：
- 确保Webhook回调地址可用，并且能够正确接收和处理消息。
证书测试：
- 使用工具测试HTTPS连接，确保SSL/TLS连接正常。

7.2 监控与日志

日志记录：
- 在代码中添加详细的日志记录，跟踪API请求和相应的处理过程。
监控工具：
- 部署如日志分析工具（ELK Stack）或监控平台（Prometheus + Grafana）实时监控API的使用情况和错误率。

8. 问题解答

8.1 常见问题

如何获取 API Token？
- 登录Meta for Business账号，进入WhatsApp Business API管理界面，找到并复制API Token。
接口返回404错误
- 检查请求的URL是否正确，确认API endpoint地址无误。
证书配置失败
- 检查证书是否正确安装，确保证书路径和密码正确。
消息发送失败
- 检查是否超过了API的发送频率限制，查看错误信息，按需调整发送策略。
无法接收消息
- 确认回调地址正确，并且服务器端口配置正确，外部网络能够访问。