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

通用规范

请求格式

Base URL

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

注:示例中的ip及port(端口号)与项目关联,请联系售前或售后负责人进行确认

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)

鉴权方式

服务端接口鉴权

参数(URL Query String)

示例

get请求

curl 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

注意 1. 调用创建应用这个接口,需要appid(由crm系统生成)、Sid(由udesk提供)、Authtoken(由udesk提供),接口依赖crm系统,无法单独调用; 2. 如果已有AppId和Sid,调用示例如下

curl {{base_url}}/ccapi/v2/apps?Timestamp={{timestamp}}&AppId={{appid}}&Sign={{sign}}&Sid=123456789abcdef \
-X POST \
-H 'content-type: application/json' \
-d'
{
  "Name":"test02",
  "Type":1,
  "CallbackUrl":""
}
'
  1. 下面的请求参数有问题
  2. 应用即呼叫中心平台的租户

请求参数

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

注意 1. 调用创建应用接口时,请求参数中不需要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 坐席分机上隐藏用户号码
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 默认使用第一个中继号码,可以是中继号码中的任何一个号码

注意: 对于POST、PUT方法来说,url参数、鉴权参数外的其他参数(例如修改默认中继号接口中的DefSpNumber)应通过request body传递

返回结果

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

请求示例

curl 'http://ip:port/ccapi/v2/spnumbers/default/7763?Timestamp=1566540424&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sid=123456789abcdef&Sign=de3fec40c8671bcbab00b12e5254e378a53f646a' \
-X PUT \
-d '{"DefSpNumber" : "057126200670"}'

删除默认中继号

URL: spnumbers/default METHOD: DELETE

请求参数

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

返回结果

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

请求示例

curl 'http://ip:port/ccapi/v2/spnumbers/default/7763?Timestamp=1566540424&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sid=123456789abcdef&Sign=de3fec40c8671bcbab00b12e5254e378a53f646a' -X DELETE

修改坐席默认中继号

URL: /spnumbers/agent/default/:agentId METHOD: PUT

请求参数

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

返回结果

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

删除坐席默认中继号

URL: /spnumbers/agent/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

注意: "{AgentId}"表示url参数

请求参数

参数名 必选项 类型(格式) 说明
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 'http://ip:port/ccapi/v2/agents/7763?Timestamp=1566540424&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sid=123456789abcdef&Sign=de3fec40c8671bcbab00b12e5254e378a53f646a' \
-X PUT \
-d '{
    "AgentId": "10030",
    "WorkId": "22024",
    "Name": "测试5",
    "Mobile": "17777773333",
    "Email": "5544@qq.com",
    "Role": "agent"
}
'

注意:AgentId在url和request body中都要传入

响应示例

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

坐席签入

URL: agent/login METHOD: POST

注意: 需要先给坐席绑定分机才能签入

请求参数

参数名 类型(格式) 必选项 说明
agent_Id string(digits) Y 坐席ID
WorkerID string(digits) N 坐席工号
QueueIDs [string(digits)] N 队列标识数组
Number string(digits) N 座席联系方式, PSTN号码或VOIP帐号
State string(digits) N
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": "10032" }'

响应示例

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

坐席签出

URL: agent/logout METHOD: POST

请求参数

参数名 类型(格式) 必选项 说明
agent_Id string(digits) Y 坐席ID

注意: 请求url里 应用id为"app_id",和之前的"AppId"不一样

返回结果

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

请求示例

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

响应示例

{
    "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

注意:AgentId是url参数

请求参数

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

注意:AgentId在url和request body中都要传入

返回结果

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

Result

参数名 类型(格式) 说明
AppId string 应用ID
AgentId string(digits) 坐席ID
WorkId string(digits) 坐席工号
Name string 坐席姓名
Mobile string(phone) 坐席手机号
Email string(Email) 坐席Email
Role string(enum) 可以是agent, leader,默认为agent
Queues [string(digits)] 坐席绑定的队列列表(数组)
QueuesNames string 坐席绑定的队列名
Extensions [Extension] 坐席绑定的分机列表(数组)
DefSpNumber [string(digits)] 坐席的默认中继号
State enum 坐席状态(参考下面的State枚举值
ExtState enum 分机状态(参考下面的ExtState枚举值
WrapUpTime Integer 整理时间,单位为秒
Enable boolean true:启用 false:禁用 默认:true
ExtenInfos string 分机信息

State枚举值

含义
0 准备中
1 就绪
2 锁定
3 通话中
4 不可用

ExtState枚举值

含义
0 ExtStateIdle 分机闲置
1 ExtStateBusy 分机忙
2 ExtStateOnline 分机在线
3 ExtStateOffline 分机离线
4 ExtStateInvalid 分机无效

请求示例

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

参数名 类型(格式) 说明
CurrPage Integer 当前所在的页数
PageSize Integer 每页的记录条数
Total Integer 总记录条数
TotalPage Integer 总页数
AgentList object 坐席列表,如下

AgentList

参数名 类型(格式) 说明
AppId string 应用ID
AgentId string(digits) 坐席ID
WorkId string(digits) 坐席工号
Name string 坐席姓名
Mobile string(phone) 坐席手机号
Email string(Email) 坐席Email
Role string(enum) 可以是agent, leader,默认为agent
Queues [string(digits)] 坐席绑定的队列列表(数组)
QueuesNames string 坐席绑定的队列名
Extensions [Extension] 坐席绑定的分机列表(数组)
DefSpNumber [string(digits)] 坐席的默认中继号
State enum 坐席状态(参考下面的State枚举值
ExtState enum 分机状态(参考下面的ExtState枚举值
WrapUpTime Integer 整理时间,单位为秒
Enable boolean true:启用 false:禁用 默认:true
ExtenInfos string 分机信息

State枚举值

含义
0 准备中
1 就绪
2 锁定
3 通话中
4 不可用

ExtState枚举值

含义
0 ExtStateIdle 分机闲置
1 ExtStateBusy 分机忙
2 ExtStateOnline 分机在线
3 ExtStateOffline 分机离线
4 ExtStateInvalid 分机无效

请求示例

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

响应示例

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

坐席分机绑定

URL: agents/extensions METHOD: POST 注意:一个坐席最多可以绑定两个分机号码,但同时只能使用一个分机

请求参数

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

注意:传递Extensions时注意"[]"(中括号)

返回结果

参数名 类型(格式) 说明
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 '
{
    "AgentId" : "10031",
    "Extensions" : ["2345","9527"]
}
'

响应示例

{
    "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 '
{
  "AgentId":"6655",
  "Extensions":["2345"]
}
'

响应示例

{
    "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 响应描述

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agents/queues?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '
{
    "AgentId" : "10031",
    "Queues" : ["9008"]
}
'

坐席队列解绑

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 响应描述

请求示例

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

队列管理

创建队列

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 排队超时时间(秒),默认为60
MaxLength N number 队列最大长度,默认为128,最大值为512

返回结果

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

请求示例

curl -X POST 'http://ip:port/ccapi/v2/queues?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '
{
    "QueueId":"9009",
    "QueueName":"测试创建队列007"
}
'

修改队列

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 排队超时时间(秒),默认为0
MaxLength N number 队列最大长度,默认为128,最大值为512

返回结果

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

请求示例

curl -X PUT 'http://ip:port/ccapi/v2/queues?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '
{
    "QueueId":"9009",
    "QueueName":"测试创建队列89757",
    "Timeout": 120
}
'

删除队列

URL: queues METHOD: DELETE

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

请求参数

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

返回结果

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

请求示例

curl -X DELETE 'http://ip:port/ccapi/v2/queues?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '{ "QueueId":"9009" }'

获取全部队列信息

URL: queues METHOD: GET

请求参数

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

返回结果

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

Result

参数名 类型(格式) 说明
ID Integer id
CreatedAt date 队列的创建时间
UpdatedAt date 队列的更新时间
AppID string 应用ID
QueueID string(digits) 队列ID
Timeout number 排队超时时间(秒)
Strategy string(enum) 排队策略
AgentID Integer 坐席ID
Name string 队列名称
MaxLength number 队列最大长度
WaitMusic string 排队时播放的音乐

获取队列信息(此接口有问题,暂时忽略)

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

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

请求参数

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

返回结果

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

请求示例

curl -X POST 'http://ip:port/ccapi/v2/queues/agents?Timestamp=1566523582&AppId=a54a8b77-f12d-4ac9-742d-5b2bef5c4d11&Sign=f5f8dd0003c1ef1f2bc820a37c0af0dce18ee0fe&Sid=123456789abcdef' -d '
{
    "QueueId":"9008",
    "AgentIds":["10031", "10032"]
}
'

分机管理

创建分机

URL: extensions METHOD: POST

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

请求参数

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

注意:分机号码为 非0数字开头的四位数字

返回结果

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

Result

参数名 类型(格式) 说明
Extension string(digits) 分机号码
Password string 分机密码
Number 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"}'

响应示例

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

删除分机

URL: extensions METHOD: DELETE

注意: 已经和坐席绑定的分机不能删除

请求参数

参数名 必选项 类型(格式) 说明
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"}'

响应示例

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

话机/手机模式切换

URL: agent/set_call_mode METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
AppId Y string(uuid) 应用ID
AgentId Y string 座席ID
Contact Y string 模式,参见下面的模式列表
Number N 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": "10031",
    "Contact": "cellphone"
}
'

响应示例

{
    "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

注意: 该接口的调用需要一些准备工作:

  1. 有坐席,切换为ip话机模式(手机模式也可以,这里以IP话机举例)
  2. 有分机(下有示例)
{
  "Extension": "8975",
  "Password": "d0942c4e07c038f8",
  "Number": "90310468568975"
}
  1. 坐席和分机绑定
  2. 保证坐席是签入状态
  3. 下载一个软电话 Linphone(PC端软件)

    • 打开软件
    • 新建一个linphone account
    • use a linphone account
    • username : Number
    • sip domain:47.94.221.132:5474
    • Transport : UDP
    • 点击 "USE"
  4. request body 中caller填中继号(该租户下,和该坐席绑定的中继号)

    • 例如中继号为 057126200670,请求体为:
{
  "caller": "057126000000",
  "called": "17600000000",
  "called_display": "057126000000",
  "agent_id": "10032"
}
  1. 发送请求

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(timestamp) 时间戳
AppId Y string(uuid) 应用ID
caller Y string 主叫号码
called Y string 被叫号码
called_display Y string 外显号码
agent_id Y string 座席ID
user_data 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: /ccapi/v2/agent/hold METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
Sid Y string 账号
Sign Y string 签名
call_id Y string 通话记录Call ID
agent_id Y string(digits) 坐席id
on_succ Y string 填任意非空字符串
on_failed Y string 填任意非空字符串

返回结果

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

请求示例

curl -X POST 'http://ip:port/ccapi/v2/agent/hold?Timestamp=1585213823&Sign=zxccvb903ef48ef16225e436bb4a3b134567bb6&Sid=100100100100' -d '
{
  "call_id":"1a8462d7-00fc-4cc2-4567-038ced6ba580",
  "agent_id":"111",
  "on_succ":"demo",
  "on_failed":"demo"
}'

响应示例

{
  "code": "000000",
  "message": "OK",
  "results": ""
}

恢复

URL: /ccapi/v2/agent/hold METHOD: DELETE

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
Sid Y string 账号
Sign Y string 签名
call_id Y string 通话记录Call ID
agent_id Y string(digits) 坐席id
on_succ Y string 填任意非空字符串
on_failed Y string 填任意非空字符串

返回结果

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

请求示例

curl -X DELETE 'http://ip:port/ccapi/v2/agent/hold?Timestamp=1585214251&Sign=qweasd1bfbac11a829123e63b45fb21b3510abd2&Sid=100100100100' -d '
{
    "call_id":"123qwe-00fc-4cc2-a346-038ced6ba580",
    "agent_id":"111",
    "on_succ":"demo",
    "on_failed":"demo"
}'

响应示例

{
  "code": "000000",
  "message": "OK",
  "results": ""
}

转接

URL: /ccapi/v2/transfer/agent METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
Timestamp Y number(Timestamp) 时间戳
Sid Y string 账号
Sign Y string 签名
call_id Y string 通话记录Call ID
agent_id Y string(digits) 坐席id
agent_type Y string 本参数值必须为"anonymous"
agent_phone Y string 转接人电话
on_succ Y string 填任意非空字符串
on_failed Y string 填任意非空字符串
on_record_over Y string 填任意非空字符串
on_transferee_hangup Y string 填任意非空字符串

返回结果

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

请求示例

curl -X POST 'http://ip:port/ccapi/v2/transfer/agent?Timestamp=1585214251&Sign=ea4a2b1bfbac11a829912e63b45fb21b1230abd2&Sid=100100100100' -d '
{
  "call_id":"asdfg272-0afb-4136-81bc-328bbcc606c5",
  "agent_id":"111",
  "agent_type":"anonymous",
  "agent_phone":"10010001000",
  "on_succ":"demo",
  "on_failed":"demo",
  "on_record_over":"demo",
  "on_transferee_hangup":"demo"
}'

响应示例

{
  "code": "000000",
  "message": "OK",
  "results": ""
}

自动外呼任务管理

启动自动外呼任务

URL: ads/task/start METHOD: POST

请求参数

参数名 必选项 类型(格式) 说明
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

请求参数

参数名 必选项 类型(格式) 说明
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

请求参数

参数名 必选项 类型(格式) 说明
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

请求参数

参数名 必选项 类型(格式) 说明
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

请求参数

参数名 必选项 类型(格式) 说明
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

请求参数

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

返回结果

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

事件推送

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

订阅事件

URL: /ccapi/v2/webhooks/events METHOD: POST, 追加订阅事件 PUT : 用body 中事件替换所有替换事件 DELETE : 删除所有事件 NOTE: 由应用层向CTI CLOUD发起订阅事件请求 url 中传参 AppId Timestamp,以及sid,sign 进行校验 body 中请求参数

json形式参数

参数名 必选项 类型(格式) 说明
Events Y [ ]subinfo 事件名称列表, 如下

subinfo:

参数名 必选项 类型(格式) 说明
category Y string 事件名称, 如下 :"agent_state ext_state,agent_call_mode,call"
all_type Y [ ]string 事件名称列表, 如下

events 1. agent_call_mode "agent_call_mode_change" 2. agent_state "acd_agent_state" 3. ext_state ext_state 4. call "agent_breakout", "agent_interrupt", "asr_gather_fail", "asr_gather_succ"," begin","call_notes", "consult_fail", "consult_succ", "dtmf_gather_fail", "dtmf_gather_succ", "eavesdrop_fail", "eavesdrop_succ", "end", "end_consult_fail", "end_consult_succ", "enqueue_succ", "extern_succ", "general_hangup", "hangup_cause", "hold_call", "play_fail", "play_succ", "record_stop", "start_dialout", "start_ivr", "substitute_fail", "substitute_succ", "three_way_fail", "three_way_succ", "transfer_agent_fail", "transfer_agent_succ", "user_answer", "user_hangup", "user_ringing", "voice_mail_fail", "voice_mail_succ"

### 呼叫过程事件 ### 坐席状态变化事件 ### 队列状态变化事件 ### 录音事件

返回结果

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

消息

消息订阅

URL: subscriptions METHOD: POST

请求参数

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

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

返回结果

参数名 类型(格式) 说明
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 通话结束时间

注意: CallId等参数应通过json格式的请求体传递,如果不传,应传一个空的{}请求体,否则会报"100004 unexpected end of JSON input"错误

返回结果

参数名 类型(格式) 说明
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 N number 页大小,最大100
PageNum N number 第几页
StartTime N timestamp 开始时间
EndTime N 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

Code错误码

错误码 message信息 描述
000001 AgentId AppId WorkId Blank 请求参数中缺少AgentId AppId WorkId这三个参数
参数错误 请求参数有误
ParamsInvalid 传入的参数无效
File name Blank 传入的ivr文件名为空
000003 系统内部错误 系统内部错误
000004 数据不存在 待删除的数据不存在
100002 AppId AppNotFound or forbidden 参数中缺少AppId或者appid被禁用了
100004 Duplicate entry xxx for yyy agentId或queueId和已有的重复了
unexpected end of JSON input 请求体不存在或请求体格式有误
agent has queue or voip, can't delete 坐席已绑定队列或ip话机,无法删除
100015 NumberIsExisted 分机号码已存在
100016 VoipBindAgent 绑定坐席的分机不能删除
100017 AppID Blank 参数中缺少AppId
100018 RecordNotFound 根据请求体中传入的agentId找不到对应的资源,可能是坐席、队列、ivr语音记录等
queue Blank 根据传入的queueId找不到队列