通话端点

通话 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 Platform 尝试通过其他 VoIP 提供商连接通话时，就会出现此状态。
已恢复 回拨失败的通话时出现的状态。这个新调用是原始调用的子调用。恢复的备注，表示回调已完成且没有错误。
已安排 当最终用户使用网页内或应用内功能安排了未来通话时，就会出现此状态。
仅限行动 当由客户自己的电话服务提供商处理的通话连接到我们的 iOS 或 Android SDK 时，就会出现这种状态。
仅操作已完成 由客户自己的电话服务提供商处理的通话连接到我们的 iOS 或 Android SDK 并结束时发生的状态
折射 根据超负荷队列或非工作时间来电的配置而发生的状态。转移选项包括语音信箱、预约通话等。分流率因渠道（应用内、IVR、网页内）而异
语音信息 当最终用户被转接到语音信息选项，并选择留下语音信息以便稍后收听时，就会出现此状态。当最终用户正在留言时，系统会显示此状态
收到了语音信息 最终用户留下语音信息后，客服人员尚未收听该语音信息的状态
语音信息已读 当客服人员打开语音信息进行收听时，会显示此状态。

通话类型定义

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

通话类型 说明
Voice Outbound (API) 通过 Outbound Call API 拨打的外拨电话。
Voice Inbound (API) 通过 Incoming Call API 发起的通话。
Voice Scheduled (API) 通过 Scheduled Call API 发起的通话。

常见 API 响应代码

以下是最常见的 API 响应：

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

外拨电话 - end_user_number

参数 必填 数据类型 含义说明
call_tye TRUE 字符串 调用 tye 以创建。“Voice Outbound (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

Headers:

键 值 说明
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"
}

请求和响应示例

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

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

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

请求

Headers:

键 值 说明
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

使用最终用户号码创建外拨电话

此示例演示了如何针对特定最终用户号码进行外拨电话。

请求

Headers:

键 值 说明
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 的外拨电话。

请求

Headers:

键 值 说明
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"
}
Response: Create an outbound call with 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 或最终用户号码但未提供时的失败情况。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

Response: Error : ticket_id or end_user_number required

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

状态代码：400

错误：代理邮箱无效

此示例演示了当为代理提供的电子邮件地址无效时发生的失败。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

Response: Error : Not a valid agent email

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

状态代码：400

错误：必须提供代理邮箱

此示例演示了未向代理提供电子邮件地址时发生的失败。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

Response: Error : Agent email required

{
    "message": "Agent email required"
}

状态代码：400

错误：客服人员无权拨打电话

此示例演示了在指定代理无权拨打去电时发生的失败。

请求

Headers:

键 值 说明
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 格式不正确

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

请求

Headers:

键 值 说明
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"
}
Response: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

状态代码：400

错误：未找到联系人

此示例演示了所提供的联系人不存在的失败场景。

请求

Headers:

键 值 说明
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

已接受：需要选择一个去电号码

在此示例中，外拨电话已被接受，但客服人员必须先选择要使用的外拨号码，然后才能拨打电话。

请求

Headers:

键 值 说明
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

错误：通话类型无效

此示例演示了提供的通话类型无效的失败场景。

请求

Headers:

键 值 说明
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

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

在这种情况下，通话适配器会提示多个外拨号码。

请求

Headers:

键 值 说明
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 拨打外拨电话。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

状态代码：202

Outbound Call - ticket_id

参数 必填 数据类型 含义说明
call_type TRUE 字符串 要创建的通话类型。“Voice Outbound (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

Headers:

键 值 说明
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 或最终用户号码缺失，但这些信息是必需的，因此导致了失败。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

Response: Error : ticket_id or end_user_number required

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

状态代码：400

错误：必须提供代理邮箱

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

请求

Headers:

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Response: Error : Agent email required
{
    "message": "Agent email required"
}

状态代码：400

使用最终用户号码创建外拨电话

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

请求

Headers:

键 值 说明
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

错误：通话类型无效

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

请求

Headers:

键 值 说明
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

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

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

请求

Headers:

键 值 说明
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 发起外拨电话，以及坐席如何接受请求。

请求

Headers:

键 值 说明
Content-Type application/json
***Body:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***Status Code:*** 202 #### Error : Agent does not have access to make calls In this example we show the failure scenario where a call creation request is submitted but the agent does not have access to be able to make outbound calls. ##### 请求 ***标头：***
键 值 说明
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 创建外拨电话的场景。

请求

Headers:

键 值 说明
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"
}
Response: Create an outbound call with 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

已接受：需要选择一个去电号码

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

请求

Headers:

键 值 说明
Content-Type application/json

正文：

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

状态代码：202

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

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

请求

Headers:

键 值 说明
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

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

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

请求

Headers:

键 值 说明
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"
}
Response: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

状态代码：400

错误：代理邮箱无效

在此示例中，我们展示了提供的代理电子邮件无效的失败场景。

请求

Headers:

键 值 说明
Content-Type application/json

正文：

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Response: Error : Not a valid agent email
{
    "message": "Not a valid agent email"
}

状态代码：400

错误：未找到联系人

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

请求

Headers:

键 值 说明
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

Headers:

键 值 说明
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"
}

请求和响应示例

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

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

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

请求

Headers:

键 值 说明
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"
}
Response: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

状态代码：400

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

在此示例中，我们展示了故障场景：来电被路由到某个菜单 ID，但该菜单处于手动重定向状态，因此无法接听来电。

请求

Headers:

键 值 说明
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"
}
Response: Error : Menu is in 'manual redirection' state, can't accept calls
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

状态代码：400

错误：通话类型无效

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

请求

Headers:

键 值 说明
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 无效的失败场景。

请求

Headers:

键 值 说明
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。

请求

Headers:

键 值 说明
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"
}
Response: Error : Only IVR and mobile menu IDs are permitted
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

状态代码：400

使用最终用户号码创建来电

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

请求

Headers:

键 值 说明
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 处于非营业时间状态时发生的失败。

请求

Headers:

键 值 说明
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"
}
Response: Error : Menu is in 'after hours' state, can't accept incoming calls
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

状态代码：400

错误：无法使用此语言

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

请求

Headers:

键 值 说明
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 的来电的请求。

请求

Headers:

键 值 说明
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

错误：找不到语言

此示例演示了在找不到所提供的语言时发生的失败。

请求

Headers:

键 值 说明
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 时发生的失败。

请求

Headers:

键 值 说明
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 不正确时出现的失败情况。

请求

Headers:

键 值 说明
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

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

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

请求

Headers:

键 值 说明
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，该通话将作为新创建的预约通话的父级通话进行关联。使用 call_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

Headers:

键 值 说明
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_namber 格式不正确而导致的失败。

请求

Headers:

键 值 说明
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"
}
Response: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

状态代码：400

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

此示例演示了当指定的菜单 ID 设置为菜单重定向且无法接听来电时发生的失败。

请求

Headers:

键 值 说明
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"
}
Response: Error : Menu is in 'manual redirection' state, can't accept calls
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

状态代码：400

错误：通话类型无效

此示例演示了在发出请求且调用类型无效时发生的失败。

请求

Headers:

键 值 说明
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 时的请求和响应。

请求

Headers:

键 值 说明
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 时失败的请求。

请求

Headers:

键 值 说明
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"
}
Response: Error : Only mobile and web menu IDs are permitted
{
    "message": "Only mobile and web menu IDs are permitted"
}

状态代码：400

使用菜单 ID 创建预约通话

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

请求

Headers:

键 值 说明
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 的预约通话。

请求

Headers:

键 值 说明
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

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

在此示例中，我们展示了失败场景：创建了预约通话，但提供的菜单不在营业时间内，因此无法接听来电。

请求

Headers:

键 值 说明
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"
}
Response: Error : Menu is in 'after hours' state, can't accept incoming calls
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

状态代码：400

错误：无法使用此语言

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

请求

Headers:

键 值 说明
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

错误：找不到语言

在此示例中，我们展示了创建了预约通话但语言无效或不可用的失败场景。

请求

Headers:

键 值 说明
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 无效且未找到的失败场景。

请求

Headers:

键 值 说明
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"
}
Response: Error : menu ID is not found
{
    "message": "menu_id 9999 is not found"
}

状态代码：400

错误：菜单 ID 格式不正确

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

请求

Headers:

键 值 说明
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

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

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

请求

Headers:

键 值 说明
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

在此示例中，我们展示了失败场景：创建了预约通话，但缺少必需的预约时间值。

请求

Headers:

键 值 说明
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 在通话会话期间将数据参数传递给虚拟客服，请参阅在会话期间将数据参数传递给虚拟客服。