配置 WhatsApp 消息渠道

本文介绍如何在 Yeastar P 系列云 PBX 上配置 WhatsApp 消息渠道，以便企业坐席可以在 Linkus UC 客户端上接收并回复来自 WhatsApp 的客户消息。

使用要求

确保以下资源已准备就绪。
平台 要求
Yeastar PBX
  • 固件版本：84.20.0.128 或更高版本
  • 订阅服务：企业版 或 旗舰版
  • 域名：由于第三方平台限制，域名中不能包含下划线，否则消息渠道会出现验证失败或无法接收消息的问题。
  • 域名证书：安装有效的域名证书。
    注： 如果你的云 PBX 的一级域名不是 Yeastar 提供的标准域名 (ycmcloud.com、yeastarcloud.com 或 yeastarycm.co.za)，则必须确保已为 PBX 安装有效的域名证书，否则消息渠道会出现验证失败或无法接收消息的问题。
WhatsApp
  • 产品：WhatsApp Business Platform
  • 账户：需要准备以下两种账户
  • 电话号码：确保电话号码有效，可用于收发消息。
    注： 可在 'Meta Business Suite' 平台 中查看号码状态 (路径：账户 > WhatsApp 账户 > WhatsApp 管理工具 > 账户工具 > 电话号码)。

使用限制

了解 WhatsApp 消息渠道使用限制。

项目 说明
消息类型 支持发送文字消息和多媒体消息，其中可发送的多媒体消息类型取决于 WhatsApp。更多信息，请参见 WhatsApp 支持的多媒体文件类型。
注： 发送多媒体消息 (例如图片) 时，WhatsApp 会通过 PBX 提供的链接下载文件。因此，如果你设置了 国家地区 IP 访问防御 安全规则，需确保 PBX 允许 WhatsApp 服务器所在国家的 IP 访问，否则文件传输会失败。
消息机制 你可以接收和回复客户的消息，或主动向客户发送 WhatsApp 消息模板。
消息发送速率 支持每秒钟发送最多 80 条消息。
文件大小 支持发送最大 100 MB 的文件。
文件保留时间 文件保留时间为 72 小时。

操作步骤

步骤一、在 'Meta for Developers' 平台创建 Meta 应用

在 Meta for Developers 平台上创建一个 Meta 应用，在应用中添加电话号码，并获取 电话号码编号 和 应用密钥，后续在 PBX 上配置 WhatsApp 消息渠道时需要使用这些信息。
  1. 使用开发者账户登录 'Meta for Developers' 平台，从顶部菜单栏进入 我的应用。

  2. 创建一个 Business 类型的应用。
    1. 点击 创建应用。

    2. 完成应用设置。
      注： 在 业务资产组合 字段中，选择你的商务管理平台账户以与此应用绑定，因为需要 高级访问级别 的应用程序必须与已验证的公司关联。

  3. 在 为应用添加产品 页面，下拉找到 WhatsApp，并点击 设置。

    你将进入 WhatsApp 产品的 快速入门 页面。

  4. 在左侧导航栏，进入 WhatsApp > API 设置 > 发送和接收消息，并完成以下配置。
    1. 在 发件者 下拉列表中，点击 添加电话号码，添加自己的 WhatsApp 电话号码。

    2. 在下拉列表中选择你添加的电话号码，并记录对应的 电话号码 ID，后续需要在 PBX 上添加此号码。

      重要： 如果你使用 WhatsApp 提供的测试号码作演示或测试号码发送，则需在 接收者 下拉列表中添加收件者号码，否则消息发送会失败。

  5. 在左侧导航栏，进入 应用设置 > 基本，记录下 应用密钥，后续在 PBX 上需要使用到此信息。

步骤二、在 'Meta Business Suite' 平台获取所需凭证

在 'Meta Business Suite' 平台上创建系统用户并为用户授权，然后为此用户生成 访问口令，以允许用户访问上一步骤中创建的 Meta 应用。后续在 PBX 上配置 WhatsApp 消息渠道时需要使用此访问口令。此外，还需获取 WhatsApp 商业账户 ID，用于获取与该账户关联的消息模板。
重要： 建议使用 'Meta Business Suite' 平台上创建的访问口令，而非 'Meta for Developer' 平台的访问口令，因为后者是一个临时口令，过期后可能导致消息接收失败。
  1. 在 'Meta for Developers' 平台 的左上角，进入 应用面板 > 业务设置。

    你将进入 'Meta Business Suite' 平台 的 业务设置 页面。

  2. 进入 用户 > 系统用户，创建一个系统用户，并授予 app 访问权限。
    1. 点击 添加 创建一个 Admin 角色的系统用户。

    2. 选择创建的用户，点击 分配资产 并向用户分配应用的完全控制权限。

  3. 进入 账户 > WhatsApp 账户，将创建的用户添加到你的 WhatsApp 商业账号，并分配完全控制权限。

  4. 返回到 用户 > 系统用户，为系统用户生成一个新的访问口令，并启用 whatsapp_business_messaging 和 whatsapp_business_management 权限。
    注： 默认的口令有效期是 60 天，如果你不希望此口令过期，可选择 永不。

    弹窗中显示生成的口令。
    重要： 访问口令仅显示一次，务必确保在关闭弹窗之前已经复制并妥善保存此口令。

  5. 进入 账户 > WhatsApp 账户，点击你的 WhatsApp 账户，然后复制账户编号 (ID)。

步骤三、在 PBX 上创建并配置 WhatsApp 消息渠道

在 PBX 上，创建 WhatsApp 消息渠道并使用在前面步骤中获得的信息配置渠道，从而确保 PBX 能够连接 WhatsApp 以收发消息。

  1. 登录 PBX 管理网页，进入 讯息管理 > 消息渠道。
  2. 点击 添加，选择 WhatsApp。
  3. 在 鉴权信息 栏，填写 WhatsApp 的鉴权信息。
  4. 在 消息设置 页签，配置该渠道。
    1. 填写 WhatsApp 电话号码信息。
    2. 在 WhatsApp 账户 ID 字段，粘贴 在 'Meta Business Suite' 平台获取的账户 ID。

      PBX 会基于此账户 ID 将关联的消息模板同步到此渠道中。

    3. 在 消息目的地 下拉列表，设置通过此号码送入的消息会被送往哪个目的地。

      选项 说明
      分机 若选择此项，需在 分机 下拉列表中选择接收消息的分机。

      只有此分机用户可以接收到通过此号码送入的消息。
      消息队列 若选择此项，需在 消息队列 下拉列表中选择接收消息的队列。

      所选队列中的所有坐席都会收到队列中新会话的消息，但只有接管了会话的用户可以接收并回复后续送入的消息。
      第三方分析平台（消息通过二次开发接口传递） 若选择此项，通过此号码送入的消息会通过 API 转发到第三方消息分析平台进行进一步分析或处理。
      注： 要实现入站消息自动转发至第三方消息分析平台，需确保 PBX 系统已经已通过 API 与第三方消息分析平台对接。选择此选项后，PBX 系统就会自动将收到的消息发送到指定平台。你可以通过监控 API 事件 (30031) 新消息通知获取相关事件通知。此外，PBX 提供了完整的讯息管理 API 接口，可用于与对接的第三方消息分析平台进行进一步的消息交互。
    4. 在 允许创建会话的分机 栏，选择一个或多个分机，选择的分机可以向外部用户发送消息。

    5. 可选： 如果你想要系统自动关闭在指定时间内无任何互动的会话，勾选 自动关闭会话，并在 会话超时时间 (天) 栏中设置超时时间。

  5. 点击 保存。

步骤四、在 Meta 应用中配置 Webhook

在 'Meta for Developers' 平台，为 meta 应用配置 Webhook，以接收实时消息事件，从而确保 PBX 可接收并处理来自 WhatsApp 的消息。

  1. 使用开发者账户登录 'Meta for Developers' 平台，从顶部菜单栏进入 我的应用。

  2. 点击创建的应用，进入应用详情页。

  3. 进入 WhatsApp > 配置 ，配置消息 Webhook 并订阅 Webhook 字段，以允许 PBX 接收从 WhatsApp 传入的消息。
    1. 粘贴从 PBX 获取的 Webhook URL 和 验证令牌。

    2. 在 Webhook 字段 栏，订阅 messages Webhook 字段。

执行结果

  • WhatsApp 消息渠道的 状态 变为 ，表示你已成功创建了 WhatsApp 消息渠道。

  • 系统自动追踪并记录该渠道上发送和接收的消息数量，其中 总发送量 包含了发送成功和发送失败的所有消息数量。
    提示： 可使用时间筛选功能查看指定时间段内的消息数据。

后续步骤

发送测试消息，确认指定的坐席是否可以在 Linkus UC 客户端上成功接收和发送消息。