@(udesk)[CTI|API|CTI CLOUD]

通用规范

请求格式

Base URL

https://{host}/{Type}/{version}/{api}?Timestamp={Timestamp}&AppId={AppId}

HTTP Header

HTTP METHOD

HTTP Status Code

返回格式

通用

正确返回格式

{
  "ErrCode": "000000", // 响应码(必须)
  "ErrDesc": "OK",   // 响应描述(必须)
  "Result": {
    // 数据...
  }
}

错误返回格式

{
  "ErrCode": "000001",     // 响应码(必须)
  "ErrDesc": "参数错误", // 响应描述(必须)
  "Result": {
    // 数据...
  }
}

websocket消息格式

请求消息标准头部

{
    "Ver": "1.0",   // 协议版本号
    "UA": "Chrome 62;uvcsdk-js-1.0",  // 可选,<浏览器或移动端操作>;<SDK>
    "SeqId": 1,        // 序列ID,消息发送方定义,顺序增加。响应序列ID与发送的序列ID相同
    "MsgId": "uuid",   // 消息ID,每一次消息的唯一标识,消息发送方定义定义,响应消息ID与发送的消息ID相同
    "MsgType":"REQ", // 请求消息:REQ
    "AppId": "f781fd92-9e96-4195-7a7e-257307edb4ad",
    "AgentId": "1443",
    "Timestamp": 1511069652789, // UTC时间戳,精确到毫秒
}

响应消息标准头部

{
    "Ver": "1.0",   // 协议版本号
    "SeqId": 1,        // 响应序列ID与发送的序列ID相同
    "MsgId": "uuid",        // 响应消息ID与发送的消息ID相同
    "MsgType":"REP", // 响应消息:REP
    "Timestamp": 1511070594789, // UTC时间戳,精确到毫秒

    "ErrCode": "000000",        // 成功: 000000,
    "ErrDesc": "OK",          // 错误描述,成功为: OK
}

通知消息标准头部

通知消息不需要响应

{
    "Ver": "1.0",   // 协议版本号
    "SeqId": 1,        // 序列ID,消息发送方定义,顺序增加。响应序列ID与发送的消息ID相同
    "MsgId": "uuid",   //  消息ID,每一次消息的唯一标识,消息发送方定义定义,响应消息ID与发送的消息ID相同
    "MsgType":"NTF", // 通知消息:NTF
    "Timestamp": 1511069652789, // UTC时间戳,精确到毫秒
}

事件消息标准头部

事件消息需要evtAck响应

{
    "Ver": "1.0",   // 协议版本号
    "SeqId": 1,        // 序列ID,消息发送方定义,顺序增加。响应消息ID与发送的消息ID相同
    "MsgId": "uuid",   // 消息ID,每一次消息的唯一标识,消息发送方定义定义,响应消息ID与发送的消息ID相同
    "MsgType":"EVT", // 事件消息:EVT
    "Timestamp": 1511069652789, // UTC时间戳,精确到毫秒
}

事件响应消息

{
    "Ver": "1.0",   // 协议版本号
    "SeqId": 1,        // 序列ID。响应序列ID与发送的序列ID相同
    "MsgId": "uuid", // 消息ID,每一次消息的唯一标识,响应消息ID与发送的消息ID相同
    "MsgType":"ACK", // 事件响就消息:ACK
    "Timestamp": 1511069652789, // UTC时间戳,精确到毫秒

    "Method": "{EvtMethod}"
}

数据格式约定

PSTN号码

示例

"01067654637" # 座机号
"13676546374" # 手机号

分机号码(Extension)

示例

"8001"      # 分机号码

队列ID(QueueId)

坐席ID(AgentId)

坐席工号(WorkId)

时间戳(Timestamp)

鉴权方式

服务端接口鉴权

示例

https://xxx.udesk.cn/ccapi/v2/agents?Timestamp=1519468251&AppId=6f142ddb-47ed-442e-83e7-6d2574d77aa2&Sid=1234567890&Sign=9416b06a42d56dc3be412fa084e787dba52a2769

前端接口鉴权

示例

https://xxx.udesk.cn/ccapi/v2/agents?Timestamp=1519468251&AppId=6f142ddb-47ed-442e-83e7-6d2574d77aa2&AgentId=8001&Sign=9416b06a42d56dc3be412fa084e787dba52a2769

websocket鉴权

服务端接口说明

应用管理

创建应用

URL: apps METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
Name Y string 应用名称
Type Y integer 应用类型,呼叫中心平台:1 电销平台:0
CallbackUrl Y string(url) 服务器回调地址
IsHideUserNum N boolean 坐席分机上隐藏用户号码, 默认:False
Memo N string 描述

注:请求参数中不需要 AppId,因为应用还没有创建,此时还没有 AppId。这是唯一一个不需要 AppId 作为请求参数的 API 接口。

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
AppId string(uuid) 应用唯一ID
ExtensionPrefix string 坐席分机号前缀
Name string 应用名称
Memo string 应用描述
Type string 应用类型
CallbackUrl string 回调地址
IsHideUserNum string 坐席分机上隐藏用户号码
ExtensionPrefix string(digits) 坐席分机号前缀
Secret string 应用密钥
WrapUpTime string 整理时间

修改应用

URL: apps METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
Name N string 应用名称
Type N string(enum) 应用类型,值:default或external, 默认为:default
CallbackUrl N string(url) 服务器回调地址
IsHideUserNum N boolean 坐席分机上隐藏用户号码
Memo N string 描述

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取应用详情

URL: apps METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
AppId string(uuid) 应用ID
Name string 应用名称
Type string(enum) 应用类型,default或external
CallbackUrl string(url) 服务器回调地址
IsHideUserNum boolean 坐席分机上隐藏用户号码
Secret string 应用密钥
Memo string 描述,选填

中继号码管理

外呼时中继号码的选号策略:

  1. 外呼指定中继号优先
  2. 其次,坐席默认中继号
  3. 再次,企业默认中继号
  4. 最后,系统随机选号

获取中继号列表

URL: spnumbers METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
SpNumbers [string(uuid)] 中继号列表
DefSpNumber string(digits) 当前配置的默认中继号

修改默认中继号

URL: spnumbers/default METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
DefSpNumber N string 默认使用第一个中继号码,可以是中继号码中的任何一个号码

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

删除默认中继号

URL: spnumbers/default METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

修改坐席默认中继号

URL: spnumbers/default/{AgentId} METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
DefSpNumber N string 默认使用企业默认中继号码,可以是中继号码中的任何一个号码

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

删除坐席默认中继号

URL: spnumbers/default/{AgentId} METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

坐席管理

创建坐席

URL: agents METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y string 时间戳
AppId Y string(uuid) 应用ID
Agents Y array(座席对象) 座席列表

座席对象

参数名 必选项 类型(格式) 说明
AgentId Y string(digits) 坐席ID
WorkId Y string(digits) 坐席工号
Name N string 坐席姓名
Mobile N string(phone) 坐席手机号
Email N string(Email) 坐席Email
Role N string(enum) 可以是agent, leader,默认为agent
Enable N boolean true:启用,默认启用
IsCreateExtension N boolean 创建并绑定坐席分机

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如果同时绑定分机,如下

Result

参数名 类型(格式) 说明
Extensions [Extension] 分机号码列表,如下

Extensions*

参数名 类型(格式) 说明
Extension string(digits) 分机号码
Password string 分机密码

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agents?Timestamp=1566446286&AppId=802411d4-2fb5-46ae-422f-d33de0059c47&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"Agents\":[{\"AgentId\":\"199\",\"WorkId\":\"199\",\"Name\":\"Li\",
\"Mobile\":\"18512520714\",\"Email\":\"123@qq.com\",\"Role\":\"agent\",\"Extension\":\"2457\",\"WrapUpTime\":0},{\"AgentId\":\"200\",\"WorkId\":\"200\",\"Name\":\"Qian\",\"Mobile\":\"18512520714\",\"Email\":\"456@qq.com\",\"Role\":\"agent\",\"Extension\":\"2458\",\"WrapUpTime\":1}]}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

修改坐席

URL: agents/{AgentId} METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y string 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string(digits) 坐席ID
WorkId Y string(digits) 坐席工号
Name N string 坐席姓名
Mobile N string(phone) 坐席手机号
Email N string(Email) 坐席Email
Role N string(enum) 可以是agent, leader,默认为agent
Enable N boolean true:启用 false:禁用 默认:true

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X PUT 'http://ip:port/ccapi/v2/agents/7763?Timestamp=1566540424&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=de3fec40c8671bcbab00b12e5254e378a53f646a&Sid=123456789abcdef' -d '{\"AgentId\":\"7763\",\"WorkId\":\"7763\",\"Enable\":true}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

坐席签入

URL: agent/login METHOD: POST

请求参数

参数名 类型(格式) 必选项 说明
AgentID string(digits) Y 坐席ID
WorkerID string(digits) N 坐席工号
QueueIDs [string(digits)] N 队列标识数组
Number string(digits) N 座席联系方式, PSTN号码或VOIP帐号
State string(digits) Y
MsgId string N 时间戳
返回结果
参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
msg_id string 签入时发送过来的MsgId
result string 无意义
data nil 无意义

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agent/login?Timestamp=1566554019&AppId=d30fe35c-995d-4921-55b8-ad21b476bbb8&Sign=597ba974a48f49ca8ae95eee2d725a5bf6211520&Sid=123456789abcdef&MsgId=123456789' -d '{\"agent_id\":\"91\"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "msg_id": "123456789",
    "results": "",
    "data": null
}

坐席签出

URL: agent/logout METHOD: POST

请求参数

参数名 类型(格式) 必选项 说明
AgentID string(digits) Y 坐席ID
返回结果
参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agent/logout?Timestamp=1566554019&AppId=d30fe35c-995d-4921-55b8-ad21b476bbb8&Sign=597ba974a48f49ca8ae95eee2d725a5bf6211520&Sid=123456789abcdef&MsgId=123456789' -d '{\"agent_id\":\"91\"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "msg_id": "123456789",
    "results": "",
    "data": null
}

删除坐席

URL: agents/{AgentId} METHOD: DELETE

请求参数

参数名 类型(格式) 必选项 说明
Timestamp number(Timestamp) Y 时间戳
AppId string(uuid) Y 应用ID
AgentId string(digits) Y 坐席ID,数字
IsDelExtensions boolean N 是否同时删除绑定的分机,true - 删除坐席绑定的所有分机;false(默认) - 不删除坐席绑定的分机

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X DELETE 'http://ip:port/ccapi/v2/agents/7777?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{"AgentId":"7777"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

获取坐席详情

URL: agents/{AgentId} METHOD: GET

请求参数

参数名 类型(格式) 必选项 说明
Timestamp number(Timestamp) Y 时间戳
AppId string(uuid) Y 应用ID
AgentId string(digits) Y 坐席ID,数字

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
AppId string(uuid) 应用ID
AgentId string(digits) 坐席ID
WorkId string(digits) 坐席工号
Name string 坐席姓名
Mobile string(phone) 坐席手机号
Email string(Email) 坐席Email
Role string(enum) 可以是agent, leader,默认为agent
Enable N boolean
Extensions [Extension] 坐席绑定的分机列表
Queues [string(digits)] 坐席绑定的队列列表
DefSpNumber [string(digits)] 坐席默认中继号

请求示例

curl 'http://ip:port/ccapi/v2/agents/7765?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{"AgentId":"7765"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "AppId": "a54a8b77-f12d-4ac9-742d-5b2bef5c4d11",
        "AgentId": "7765@a54a8b77-f12d-4ac9-742d-5b2bef5c4d11",
        "WorkId": "7765",
        "Name": "",
        "Mobile": "",
        "Email": "",
        "Role": "agent",
        "Queues": null,
        "Extensions": null,
        "DefSpNumber": "",
        "State": 4,
        "ExtState": 3,
        "WrapUpTime": 0,
        "Enable": true
    }
}

获取坐席列表

URL: agents METHOD: GET

请求参数

参数名 必选项 说明
Timestamp Y 时间戳
AppId Y 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
Agents [Agent] 坐席列表,如下

Agents

参数名 类型(格式) 说明
AgentId string(digits) 坐席ID
WorkId string(digits) 坐席工号
Name string 坐席姓名
Mobile string(phone) 坐席手机号
Email string(Email) 坐席Email
Role string(enum) 可以是agent, leader,默认为agent
Enable N boolean
Extensions [Extension] 坐席绑定的分机列表
Queues [string(digits)] 坐席绑定的队列列表
DefSpNumber [string(digits)] 坐席默认中继号

请求示例

curl 'http://ip:port/ccapi/v2/agents?Timestamp=1566536708&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=2a371cf8c49560671c02116ae54ac1f9ef1e59f3&Sid=123456789abcdef'

响应示例

{
    "ErrCode": "",
    "ErrDesc": "",
    "Result": [
        {
            "AppId": "a54a8b77-f12d-4ac9-742d-5b2bef5c4d11",
            "AgentId": "62",
            "WorkId": "565",
            "Name": "crm测试2",
            "Mobile": "13716429603",
            "Email": "crmdianxiao2@test.cn",
            "Role": "agent",
            "Queues": null,
            "Extensions": null,
            "DefSpNumber": "",
            "State": 0,
            "ExtState": 0,
            "WrapUpTime": 0,
            "Enable": true
        },
        {
            "AppId": "a54a8b77-f12d-4ac9-742d-5b2bef5c4d11",
            "AgentId": "78",
            "WorkId": "",
            "Name": "diandian测试专用",
            "Mobile": "13935107603",
            "Email": "diandian@test.cn",
            "Role": "agent",
            "Queues": null,
            "Extensions": null,
            "DefSpNumber": "057126200670",
            "State": 0,
            "ExtState": 0,
            "WrapUpTime": 0,
            "Enable": false
        }
    ]
}

坐席分机绑定

URL: agents/extensions METHOD: POST

NOTE:一个坐席最多可以绑定两个分机号码,但同时只能使用一个分机

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string(digits) 坐席ID
Extensions Y [string(digits)] 分机号码列表

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agents/extensions?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"Extensions\":[\"2345\"],\"AgentId\":\"6655\"}
'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

坐席分机解绑

URL: agents/extensions METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string(digits) 坐席ID
Extensions Y [string(digits)] 分机号码列表

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X DELETE 'http://ip:port/ccapi/v2/agents/extensions?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '{\"Extensions\":[\"2345\"],\"AgentId\":\"6655\"}
'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

坐席队列绑定

URL: agents/queues METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string(digits) 坐席ID
Queues Y [string(digits)] 队列ID列表

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

坐席队列解绑

URL: agents/queues METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string(digits) 坐席ID
Queues Y [string(digits)] 队列ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

队列管理

创建队列

URL: queues METHOD: POST

NOTE: 一个AppId最多可以创建100个队列

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
QueueId Y string(digits) 队列ID
QueueName Y string 队列名称
Strategy N string(enum) 排队策略,默认为longest_idle
Timeout N number 排队超时时间(秒),默认为120
MaxLength N number 队列最大长度,默认为128,最大值为512

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

修改队列

URL: queues METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
QueueId Y string(digits) 队列ID
QueueName Y string 队列名称
Strategy N string(enum) 排队策略,默认为longest_idle
Timeout N number 排队超时时间(秒),默认为120
MaxLength N number 队列最大长度,默认为128,最大值为512

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

删除队列

URL: queues METHOD: DELETE

NOTE: 有坐席绑定的队列不能删除

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
QueueId Y string(digits) 队列ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取全部队列信息

URL: queues METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
Queues [object] 队列列表,如下

Queues

参数名 类型(格式) 说明
QueueId string(digits) 队列ID
QueueName string 队列名称
Strategy string(enum) 排队策略
Timeout number 排队超时时间(秒)
MaxLength number 队列最大长度

获取队列信息

URL: queues/{QueueId} METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
QueueId string(digits) 队列ID
QueueName string 队列名称
Strategy string(enum) 排队策略
Timeout number 排队超时时间(秒)
MaxLength number 队列最大长度
Agents [AgentId] 绑定此队列的坐席ID列表

队列批量绑定坐席

URL: queues/agents METHOD: POST, PUT

NOTE: 队列批量绑定坐席,只新建不删除之前记录

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
QueueId Y string(digits) 队列ID
AgentIds Y [string(digits)] 绑定的坐席ID列表

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

分机管理

创建分机

URL: extensions METHOD: POST

NOTE: 分机密码由系统生成,创建时不能设定

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
Extension Y string(digits) 分机号码

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
Extension string(digits) 分机号码
Password string 分机密码

请求示例

$ curl -X POST 'http://ip:port/ccapi/v2/extensions?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"Extension\":\"4567\",\"Password\":\"123456\",\"Number\":\"11223344556677\"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "Extension": "4567",
        "Password": "5ca7561e1748f1b7",
        "Number": "90310468564567"
    }
}

删除分机

URL: extensions METHOD: DELETE

NOTE: 绑定坐席的分机不能删除

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
Extension Y string(digits) 分机号码

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
$ curl -X DELETE 'http://ip:port/ccapi/v2/extensions?Timestamp=1566538172&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=5d97fdd3e55f26a0aea37ca3d03819bf28093038&Sid=123456789abcdef' -d '{\"Extension\":\"4567\",\"Password\":\"123456\",\"Number\":"11223344556677"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": null
}

话机/手机模式切换

URL: agent/set_call_mode METHOD: DELETE

NOTE: 绑定坐席的分机不能删除

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string 座席 ID
Contact Y string 模式,参见下面的模式列表
Number Y string 号码
MsgId N string 用于标识本地调用的唯一 ID

模式列表

模式 说明
voip IP 话机
cellphone 手机

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
msg_id string 签入时发送过来的MsgId
result string 无意义
data nil 无意义

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agent/set_call_mode?Timestamp=1566554019&AppId=d30fe35c-995d-4921-55b8-ad21b476bbb8&Sign=597ba974a48f49ca8ae95eee2d725a5bf6211520&Sid=123456789abcdef&MsgId=123456789' -d '{\"AgentId\":\"91\",\"Contact\":\"cellphone\",\"Number\":\"13719873839\"}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "msg_id": "123456789",
    "results": "",
    "data": null
}

IVR配置管理

上传IVR语音文件

URL: ivrs/vfiles METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
FileName Y string 文件名,不能重名
FileType N string 文件类型,只支持wav
FileDesc N string 文件描述

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

删除IVR语音文件

URL: ivrs/vfiles METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
FileName Y string 文件名,英文字符或数字,不能重名

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取IVR语音文件列表

URL: ivrs/vfiles METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
IvrVFiles [object] 语音文件列表, 如下

IvrVFiles

参数名 类型(格式) 说明
FileName string 文件名
FileType string 文件类型
FileDesc string 文件描述

设置IVR默认语音

URL: ivrs/defvoices METHOD: POST,PUT

NOTE: 如果不配置IVR语音,系统使用默认配置

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
DefVoices Y [object] IVR提示语音,如下

DefVoices

参数名 必选项 类型(格式) 说明
Welcome N object(voice) or "default" 欢迎语
ClosingTime N object(voice) or "default" 下班提示语
NoAnswer N object(voice) or "default" 未接拒接语音
VoiceMail N object(voice) or "default" 留言语音
Waiting N object(voice) or "default" 等待语音
Consult N object(voice) or "default" 咨询语音
Hold N object(voice) or "default" 保持语音
QueueTimeout N object(voice) or "default" 排队超时语音
Evaluate N object(voice) or "default" 满意度语音

Voice

参数名 必选项 类型(格式) 说明
Type Y string 类型:tts, wav
Content Y string 内容:Type是tts时,内容为tts文本内容;Type是wav时,内容为文件名

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取IVR默认语音

URL: ivrs/defvoices METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
Voices [Voice] IVR提示语音,参考:“设置IVR语音配置”

更新快速路由配置

URL: ivrs/fastrouters METHOD: POST, PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
FastRouter Y [object] 快速路由配置表,如下

FastRouter

参数名 必选项 类型(格式) 说明
Dtmf Y string(digit) 按键, 0~9
Desc Y string 队列描述
QueueId Y string(digits) 队列ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取快速路由配置

URL: ivrs/fastrouters METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
FastRouter [object] 快速路由配置表,如下

FastRouter

参数名 类型(格式) 说明
Dtmf string(digit) 按键, 0~9
Desc string 队列描述
QueueId string(digits) 队列ID

创建外呼

URL: originatev2 METHOD: POST

NOTE:

  1. 方向: APP -> CTI

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
Called Y string 被叫号码
CalledDisplay Y string 外显号码
AgentID Y string 座席ID
UserData N array(随路数据对象) 随路数据

随路数据对象

字段 必选项 类型(格式) 说明
evt Y string 事件类型
data Y string 自定义数据类型

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
results string 呼叫CallID

请求示例

$ curl 'http://47.94.221.132:8043/ccapi/v2/originatev2?Timestamp=1566446286&AppId=d30fe35c-995d-4921-55b8-ad21b476bbb8&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"caller\": \"057128091649\", \"called\": \"15652692674\",\"called_display\":\"057128091649\",\"agent_id\": \"91\", \"user_data\":[{\"evt\": \"user_answer\", \"data\":\"1111111\"}, {\"evt\": \"agent_answer\",\"data\": \"22222\"}]}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "msg_id": "",
    "results": "97688e57-7a36-40f7-694a-393d4d1a10d3",
    "data": null
}

自动外呼任务管理

启动自动外呼任务

URL: ads/task/start METHOD: POST

NOTE:

  1. 方向: APP -> ADS

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
AdTaskId Y string 任务ID
AdTaskType Y string 1 - 精准;2 - 比例;3 - 预测;4 - 语音播报;5 - 机器人
AdTaskRatio Y number 1.0~5.0, 比例外呼时为呼叫比例,预测外呼时为呼叫强度
AdQueueId N string 任务对应的queue_id
AdIvrId N string 任务对应的ivr_id
AdRobotToken N string 任务对应的robot_token
AdCallerNum Y string 外呼任务使用的主叫号码
AdDispNum Y string 外呼任务使用的主叫号码
AdConCallLimit Y number 最大呼叫并发数,最大值 100

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

更新自动外呼任务比例/强度

URL: ads/task/update_ratio METHOD: POST

NOTE:

  1. 方向: APP -> ADS

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
AdTaskId Y string 任务ID
AdTaskRatio Y number 1.0~5.0, 比例外呼时为呼叫比例,预测外呼时为呼叫强度

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

停止自动外呼任务

URL: ads/task/stop METHOD: POST

NOTE:

  1. 方向: APP -> ADS

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
AdTaskId Y string 任务ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

强制停止自动外呼任务

URL: ads/task/force_stop METHOD: POST

NOTE: 1. 方向: APP -> ADS 2. 仅供内部调试使用

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
AdTaskId Y string 任务ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

获取自动外呼任务号码

URL: cc_ad_task/numbers METHOD: POST

NOTE:

  1. 方向: ADS -> APP

请求参数

参数名 必选项 类型(格式) 说明
app_id Y string(uuid) 应用ID
ad_task_id Y string 任务ID
count Y number 号码数

返回结果

参数名 类型(格式) 说明
code string(digits) 响应码
message string 响应描述
exhausted boolean true/false, 号码是否已经用完
results [AdNumber] 号码列表,如下

AdNumber

参数名 类型(格式) 说明
id string 号码id
number string 号码

自动外呼任务停止通知

URL: cc_ad_task/stop METHOD: POST

NOTE:

  1. 方向: ADS -> APP

请求参数

参数名 必选项 类型(格式) 说明
app_id Y string(uuid) 应用ID
ad_task_id Y string 任务ID

返回结果

参数名 类型(格式) 说明
code string(digits) 响应码
message string 响应描述

事件推送

NOTE: + 事件推送使用POST方法 + 使用与接口相同的鉴权方式

订阅事件

URL: webhooks/events METHOD: POST, PUT NOTE: 由应用层向CTI CLOUD发起订阅事件请求

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
Events Y [string] 事件名称列表, 如下

events

  1. 坐席相关
  2. AgentStateChange: AcdAgentStateSubType
  3. AgentCallModeChange
  4. ExtStateSubType
  5. 呼叫相关:
  6. AgentRinging
  7. AgentAnswered
  8. UserRinging
  9. UserAnswered
  10. AgentHangup
  11. UserHangup
  12. StartDialout
  13. CallNotes:坐席或机器人说话时的文本内容,坐席是识别结果,机器人是robot返回的文本(语音文件直接返回语音文件名称)
  14. HangupCause:挂机原因,已合并到GeneralHangup
  15. RecordStop
  16. CallEnd // 通话记录, GeneralHangup:挂机消息,通话记录

IncomingCall【无】 Dialout【无】 ... ### 呼叫过程事件 ### 坐席状态变化事件 ### 队列状态变化事件 ### 录音事件

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

获取订阅事件列表

URL: webhooks/events METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
Events [string] 事件名称列表

消息订阅

URL: subscriptions METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
subscriptions Y array(subscription) 订阅对象列表

消息订阅对象

参数名 必选项 类型(格式) 说明
callback Y string(url) 回调地址
name Y string 订阅的名字
events Y [string] 订阅事件列表

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object(sub_result) name与subid的映射关系

sub_result | 参数名 | 类型(格式) | 说明 | |--------|-----------|------| |sub_succ | array(sub_succ) | 订阅成功的subid和名称 | |sub_fail | array(string) | 订阅失败的名字 |

sub_succ | 参数名 | 类型(格式) | 说明 | |--------|-----------|------| |id| unit| 订阅的 ID | |name | string | 订阅的名称 |

请求示例

curl -X POST 'http://123.56.218.144:8043/ccapi/v2/subscriptions?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"subscriptions\": [{\"callback\": \"http://59.110.105.200:12345\",\"name\": \"sub1\",\"events\": [\"agent_ringing\", \"agent_answer\",\"start_dialout\", \"user_ringing\", \"user_answer\", \"agent_hangup\", \"user_hangup\"]},
{\"callback\": \"http://59.110.105.200:12345\",\"name\": \"sub2\",\"events\": [\"agent_ringing\", \"agent_answer\",\"start_dialout\", \"user_ringing\", \"user_answer\", \"agent_hangup\", \"user_hangup\"]},
{\"callback\": \"http://59.110.105.200:12345\",\"name\": \"sub3\",\"events\": [\"agent_ringing\", \"agent_answer\",\"start_dialout\", \"user_ringing\", \"user_answer\", \"agent_hangup\", \"user_hangup\"]},
{\"callback\": \"http://59.110.105.200:12345\",\"name\": \"sub4\",\"events\": [\"agent_ringing\", \"agent_answer\",\"start_dialout\", \"user_ringing\", \"user_answer\", \"agent_hangup\", \"user_hangup\"]}
]}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "sub_succ":[{"id":1,"name":"sub1"},{"id":2,"name":"sub2"}],
        "sub_fail":["sub3","sub4"]
    }

}

消息订阅批量查询

URL: subscriptions METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result array(subscription) 订阅事件列表

subscription

参数名 必选项 类型(格式) 说明
callback Y string(url) 回调地址
name Y string 订阅的名字
events Y [string] 订阅事件列表
enable Y bool 订阅状态 true:启用,false:禁用

请求示例

curl -X GET 'http://123.56.218.144:8043/ccapi/v2/subscriptions?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' 

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": [
        {
            "callback": "http://59.110.105.200:12345",
            "name": "sub1",
            "events": [
                "agent_ringing",
                "agent_answer",
                "start_dialout"
            ],
            "enable": false
        },
        {
            "callback": "http://59.110.105.200:12345",
            "name": "sub1",
            "events": [
                "agent_ringing",
                "agent_answer",
                "start_dialout"
            ],
            "enable": false
        }
    ]
}

消息订阅单个查询

URL: subscriptions/{id} METHOD: GET

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result subscription 订阅对象

subscription

参数名 必选项 类型(格式) 说明
callback Y string(url) 回调地址
name Y string 订阅的名字
events Y [string] 订阅事件列表
enable Y bool 订阅状态 true:启用,false:禁用

请求示例

curl -X GET 'http://123.56.218.144:8043/ccapi/v2/subscriptions/8?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' 

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "callback": "http://59.110.105.200:12345",
        "name": "sub1",
        "events": [
            "agent_ringing",
            "agent_answer",
            "start_dialout"
        ],
        "enable": false
    }
}

修改消息订阅

URL: subscriptions/{id} METHOD: PUT

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
subscription Y object(subscription) 订阅对象

subscription | 参数名 | 类型(格式) | 说明 | |--------|-----------|------| |callback|Y| string(url) |回调地址| |name |Y| string |订阅的名字| |events |Y|array(string)|订阅事件(覆盖操作)| |enable |Y| bool |订阅状态 true:启用,false:禁用|

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result [object] name与subid的映射关系

object | 参数名 | 类型(格式) | 说明 | |--------|-----------|------| |SubId | number | 订阅的唯一id | |name | string | 订阅的名字 |

请求示例

curl -X PUT 'http://123.56.218.144:8043/ccapi/v2/subscriptions/7?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' -d '{\"callback\": \"http://59.110.105.911:12345\",\"name\": \"sub1\",
\"events\": [\"user_ringing\", \"user_answer\", \"agent_hangup\", \"user_hangup\"],\"state\":0}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "sub1": 7
    }
}

删除消息订阅

URL: subscriptions/{id} METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述

请求示例

curl -X DELETE 'http://123.56.218.144:8043/ccapi/v2/subscriptions/8?Timestamp=1566446286&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=891462f08d113b0b1285e985ff7a7c56ba42a18f&Sid=123456789abcdef' 

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": ""
}

回调认证

callback URL 的认证方式如下:

callback 请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y string 时间戳,当前时间距离UTC时间,1970-01-01 00:00:00的秒数
AppId Y string(uuid) 应用ID
Sign Y string 签名

callback 签名计算方法

Secret为创建应用时返回的加密字段,需要用户保存。

Sign: SHA1(AppId + Secret + Timestamp)

客户端接口说明

坐席客户端接口

NOTE: 客户端使用websocket,所有请求都是异步的

*签入

{
    // #include <标准头部>
    "Method": "login",
    "AppId": "xxxxxxxxxxxxxxxx",
    "AgentId": "xxxxxxxxxxxxxxxx",
    "Token": "xxxxxxxxxxxxxxxx",
    "State": "idle",   // Agent的初始状态,可选,默认为idle
}

*签出(离线)

{
  // #include <标准头部>
  "Method": "logout",
}

*置忙

{
  // #include <标准头部>
  "Method": "setState",
  "State": "busy",
}

*置闲

{
  // #include <标准头部>
  "Method": "setState",
  "State": "idle",
}

*离席(小休)

{
  // #include <标准头部>
  "Method": "setState",
  "State": "onBreak",
  "SubState": 0, // SubState 默认为0,可以是一个>=0的整数
}

*挂机

{
  // #include <标准头部>
  "Method": "hangup",
}

*设置呼叫模式【webrtc】

{
  // #include <标准头部>
  "Method": "setCallMode",
  "Contact": "xxxx", // cellphone/voip
  "UserData": "xxxx",    // 随路数据
}

*外拨

{
  // #include <标准头部>
  "Method": "dialout",
  "DestNumber": "xxxx", // 目标号码
  "SpNumber": "xxxx", // 显示号码
  "UserData": "xxxx",    // 随路数据
}

成功返回

{
  "Method": "dialout",
  "DestNumberLoc": "", // 外拨被叫号码归属地
  "UserData": ""
}

*获取当前状态

NOTE: 通话状态返回通话的详细情况

{
  // #include <标准头部>
  "Method": "getState",
}

返回

{
  // #include <标准头部>
  "Method": "getState",

  "CurState": "idle",
  "StartTime": xxxxx, // timestamp - 坐席状态变化时间点
  "CurMode": "", // cellphone | voip
  "CurExtState": "", // 当前分机状态

  // 如果是通话状态,会包括以下返回:
  "DestNumber": "",
  "DestNumberLoc": "", // 号码归属地
  "SpNumber": "",
  "CallDirection": "",
  "UserData": "",
}

坐席客户端事件

*外拨坐席话机振铃

{
  // #include <标准头部>
  "Method": "agentRinging",
  "AgentNumber": "",
  "DestNumber": "",
  "DestNumberLoc": "", // 号码归属地
  "SpNumber": "",
  "CallDirection": "",
  "UserData": "",
}

*外拨坐席摘机

{
  // #include <标准头部>
  "Method": "agentAnswered",
  "AgentNumber": "",
  "DestNumber": "",
  "DestNumberLoc": "", // 号码归属地
  "SpNumber": "",
  "CallDirection": "",
  "UserData": "",
}

*外拨用户侧振铃

{
  // #include <标准头部>
  "Method": "userRinging",
  "AgentNumber": "",
  "DestNumber": "",
  "DestNumberLoc": "", // 号码归属地
  "SpNumber": "",
  "CallDirection": "",
  "UserData": "",
}

*外拨用户摘机

{
  // #include <标准头部>
  "Method": "userAnswered",
  "AgentNumber": "",
  "DestNumber": "",
  "DestNumberLoc": "", // 号码归属地
  "SpNumber": "",
  "CallDirection": "",
  "UserData": "",
}

*坐席挂机

{
  // #include <标准头部>
  "Method": "agnetHangup",
  "Reason": "",
}

*用户挂机

{
  // #include <标准头部>
  "Method": "userHangup",
  "Reason": "",
}

*坐席状态变化

{
  // #include <标准头部>
  "Method": "agentStateChange",
  "CurState": "",
  "CurStateSubId": 0,  // 小休状态有此项
  "OldState": "",
}

*坐席呼叫模式变化

{
  // #include <标准头部>
  "Method": "agentCallModeChange",
  "CurContact": "",
}

*分机状态变化

{
  // #include <标准头部>
  "Method": "extensionStateChange",
  "CurState": "",
  "OldState": "",
  "Reason": "",
}

*服务器断开连接

{
  // #include <标准头部>
  "Method": "disconnect",
  "Reason": "",
}

页面回拨

鉴权方式

回拨外呼接口

回拨目标管理

数据获取

获取通话记录

URL: calls/logs METHOD: GET

NOTE: 1. 只取已经结束的通话 2. 通过CallId获取指定CallId的通话,CallId优先 3. 通过时间范围可以获取一定时间范围的通话,时间范围1周,1周以前的数据不能获取

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
CallId N string(uuid) 呼叫ID,有此参数,只取这个CallId的记录
PageSize N number 页大小,最大100
PageNum N number 第几页
StartTime N timestamp 通话开始时间
EndTime N timestamp 通话结束时间

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
CallLogs [CallLog] 呼叫记录列表,如下

CallLog

参数名 类型(格式) 说明
CallId string(uuid) 呼叫标识
StartTime timestamp 通话开始时间
EndTime timestamp 通话结束时间
AgentAnswerTime timestamp 座席接听时间
UserAnswerTime timestamp 客户接听时间
CallDuration number 通话时长,单位:秒
TotalDuration number 通话总时长,单位:秒
DestNumber string(digits) 客户号码
UNProvince string 客户号码归属省份
UNCity string 客户号码归属城市
SpNumber string(digits) 中继号码
AgentId string(digits) 座席ID
AgentName string 座席姓名
WorkId string 座席工号
Email string(email) 座席邮箱
CallType string 通话类型, 如:呼入、呼出、呼入(转接)、呼入(监听)等
EndType string 通话结果
HangupBy string 通话挂断方,客户or座席
HangupReason string 挂机原因
HangupCode string(digits) 挂机返回码
AgentDevType string 设备类型,ip座机”或“手机、软电话
RobotVars map[string]object AI变量
AIRecordLen number AI录音时长
AdCallId string 自动外呼呼叫ID
AdTaskId string 自动外呼任务ID

请求示例

$ curl -X GET 'http://ip:port/ccapi/v2/calls/logs?Timestamp=1566530056&AppId=d30fe35c-995d-4921-55b8-ad21b476bbb8&Sign=e3d716dfd01e67207bb998f2b0c7dc7cdf2bf2b4&Sid=123456789abcdef' -d '{\"CallId\":\"bc1cc555-0b24-4e1c-9979-a514888ea495\",\"PageSize\":20,\"PageNum\":1,\"StartTime\":1566316800000,\"EndTime\":1566489599000}'

响应示例

{
    "ErrCode": "000000",
    "ErrDesc": "OK",
    "Result": {
        "CallLogs": [
            {
                "CallId": "bc1cc555-0b24-4e1c-9979-a514888ea495",
                "StartTime": 1566298669326,
                "EndTime": 1566320334606,
                "AgentAnswerTime": 1566298674686,
                "UserAnswerTime": 0,
                "CallDuration": 0,
                "TotalDuration": 21665,
                "DestNumber": "01086482889",
                "UNProvince": "",
                "UNCity": "",
                "SpNumber": "057128091649",
                "AgentId": "",
                "AgentName": "",
                "WorkId": "",
                "Email": "",
                "CallType": "呼出",
                "EndType": "callResult",
                "HangupBy": "agent",
                "HangupReason": "",
                "HangupCode": "",
                "AgentDevType": "voip",
                "RobotVars": null,
                "AIRecordLen": 0,
                "AdCallId": "",
                "AdTaskId": ""
            },
            {
                "CallId": "50def7e0-cf70-411e-9e05-4381817b441c",
                "StartTime": 1566351290766,
                "EndTime": 1566351302186,
                "AgentAnswerTime": 1566351292686,
                "UserAnswerTime": 0,
                "CallDuration": 0,
                "TotalDuration": 12,
                "DestNumber": "057128091649",
                "UNProvince": "",
                "UNCity": "",
                "SpNumber": "057128091649",
                "AgentId": "",
                "AgentName": "",
                "WorkId": "",
                "Email": "",
                "CallType": "呼入",
                "EndType": "callResult",
                "HangupBy": "agent",
                "HangupReason": "",
                "HangupCode": "",
                "AgentDevType": "voip",
                "RobotVars": null,
                "AIRecordLen": 0,
                "AdCallId": "",
                "AdTaskId": ""
            }
        ]
    }
}

获取录音记录

URL: calls/recfiles METHOD: GET

NOTE: 1. 通过CallId获取指定CallId的通话录音列表,CallId优先 2. 通过时间范围可以获取一定时间范围的通话录音列表,时间范围1周,1周以前的数据不能获取

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
CallId N string(uuid) 呼叫ID,有此参数,只取这个CallId的记录
PageSize N number 页大小,最大100
PageNum N number 第几页
StartTime N timestamp 通话开始时间
EndTime N timestamp 通话结束时间

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
RecFiles [RecFile] 录音记录列表,如下

RecFile

参数名 类型(格式) 说明
CallId string(uuid) 呼叫标识
StartTime timestamp 录音开始时间
EndTime timestamp 录音结束时间
Duration number 录音时长,单位:秒
RecFileUrl string(url) 录音文件地址

获取坐席状态变化记录

过滤条件:AgentId, or 时间, AppId

URL: agents/statelogs METHOD: GET

NOTE: 1. 指定AgentId后,只返回此坐席的状态变化记录 2. 不指定AgentId时,返回此企业所有坐席的状态变化记录 3. 时间段限制:1周

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId N string(uuid) 坐席ID
PageSize Y number 页大小,最大100
PageNum Y number 第几页
StartTime Y timestamp 开始时间
EndTime Y timestamp 结束时间

返回结果

参数名 类型(格式) 说明
ErrCode string(digits) 响应码
ErrDesc string 响应描述
Result object 如下

Result

参数名 类型(格式) 说明
AgentStateLogs [AgentStateLog] 录音记录列表,如下

AgentStateLog

参数名 类型(格式) 说明
AgentId string(digits) 座席ID
AgentName string 座席姓名
WorkId string 座席工号
CurState string 当前状态
CurStateSubId number 当前状态子Id
StartTime timestamp 当前状态开始时间
EndTime timestamp 当前状态结束时间
Duration number 当前状态持续时长,单位:秒
OldState string 前一状态
OldStateSubId number 前一状态子Id