SMS API

借助 Contact Center AI Platform (CCAI Platform)，您可以使用 SMS API 处理入站和出站短信。

身份验证

如需使用 SMS API，您需要凭据。

如需为 SMS API 创建凭据，请按以下步骤操作：

  1. 在 CCAI Platform 门户中，依次点击设置 > 开发者设置 > API 凭据管理 。

  2. 点击 + 添加 API 凭据 按钮。系统会打开添加 API 凭据 消息。

  3. 输入凭据的名称 。

  4. 点击创建 。

出站短信 API

出站短信 API 提供了一个用于发起出站短信的端点。这样，您就可以通过编程方式向消费者发送短信。

使用此 API 时，请注意以下三个要点：

  • 此服务并非旨在一次发送数万条消息， 而是旨在发送事件驱动型消息。

  • 消费者可以回复短信并发起支持会话。

  • 如果您需要在同一天向同一号码发送多条短信，此 API 将无法正常运行。

使用场景

出站短信 API 的示例使用场景基于事件。例如，如果您想通知消费者其订单已准备好取货，并让他们可以选择回复。发送出站短信时，系统会创建一个活跃会话；当客户回复时，系统会将他们转接到客服人员。

此 API 与 无会话出站 短信 API 的区别在于，使用 无会话 API 时，您只需发送通知，如果消费者 回复，他们会收到一条默认消息（如果已配置），并且不会被 转接到客服人员。

其他潜在使用场景：

  • 账号登录。
  • 账号活动。
  • 重要的账号使用事件。
  • 检测已连接的设备问题。
  • 按需服务（例如送货和拼车）的预计到达时间通知。
  • 预约提醒。
  • 主动服务或账号提醒。
  • 双重身份验证（需要客户拥有现有的代码生成器和服务流程）。

出站短信 API 端点

此新端点的基本 URI 为：

POST https://<subdomain>.<domain>/apps/api/v1/sms

入站短信支持

如果环境想要支持入站短信回复，则还需要将出站号码设置为分配给队列的入站短信号码。每个短信手机号码只能分配给一个 队列。如需了解详情，请参阅：常规短信聊天配置。

如果最终用户回复以这种方式配置的短信，他们将被带到入站短信手机号码分配到的短信队列菜单。如需了解详情，请参阅短信聊天设置 - 电话号码。

API 操作

本部分概述了 API 操作、正文参数和响应代码。

正文和参数

API 请求的正文中应包含以下字段：

字段名称 类型 必需 说明 值 备注
agent_id 整数 否 如果提供的号码之间不存在聊天，则与此 ID 对应的客服人员将被分配到新聊天。如果客服人员已连接到现有聊天，则系统将代表他们发送消息。
agent_email 字符串 否 客服人员的电子邮件地址。
chat_type 字符串 是 短信 SMSAP
chat_subtype 字符串 是 api_initiated
end_user_number 字符串 是 要接收短信的号码 验证：有效的手机号码：美国手机号码的格式为 +18882468888
outbound_number 字符串 是 用于发送短信的出站手机号码 验证：a) 手机号码必须是与租户关联的短信手机号码，b) 缺少手机号码，c) 手机号码格式不正确：美国手机号码的格式为 +18882468888
message 字符串 是 要发送给消费者的短信 长消息：将长消息拆分为多条消息（应包含在现有的出站短信功能中） 验证：a) 缺少消息，b) 消息超出最大字符数 (x)
ticket_id id 否 将会话与特定的 CRM 工单 ID 相关联 注意：系统会忽略无效的工单 ID。

错误和成功

场景 预期结果 复制
已启用短信服务
已启用出站短信服务
chat_type 值为“OutboundSMSAPI”
end_user_number 已提供且格式正确
outbound_number 已提供且格式正确
对于非美国手机号码：已启用非美国手机号码
已提供消息
outbound_number 和 end_user_number 之间没有活跃聊天		 成功 (200) 成功响应示例
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
已提供客服人员 ID 和客服人员电子邮件地址 错误 只能提供 agent_id 或 agent_email 之一。
已提供客服人员 ID 或客服人员电子邮件地址
客服人员未连接到现有聊天		 错误 出站短信失败。客服人员未连接到聊天。
未启用短信服务 错误 “未启用短信服务”。
未启用出站短信服务 错误 “未启用出站短信服务”
未提供 chat_type 错误 “需要提供 chat_type”
已提供 chat_type，但未设置为“sms” 错误 “需要提供有效的 chat_type”
已提供 end_user_number，但格式不正确 错误 “end_user_number 无效”
（注意：美国手机号码的有效格式为“+18882468888”）
未提供 end_user_number 错误 “end_user_number 为必填项”
已提供 outbound_number，但格式不正确 错误 “outbound_number 无效”
（注意：美国手机号码的有效格式为“+18882468888”）
已提供 outbound_number，但该租户不存在此号码 错误 “找不到 outbound_number”
未提供 outbound_number 错误 “outbound_number 为必填项”
outbound_number 是非美国手机号码，但未启用“非美国手机号码服务” 错误 “未启用非美国手机号码服务”
注意：取决于 非美国手机号码 设置，位于 设置 > 通话中短信 > 非美国手机号码配置
消息为空 错误 “message 为必填项”
outbound_number 和 end_user_number 之间存在活跃聊天 错误 “出站短信失败。消费者已处于活跃的短信会话中。”
已填写 ticket_id，但 CRM 中不存在该 ID 错误 “找不到工单”

短信过期

出站短信会在发送后立即生效。

在给定的出站手机号码和消费者手机号码之间建立新的短信聊天会话之前，需要结束所有短信聊天 。这包括使用 API 发送的出站短信。如果出站手机号码和消费者手机号码之间存在活跃聊天，则任何出站短信都会失败。

自动聊天超时选项

自动聊天超时选项在设置 > Chat > 短信过期和全局超时 中配置。这样，您就可以控制聊天会话在聊天会话流程中没有活动或进度的情况下保持活跃的时间。

Chat 状态区分

以下是聊天流程状态更改之间的区别：

  • 队列选择状态聊天过期使用 API 发送的出站聊天在消费者 回复之前被视为处于队列选择状态

    任何未超出队列选择状态的聊天会话。这包括消费者未回复的已发送出站短信。您可以定义聊天在此状态下可以保留多长时间，然后过期（消息已发送，消费者未在计时器内回复 - 聊天过期）。

  • 未回复的短信聊天过期（在营业时间内）聊天在特定队列的设置营业时间内可以保持未回复状态的时间长度，然后过期。

  • 未回复的短信聊天过期（在营业时间外）聊天在特定队列的设置营业时间外可以保持未回复状态的时间长度，然后过期。

  • 出站短信聊天超时 如果 [x] 分钟内没有 任何活动，出站短信聊天会话将自动过期。

Chat 状态详情

  • 使用 API 发送出站短信时，聊天被视为活跃 但未连接

  • 这些活跃 的出站短信聊天在消费者回复之前被视为处于队列选择状态

  • 一旦消费者回复且聊天分配给客服人员，聊天即被视为已连接

Chat 状态对应用计时器的影响

  • 使用 API 发送的活跃 聊天（消费者未回复）受队列选择状态计时器的约束

  • 连接到客服人员的聊天受出站过期计时器的约束

  • 如果消费者回复了初始消息，但从未分配客服人员，则聊天未连接 ，并且受未回复的聊天过期计时器的约束（在营业时间内或之后）

API 消息流和状态示例：

  1. 使用 API 向消费者发送短信 - 聊天处于队列选择状态，未连接到客服人员

  2. 队列选择状态聊天过期计时器启动。如果消费者未在计时器阈值内回复，Chat 将超时并结束。

  3. 消费者回复聊天 - 聊天现在已连接到客服人员。

  4. 消费者发送最后一条消息 - 出站短信聊天超时计时器启动。

  5. 达到出站短信聊天超时计时器阈值 - 聊天结束。

没有聊天关闭计时器 - 对于 API 发起的出站短信会话， 聊天关闭计时器 不会运行，因此即使在消费者回复消息后，聊天作为入站 聊天进入时，也不会发生聊天 关闭事件。

响应定义

API 会使用单个调用对象进行响应，如 /calls 中的模型所示。

无会话出站短信 API

CCAI Platform 提供了一个出站短信 API，该 API 可以支持没有关联会话的出站短信。

此 API 调用会发起非会话关联的短信，这些短信可以在使用 CCAI Platform 的现有工作流期间触发。

如果仅向消费者发送一次性消息，并且无需打开 CRM 工单，则最好使用无会话短信。

此出站短信 API 允许您在每次 API 调用中发送最多 500 条消息。

使用场景

无会话短信的常见使用场景包括：

  • 一次性密码设置。

  • 验证码。

  • 预约提醒。

  • 反馈链接。

  • 营销或促销消息。

无会话出站 API 和 出站短信 API 的不同之处在于， 使用出站短信时，当消费者回复时，系统会发起活跃会话，并且 可以将他们转接到客服人员。虽然它们的使用场景类似（送货通知、预约提醒），但不同之处在于消费者回复时会发生什么情况。使用无会话 API 时，他们可能会收到一条默认的“请勿回复”通知，但使用出站短信时，他们将被转接到客服人员。

无会话出站短信 API 端点

此端点的基本 URI 为：

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

添加 API 凭据

  1. 在 CCAI Platform 门户中，依次点击设置 > 开发者设置 > API 凭据管理 。

  2. 点击 + 添加 API 凭据 按钮。系统会打开添加 API 凭据 消息。

  3. 输入凭据的名称名称 。

  4. 点击创建 。

发送短信

如需发送无会话出站短信，请调用 POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms 并 传递以下请求参数：

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
字段名称 类型 必需 说明 备注
from_phone 字符串 是 将用于发送消息的手机号码。 必须是有效的美国号码。
如果出现以下情况，API 调用将返回错误：
* 手机号码不是与租户关联的短信手机号码
* from_phone 字段为空
* 手机号码不符合正确的格式。例如，以下号码是有效的美国手机号码：+18882468888
to_phones 数组 [字符串] 是 将用于接收消息的手机号码。 为确保 API 调用成功：
* 确认您拥有有效的手机号码，例如 +18882468888
每次 API 调用最多可以包含 100 个手机号码。
messages 数组 [字符串] 是 要发送的消息。 您最多可以发送 5 条单独的消息。
每条消息的长度上限为 320 个字符，不得超出此限制。

API 响应

如果 API 调用成功，您将看到：

  • code: 200

  • 请求 ID

    请务必在系统记录中记录请求 ID。如果您需要排查问题，支持团队将需要请求 ID 来提供帮助。

如果 API 调用失败，您将看到：

  • code: 4xx

  • 错误消息

短信限制

  • API 每分钟最多处理 300 条消息。

  • 所有未处理的消息将在 2 小时后过期。