Chat 平台 API 指南

此页面介绍了如何使用聊天端点，如聊天平台 API 端点中所述。

术语

为便于理解，以下是一些定义，在使用本文档时请务必牢记。

客户：在其软件中实现聊天平台 API 的 Contact Center AI 平台 (CCAI 平台) 客户。
使用方：向聊天平台 API 发出请求的软件。
最终用户：客户软件的用户，尝试与代理进行对话。

Webhook 身份验证

聊天平台 API 通过向消费者的服务器发送 webhook 请求，将聊天期间发生的事件传达给消费者。Webhook 载荷和类型在 API 规范中定义。每个 webhook 请求都包含两个标头，即 X-Signature 和 X-Signature-Timestamp。

X-Signature 包含一个网络钩子签名，格式如下： primary=<primary_signature> secondary=<secondary_signature>

主签名和次签名分别是主 webhook 密钥或次 webhook 密钥的 base64 编码 sha256 摘要，其中包含 X-Signature-Timestamp 标头和请求的 JSON 载荷的串联字符串。

以下示例展示了如何在 Ruby on Rails 示例应用中实现对 webhook 请求的授权：

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

概览

一般来说，聊天平台 API 对话的基本流程应如下所示。关键点已编号，并提供了一些注释以供参考。请注意，客户只需负责实现图中的“客户”侧，而 Contact Center AI 平台会处理图中的系统侧和客服人员侧。将它们纳入图表中仅是为了让读者了解聊天的整体流程。

下图显示了聊天平台 API 对话的流程。

创建最终用户

聊天在创建时需要有效的最终用户 ID，这意味着在创建聊天之前，最终用户必须存在于 Contact Center AI 平台系统中。
最终用户通过其 identifier 属性（由消费者提供的字符串值）进行唯一标识。如果最终用户之前使用过 Web 或移动 SDK，则他们可能已存在于系统中。POST /end_users 端点实现为幂等更新插入，因此，如果最终用户已存在，尝试再次创建他们将更新任何已更改的数据并返回最终用户的信息。

创建对话

如需使用聊天平台 API 创建对话，请按以下步骤操作：

处理新的聊天载荷：聊天初始化流程与 POST /chats 请求异步进行。因此，chat_created 事件可能会在 POST /chats 创建端点的 API 响应之前或之后收到。建议以幂等方式处理 chat_created 事件和聊天创建 API 响应，以避免出现任何消费者 bug。
创建包含转写的对话：聊天平台 API 支持创建包含现有对话转写的对话，适用于在客户的平台内（例如与聊天机器人）进行聊天，然后再将对话发送到 Contact Center AI 平台的场景。这可为回答聊天问题的客服人员提供有关聊天会话的更多信息，并有助于防止最终用户重复自己的问题。如需了解转写内容载荷格式，请参阅 chat_platform_openapi.yaml。

队列选择虚拟客服

为了简化 API 使用者的菜单选择，聊天平台 API 旨在与 Dialogflow 虚拟客服搭配使用，以帮助将新对话放入队列。

如需设置虚拟客服，您需要执行以下步骤：

为此目的创建一个指定的虚拟客服，并将其分配给队列。通过聊天平台 API 创建的所有新对话都应在此队列中创建。创建和配置新的虚拟客服不在本文档的讨论范围内。
使用 POST 或 chats 端点创建新对话时，请添加自定义上下文载荷，其中包含有关所创建对话的一些上下文，虚拟客服可以使用这些上下文来确定应将对话路由到哪个队列。上下文载荷可以包含客户定义的任何自定义数据，但必须采用以下格式，以便分配给队列的虚拟客服能够访问这些数据。
- 示例："context": {"value": {"foo": "bar" } } 将允许虚拟代理读取值为 bar 的 $session.params.context.foo。
虚拟客服（根据客户的配置）使用上下文字段中包含的数据将聊天升级到所选队列。如果目标队列中没有可用的客服人员（例如队列已过工作时间或已满负荷），则升级会被转接，并且消费者会收到一个 webhook，其中指明了转接原因和可用的转接选项。

升级改道：聊天平台 API 中的 Chat 升级支持以下改道选项（如果在 Contact Center AI 平台门户中配置）：

电子邮件：让最终用户向支持团队发送电子邮件，然后结束聊天。当最终用户选择此选项时，在电子邮件发送完毕后，客户需要使用 PATCH /chats/:id 端点在请求正文中添加以下参数，将相应对话标记为已改用其他渠道并已结束："status": "finished" , "escalation_id": <id of escalation> , 和 "deflection_channel": "email"
继续使用虚拟客服：从技术上讲，这是一个有效的分流选项，但对于使用队列选择虚拟客服而言，这没有意义，因为虚拟客服只会尝试再次升级聊天。
继续等待人工客服：此选项仅适用于升级原因代码为 over_capacity 的升级。如果最终用户选择此选项，请使用 PATCH chats/:id/escalations/:id with deflection_channel=human_agent 更新升级转移
- 外部分流链接：警告最终用户，选择分流中提供的链接将结束聊天。如果选择了链接，则结束聊天，并为 deflection_channel 参数使用 external_link

收发消息

如需发送或接收消息，请按以下步骤操作：

文本内容：如需发送文本消息，请使用 API 文档中定义的 POST /chats/:id/message 端点。如需接收消息，请监听 message_received 网络钩子事件。请注意，API 使用者将针对使用该 API 发送的所有消息（包括最终用户发送的消息）收到 message_received 事件。
照片和视频内容：照片和视频内容通过以下方式发送：从 Contact Center AI 平台获取配置的 Cloud Storage 服务的预签名上传网址，上传到存储服务，然后在消息载荷中将存储网址发送到 Contact Center AI 平台。
1. 获取预签名网址：使用 POST /v1/chats/:chat_id/photos/upload 或 POST /v1/chats/:chat_id/videos/upload endpoints 从 Contact Center AI 平台获取预签名上传网址。此端点会返回一个预签名网址，以及一组在上传文件时要转发到存储服务的字段。预签名上传具有以下限制：
  - 对于照片，Content-Type 为 image/jpeg；对于视频，Content-Type 为 video/mp4。
  - 照片大小上限为 2 MB。视频大小上限为 20 MB。
  - 过期时间为 5 分钟。
  - 客户必须先调整照片大小和方向，然后才能上传。
  - 每个预签名网址仅适用于一张照片或一个视频；如需发送多个附件，您必须为每个附件请求一个预签名网址。
2. 上传媒体文件：如需上传媒体文件，请向在 2a 中获取的预签名网址发出 POST 请求，并在请求正文中包含以下内容：
  - "file"：要上传的文件
  - 预签名网址请求的“fields”对象中返回的所有字段。
3. 将媒体文件添加到对话中：如需将媒体文件添加到对话中，请使用 POST /chats/:id/photos 或 POST /chats/:id/videos 端点。请注意，照片端点支持发送照片数组，而视频端点一次仅支持一个视频。
  - s3_path 请求正文参数应与预签名网址响应的 key 字段的值相同。
  - 如果请求成功，将返回两个字段。建议在 API 使用者中保存或缓存 media_id 到网址的映射，因为聊天消息中的所有媒体都将仅通过 media_id 进行引用。
    - url：文件所在的只读 S3 或 Cloud Storage 网址。
    - media_id：Contact Center AI 平台中媒体文件的 ID。这是媒体在聊天载荷中使用的 ID。
4. 以聊天消息的形式发送媒体文件：如需以聊天消息的形式发送媒体文件，请将以下载荷发送到 POST /chats/:id/message endpoint：
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

预期 API 响应中存在无法识别的 JSON 键

所有 API 更新都向后兼容。我们保留随时在现有 API 响应中引入新 JSON 键的权利。我们建议您采取防御性措施来处理响应，即忽略任何无法识别的键，以保持持续的功能。

Chat 平台 API 指南 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

术语