SMS API

借助 Contact Center AI 平台 (CCAI 平台)，您可以使用 SMS API 来处理入站和出站 SMS 消息。

身份验证

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

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

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

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

  3. 输入凭据的名称。

  4. 点击创建。

出站短信 API

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

使用此 API 时，需要考虑以下三个关键点：

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

  • 消费者可以回复此短信，并开始支持会话。

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

使用场景

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

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

其他潜在用例：

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

出站短信 API 端点

此新端点的基本 URI 为：

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

入站短信支持

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

如果最终用户回复以这种方式配置的短信，系统会将他们带到入站短信手机号码所分配到的短信队列菜单。如需了解详情，请参阅 SMS Messaging Chat Settings - Phone Number（短信聊天设置 - 电话号码）。

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
消息 字符串 是 要向消费者发送的短信 长消息：将长消息拆分为多条消息（应包含在现有的出站短信功能中） 验证：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 is invalid”
（注意：有效的手机号码：“+18882468888”，适用于美国手机号码）
未提供 end_user_number 错误 “end_user_number 是必需的”
提供了 outbound_number，但格式不正确 错误 “outbound_number is invalid”
（注意：有效的手机号码：“+18882468888”[美国手机号码]）
提供了 outbound_number，但该租户不存在此号码 错误 “找不到 outbound_number”
未提供 outbound_number 错误 “outbound_number 是必需的”
outbound_number 是非美国手机号码，但“非美国手机号码服务”未启用 错误 “未启用非美国手机号码服务”
注意：取决于非美国手机号码设置，该设置位于设置 > 通话中短信 > 非美国手机号码配置
消息为空 错误 “message is required”
outbound_number 与 end_user_number 之间的活跃聊天 错误 “外发短信失败。用户已处于有效的短信会话中。”
ticket_id 已填写，但在 CRM 中不存在 错误 “找不到工单”

短信过期

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

在给定的外呼手机号码与消费者手机号码之间建立新的短信聊天会话之前，任何短信聊天都需要结束。这包括使用该 API 发送的出站短信。如果发件人手机号码与消费者手机号码之间存在有效的现有对话，则任何出站短信都会失败。

自动聊天超时选项

您可以在“设置”>Chat”>“短信过期和全局超时”中配置自动聊天超时选项。此属性用于控制在聊天会话流程中没有活动或进度的情况下，聊天会话保持活跃状态的时间。

Chat 状态的区别

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

  • 队列选择状态下的 Chat 过期使用 API 发送的出站对话在消费者回复之前一直处于队列选择状态

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

  • 未答复的短信对话的过期时间（在工作时间内）：在特定队列的设定工作时间内，聊天在队列中保持未答复状态的时间长度，超过此时间长度后聊天会过期。

  • 未答复的短信对话过期时间（在非工作时间）对话在队列中保持未答复状态的时间长度，超过此时间后，对话会在特定队列的设置工作时间之外过期。

  • 外发短信对话超时 如果 [x] 分钟内没有任何活动，外发短信对话会话将自动过期。

Chat 状态详细信息

  • 使用 API 发送出站短信时，相应对话会被视为活跃，但不会被视为已连接

  • 这些有效的出站短信对话在消费者回复之前，会被视为处于队列选择状态

  • 当消费者回复且有客服人员分配到相应对话时，该对话即被视为“已连接”

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

  • 使用 API 发送的有效对话如果未收到消费者的回复，则会受到队列选择状态计时器的影响

  • 与客服人员建立的对话会受到出站过期计时器的影响

  • 如果消费者回复了初始消息，但系统从未分配客服人员，则聊天未连接，并且会受到“未答复的聊天过期”计时器的影响，无论是在工作时间内还是工作时间后

API 消息流和状态示例：

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

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

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

  4. 消费者发送最后一条消息 - 出站 SMS 对话超时计时器开始计时。

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

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

响应定义

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

无会话的出站短信 API

CCAI 平台提供了一个出站短信 API，该 API 可以支持出站短信，而无需任何关联的会话。

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

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

此出站短信 API 能够通过每次 API 调用发送最多 500 条消息。

使用场景

无会话 SMS 的常见用例包括：

  • 动态密码设置。

  • 验证码。

  • 预约提醒。

  • 反馈链接。

  • 营销或促销信息。

无会话的出站 API 和出站 SMS API 的不同之处在于，使用出站 SMS 时，当使用方做出响应时，系统会启动有效会话，并且可以将使用方转接到客服人员。虽然它们的使用场景类似（例如，外送通知、预约提醒），但不同之处在于消费者回复时会发生什么情况。他们可能会收到不含会话的默认“请勿回复”通知，但如果使用出站短信，他们将被转接到客服人员。

无会话的出站 SMS API 端点

相应端点的基本 URI 为：

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

添加 API 凭据

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

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

  3. 输入凭据的名称 Name。

  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 个手机号码。
消息 数组 [字符串] 是 要发送的消息。 您最多可以发送 5 条单独的消息。
每条消息的字数上限为 320 个字符，不得超过此上限。

API 响应

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

  • code: 200

  • 请求 ID

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

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

  • 代码：4xx

  • 错误消息

短信限制

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

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