通话端点

调用 API 端点可提供对调用对象的访问权限。每次拨打和接听 Contact Center AI 平台 (CCAI Platform) 的电话时，系统都会创建一个通话对象。

以下是调用 API 端点：

调用对象

以下是调用对象的示例：

[
  {
    "id": 0,
    "parent_id": 0,
    "lang": "en",
    "call_type": "Voice Scheduled (API)",
    "status": "scheduled",
    "created_at": "2018-06-07T19:49:52.896Z",
    "queued_at": "2018-06-07T19:49:52.896Z",
    "assigned_at": "2018-06-07T19:49:52.896Z",
    "connected_at": "2018-06-07T19:49:52.896Z",
    "ends_at": "2018-06-07T19:49:52.896Z",
    "scheduled_at": "2018-06-07T19:49:52.896Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": 0,
    "has_feedback": true,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "string",
    "out_ticket_url": "string",
    "verified": true,
    "recording_url": "string",
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_details": "string",
    "fail_reason": "nothing",
    "support_number": "string",
    "selected_menu": {
      "id": 0,
      "name": "string",
      "parent_id": 0,
      "position": 0,
      "deleted": true,
      "hidden": "string",
      "menu_type": "ivr_menu",
      "output_msg": "string"
    },
    "menu_path": {
      "items_count": 0,
      "name": "string",
      "materialized_path": "string"
    },
    "agent_info": {
      "id": 0,
      "name": "string",
      "last_name": "string",
      "first_name": "string",
      "agent_number": "string",
      "avatar_url": "string"
    },
    "end_user": {
      "id": 0,
      "identifier": "string",
      "out_contact_id": "string"
    },
    "photos": [
      {
        "id": 0,
        "photo_type": "photo",
        "url": "string"
      }
    ],
    "videos": [
      {
        "id": 0,
        "url": "string"
      }
    ],
    "transfers": [
      {
        "id": 0,
        "status": "transferring",
        "fail_reason": "nothing",
        "created_at": "2018-06-07T19:49:52.896Z",
        "from_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "to_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "from_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        },
        "to_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        }
      }
    ],
    "participants": [
      {
        "id": 0,
        "type": "end_user",
        "status": "waiting",
        "call_id": 0,
        "user_id": 0,
        "end_user_id": 0,
        "call_duration": 0,
        "hold_duration": 0,
        "connected_at": "2018-06-07T19:49:52.896Z",
        "ended_at": "2018-06-07T19:49:52.896Z",
        "fail_reason": "nothing"
      }
    ]
  }
]

通话状态定义

状态字段可以处于以下任何一种状态：

通话状态 说明
正在选择 最终用户已致电联络中心，但仍在浏览菜单选项，尚未进入叶菜单时所处的状态。
已加入队列 最终用户选择叶菜单节点并启动呼叫请求以广播或多播给客服人员后发生的状态。
已分配 当代理被选中来接听最终用户来电时发生的状态。当客服人员接听来电时，会发生此事件。
正在连接 在分配代理后，最终用户与代理之间正在建立连接时发生的状态。
已连接 通话已建立连接，并且客服人员和最终用户都已加入通话时所处的状态。
已完成 通话已接通后结束时发生的状态。
失败 通话在成功连接之前结束时发生的状态。我们还会提供失败原因，以便您了解更多详细信息。
正在切换 在尝试连接时调用失败，而 CCAI 平台尝试将调用与不同的 VoIP 提供方连接时发生的状态。
已恢复 在回拨失败的通话时发生的状态。新通话是原始通话的子通话。恢复了回调在完成时没有出现错误的注释。
已安排 最终用户已使用 In-Web 或 In-App 安排了未来的通话时出现的状态。
仅行动号召广告系列 一种状态，指由客户自己的电话服务提供商处理的通话连接到我们的 iOS 或 Android SDK 时所处的状态。
仅行动号召广告系列已完成 当由客户自己的电话服务提供商处理的通话连接到我们的 iOS 或 Android SDK 并结束时发生的状态
折射 根据过量队列或下班后通话的配置而发生的状态。转接选项包括语音信箱、安排通话等。转接率因渠道（应用内、IVR、网站内）而异
语音信息 最终用户被转接到语音信息选项，并选择留言以供日后收听时发生的状况。当最终用户正在留言时，系统会处于此状态
收到了语音信息 最终用户留下语音信息后，客服人员尚未收听该语音信息时所处的状态
语音信息已读 代理已打开语音信息以进行收听时所处的状态。

通话类型定义

call_type 字段只能是以下值之一：

通话类型 说明
语音外呼 (API) 通过 Outbound Call API 发起的通话。
Voice Inbound (API) 通过 Incoming Call API 发起的调用。
Voice Scheduled (API) 通过 Scheduled Call API 发起的通话。

常见的 API 响应代码

以下是最常见的 API 响应：

响应代码 含义
201 API 请求已成功，并将创建通话
202 API 请求已成功，但需要在 widget 内进行人工干预才能完成操作
400 通话类型无效 - 请确保通话类型受支持
400 客服人员无法接听此来电
400 缺少参数 - 请检查以确保已添加必需参数
404 找不到资源 - 请检查您的子网域

外拨电话 - end_user_number

参数 必需 数据类型 定义
call_tye TRUE 字符串 调用 tye 以创建。“语音出站 (API)”、“OutboundCall”（已弃用）目前可用
agent_email TRUE 字符串 将分配给外拨电话的客服人员的电子邮件地址。
ticket_id FALSE 字符串 CRM 工单 ID，然后拨打与该工单关联的最终用户的电话。
end_user_number FALSE 字符串 将拨打的最终用户手机号码。ticket_id 的优先级高于 end_user_number。
outbound_number FALSE 字符串 格式正确的出站号码，可通过“设置”>“电话号码”>“电话号码管理”进行管理。如果为空，则使用默认的出站号码
lang FALSE 字符串 会议的字幕语言。使用 ISO 639-1 代码。（默认值：“en”）

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/calls

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

错误：客服人员无法接听此电话

此示例演示了客服人员无法接听电话时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
响应：错误：客服人员无法接听此电话
{
    "message": "Agent is not available to take this call"
}

状态代码：400

使用最终用户号码创建出站通话

此示例演示了如何针对特定最终用户号码发起出站呼叫。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
响应：使用 end_user_number 创建出站通话
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.jpg"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

使用工单 ID 创建外拨电话

此示例演示了如何创建具有特定支持请求 ID 的出站通话。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
响应：创建包含 ticket_id 的出站调用
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

错误：必须提供支持请求 ID 或最终用户号码

此示例演示了需要提供支持请求 ID 或最终用户号码但未提供时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

响应：错误：需要提供支持请求 ID 或最终用户号码

{
    "message": "ticket_id or end_user_number required"
}

状态代码：400

错误：代理电子邮件地址无效

此示例演示了当为代理提供的电子邮件地址无效时出现的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

回答：错误：智能体电子邮件地址无效

{
    "message": "Not a valid agent email"
}

状态代码：400

错误：必须提供代理电子邮件地址

此示例演示了未为代理提供电子邮件地址时出现的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

回答：错误：必须提供代理电子邮件地址

{
    "message": "Agent email required"
}

状态代码：400

错误：代理无权拨打电话

此示例演示了当指定代理无权拨出电话时发生的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
响应：错误：代理无权拨打电话
{
    "message": "Agent does not have access to make calls"
}

状态代码：400

错误：end_user_number 格式不正确

此示例演示了所提供的最终用户号码格式不正确的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
响应：错误：end_user_number 格式不正确
{
    "message": "end_user_number is not well-formed"
}

状态代码：400

错误：未找到联系人

此示例演示了所提供的联系人不存在时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
响应：错误：未找到联系人
{
    "message": "Contact not found"
}

状态代码：400

已接受：需要选择一个外拨号码

在此示例中，系统接受了拨出电话，但客服人员必须在拨打电话之前选择要使用的拨出号码。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
响应
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

状态代码：200

错误：通话类型无效

此示例演示了提供的调用类型无效时的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
回答：错误：通话类型无效
{
    "message": "Invalid call type"
}

状态代码：400

通过多个外拨号码提示通话适配器

在这种情况下，通话适配器会收到多个出站号码。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
响应
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

状态代码：200

已接受：客服人员必须使用工单 ID 拨打外拨电话

此示例演示了一个请求，其中代理必须根据提供的工单 ID 拨打出站电话。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

状态代码： 202

外拨电话 - ticket_id

参数 必需 数据类型 定义
call_type TRUE 字符串 要创建的通话类型。“语音出站 (API)”、“OutboundCall”（已弃用）目前可用
agent_email TRUE 字符串 将分配给外拨电话的客服人员的电子邮件地址。
ticket_id FALSE 字符串 CRM 工单 ID，然后拨打与该工单关联的最终用户的电话。
end_user_number FALSE 字符串 将拨打的最终用户手机号码。ticket_id 的优先级高于 end_user_number。
outbound_number FALSE 字符串 格式正确的出站号码，可通过“设置”>“电话号码”>“电话号码管理”进行管理。如果为空，则使用默认的出站号码
lang FALSE 字符串 会议的字幕语言。使用 ISO 639-1 代码。（默认值：“en”）

端点：

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}​/apps/api/v1/calls

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "ticket_id": "123123",
    "lang": "en"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

错误：必须提供支持请求 ID 或最终用户号码

在此示例中，缺少工单 ID 或最终用户号码的失败情形，但这是必需的。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

响应：错误：需要提供支持请求 ID 或最终用户号码

{
    "message": "ticket_id or end_user_number required"
}

状态代码：400

错误：必须提供代理电子邮件地址

在此示例中，我们展示了未提供但需要提供代理电子邮件地址的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
回答：错误：必须提供代理电子邮件地址
{
    "message": "Agent email required"
}

状态代码：400

使用最终用户号码创建出站通话

在此示例中，我们将展示如何通过提供最终用户号码来创建出站通话。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
响应：使用 end_user_number 创建出站通话
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reaso": "not_voicemail",
    "deflection": "n_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

错误：通话类型无效

在此示例中，我们展示了所提供的调用类型无效时的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
回答：错误：通话类型无效
{
    "message": "Invalid call type"
}

状态代码：400

通过多个外拨号码提示通话适配器

在此示例中，我们将展示如何使用多个出站手机号码提示通话适配器。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

状态代码： 202

已接受：客服人员必须使用工单 ID 拨打外拨电话

在此示例中，我们展示了如何使用工单 ID 发起出站呼叫，以及客服人员如何接受请求。

请求

标头：

键 值 说明
Content-Type application/json
***正文：*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***状态代码：*** 202 #### 错误：客服人员无权拨打电话 在此示例中，我们展示了提交了通话创建请求但客服人员无权拨打外呼电话的失败情形。 ##### 请求 ***标头：***
键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
响应：错误：代理无权拨打电话
{
    "message": "Agent does not have access to make calls"
}

状态代码：400

使用工单 ID 创建外拨电话。

在此示例中，我们展示了使用工单 ID 创建出站调用的场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
响应：创建包含 ticket_id 的出站调用
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

已接受：需要选择一个外拨号码

在此示例中，我们展示了以下场景：创建了外拨电话请求，需要选择外拨号码，然后接受了该请求。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

状态代码： 202

错误：客服人员无法接听此电话

在此示例中，我们展示了创建了通话但客服人员无法接听通话的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
响应：错误：客服人员无法接听此电话
{
    "message": "Agent is not available to take this call"
}

状态代码：400

错误：最终用户号码格式不正确

在此示例中，我们展示了所提供的最终用户手机号码格式不正确的失败情形。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
响应：错误：end_user_number 格式不正确
{
    "message": "end_user_number is not well-formed"
}

状态代码：400

错误：代理电子邮件地址无效

在此示例中，我们展示了所提供的客服人员电子邮件地址无效时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
回答：错误：智能体电子邮件地址无效
{
    "message": "Not a valid agent email"
}

状态代码：400

错误：未找到联系人

在此示例中，我们展示了无法找到所提供联系信息的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
响应：错误：未找到联系人
{
    "message": "Contact not found"
}

状态代码：400

来电

参数 必需 数据类型 定义
call_type TRUE 字符串 要创建的通话类型。使用“Voice Inbound (API)”或“IncomingCall”（已弃用）创建来电。
menu_id TRUE 整数 要将通话归因到的菜单的 ID。仅接受 IVR 和 Web 菜单 ID。
end_user_number TRUE 字符串 将拨打的最终用户手机号码。如果同时传入了 ticket_id 和 end_user_number，则以 ticket_id 为准。
lang FALSE 字符串 会议的字幕语言。使用 ISO 639-1 代码。（默认值：“en”）
ticket_id FALSE 字符串 CRM 支持请求 ID。系统将拨打与工单关联的最终用户手机号码。如果同时传入了 ticket_id 和 end_user_number，则以 ticket_id 为准。
outbound_number FALSE 字符串 用于拨出手机的手机号码。如果未传入输入内容或输入内容无效，系统将使用默认的全球出站手机号码。外拨号码可在“设置”>“队列”>“修改 / 查看”>“选择队列”>“外拨电话号码”中进行管理。
recording_permission FALSE 字符串 只有当“通话录音选项”功能设置为“征求用户录音许可”时，系统才会评估该值。您可以在“设置”>“队列”>“修改 / 查看”>“选择队列”>“通话录制选项”中进行配置。如果值为“recording_permission_not_asked”（默认）或“recording_permission_denied”，则不会录制通话。如果值为“recording_permission_granted”，则系统会录制通话。

端点：

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

错误：最终用户号码格式不正确

在此示例中，我们展示了失败场景，即创建了来电，但提供的最终用户号码格式不正确。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
响应：错误：end_user_number 格式不正确
{
    "message": "end_user_number is not well formed"
}

状态代码：400

错误：菜单处于“手动重定向”状态，无法接听来电

在此示例中，我们展示了这样一种失败情形：呼叫被路由到某个菜单 ID，但该菜单处于手动重定向状态，因此无法接收来电。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：菜单处于“手动重定向”状态，无法接听电话
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

状态代码：400

错误：通话类型无效

在此示例中，我们展示了创建了来电但提供的通话类型无效的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答：错误：通话类型无效
{
    "message": "Invalid call type"
}

状态代码：400

错误：必须提供菜单 ID

在此示例中，我们展示了创建了来电但提供的菜单 ID 无效的失败场景。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：必须提供 menu_id
{
    "message": "menu_id is required"
}

状态代码：400

错误：仅允许使用 IVR 和移动菜单 ID

在此示例中，我们展示了失败场景，即创建了来电，但提供的菜单 ID 不是 IVR 或移动菜单 ID。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：仅允许使用 IVR 和移动菜单 ID
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

状态代码：400

创建具有最终用户号码的来电

此示例演示了如何创建具有特定最终用户号码的来电。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
响应：使用 end_user_number 创建来电
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": "2019-09-10T00:19:14.421Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

错误：菜单处于“非营业时间”状态，无法接听来电

此示例演示了当提供的菜单 ID 处于非营业时间状态时发生的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：菜单处于“非营业时间”状态，无法接听来电
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

状态代码：400

错误：语言不可用

此示例演示了在指定语言不可用时，请求失败的情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答：错误：语言不可用
{
    "message": "Language 'fr' is not available"
}

状态代码：400

创建包含工单 ID 的来电

此示例演示了如何请求创建具有关联工单 ID 的来电。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：创建包含 ticket_id 的来电
{
    "id": 519,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T05:12:26.000Z",
    "queued_at": "2019-09-10T05:12:26.295Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": "76517",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 826,
            "type": "end_user",
            "status": "waiting",
            "call_id": 519,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T05:12:26.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

错误：找不到语言

此示例演示了找不到所提供语言时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：未找到语言
{
    "message": "Language 'xy' is not found"
}

状态代码：400

错误：找不到 menu_id

此示例演示了在找不到所提供的菜单 ID 时出现的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：找不到 menu_id
{
    "message": "menu_id 9999 is not found"
}

状态代码：400

错误：menu_id 格式不正确

此示例演示了当提供的菜单 ID 不正确时出现的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答：错误：menu_id 格式不正确
{
    "message": "menu_id is not well formed"
}

状态代码：400

错误：必须提供最终用户号码

在此示例中，我们展示了失败场景，即创建了来电，但未提供最终用户手机号码。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
回答：错误：必须提供 end_user_number
{
    "message": "end_user_number is required"
}

状态代码：400

预约的通话

参数 必需 数据类型 定义
call_type TRUE 字符串 要创建的通话类型。使用“Voice Scheduled (API)”或“ScheduledCall”（已弃用）创建预定通话。
menu_id TRUE 整数 要将通话归因到的菜单的 ID。仅接受移动和网站菜单 ID。
call_id FALSE 整数 上一次通话的通话 ID，将作为新创建的预定通话的父通话进行关联。使用通话 ID 时，menu_id 可以是可选的。
end_user_number TRUE 字符串 将拨打的最终用户手机号码。如果同时传入了 ticket_id 和 end_user_number，则以 ticket_id 为准。
lang FALSE 字符串 会议的字幕语言。使用 ISO 639-1 代码。（默认值：“en”）
ticket_id FALSE 字符串 CRM 支持请求 ID。系统将拨打与工单关联的最终用户手机号码。如果同时传入了 ticket_id 和 end_user_number，则以 ticket_id 为准。
scheduled_at TRUE 字符串 通话的预定时间。采用 ISO 8601 格式，表示未来的有效时间。
recording_permission FALSE 字符串 只有当“通话录音选项”功能设置为“征求用户录音许可”时，系统才会评估该值。您可以在“设置”>“队列”>“修改 / 查看”>“选择队列”>“通话录制选项”中进行配置。如果值为“recording_permission_not_asked”（默认）或“recording_permission_denied”，则不会录制通话。如果值为“recording_permission_granted”，则系统会录制通话。

端点：

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

错误：end_user_number 格式不正确

此示例演示了因 end_user_number 格式不正确而导致的失败。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：end_user_number 格式不正确
{
    "message": "end_user_number is not well formed"
}

状态代码：400

错误：菜单处于“手动重定向”状态，无法接听来电

此示例演示了当指定的菜单 ID 设置为菜单重定向且无法接听电话时出现的故障。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：菜单处于“手动重定向”状态，无法接听电话
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

状态代码：400

错误：通话类型无效

此示例演示了当发出请求且调用类型无效时出现的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答：错误：通话类型无效
{
    "message": "Invalid call type"
}

状态代码：400

错误：必须提供 menu_id

此示例展示了在未提供菜单 ID 但菜单 ID 为必需项时，请求和响应会是什么情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：必须提供 menu_id
{
    "message": "menu_id is required"
}

状态代码：400

错误：仅允许使用移动设备和网站菜单 ID

此示例演示了当提供的菜单 ID 不是网站或移动菜单 ID 时，请求会失败。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：仅允许使用移动设备和网站菜单 ID
{
    "message": "Only mobile and web menu IDs are permitted"
}

状态代码：400

使用菜单 ID 创建预定通话

此示例演示了如何创建具有特定菜单 ID 的预定通话。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：使用菜单 ID 创建预定通话
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

使用通话 ID 创建预定通话

此示例演示了如何创建具有特定通话 ID 的预定通话。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "call_id": 514,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：创建具有通话 ID 的预定通话
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

状态代码：201

错误：菜单处于“非营业时间”状态，无法接听来电

在此示例中，我们展示了失败场景，即创建了预定通话，但所提供的菜单不在服务时间范围内，因此无法接听来电。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：菜单处于“非营业时间”状态，无法接听来电
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

状态代码：400

错误：语言不可用

此示例演示了指定语言无效时的失败情况。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答：错误：语言不可用
{
    "message": "Language 'fr' is not available"
}

状态代码：400

错误：找不到语言

在此示例中，我们展示了这样一种失败场景：创建了预定通话，但语言无效或不可用。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：未找到语言
{
    "message": "Language 'xy' is not found"
}

状态代码：400

错误：找不到菜单 ID

在此示例中，我们展示了失败场景，即创建了预定通话，但提供的菜单 ID 无效且未找到。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
响应：错误：找不到菜单 ID
{
    "message": "menu_id 9999 is not found"
}

状态代码：400

错误：菜单 ID 格式不正确

在此示例中，我们展示了失败场景，即创建了预定通话，但提供的菜单 ID 格式不正确。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答：错误：menu_id 格式不正确
{
    "message": "menu_id is not well formed"
}

状态代码：400

错误：必须提供最终用户号码

在此示例中，我们展示了失败场景，即创建了预定通话，但未提供最终用户号码。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答：错误：必须提供 end_user_number
{
    "message": "end_user_number is required"
}

状态代码：400

错误：必须提供 scheduled_at

在此示例中，我们展示了失败场景，即创建了预定调用，但缺少必需的预定时间值。

请求

标头：

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
响应：错误：必须提供 scheduled_at
{
    "message": "scheduled_at is required"
}

状态代码：400

在通话期间获取预留的数据属性

端点

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

请求和响应示例

本部分包含该端点的请求和响应示例。

成功

此示例展示了成功通话。

请求

网址变量

键 值 说明
id 整数 （必填）
响应
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

状态代码 0

在通话期间更新预留的数据属性

端点

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

网址变量

键 值 说明
id 整数 （必填）

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

在会话期间将数据参数传递给虚拟代理

如需了解如何在通话会话期间使用应用 API 将数据参数传递给虚拟助理，请参阅在会话期间将数据参数传递给虚拟助理。