# 呼叫系统
# 呼叫事件对接
- 呼叫中心用户电话呼入的时候,七鱼系统通过该接口向第三方系统获取用户信息,包括访客VIP级别、外接IVR路由、crm信息,根据获取到的信息进行访客分配,及访客信息更新;IVR过程中,
IVR校验
以及导航项动作自定义IVR接口
和播放内容接口
也使用该接口对接;通话结束后,同步通话记录
使用该接口对接。通过参数eventtype
进行区分。 - 对接URL配置在七鱼系统中:系统管理》扩展与集成》CRM信息对接》呼叫对接接口URL
参数eventtype
类型说明:
参数值 | 参数说明 |
---|---|
1 | 获取访客信息 |
2 | IVR校验 |
3 | 自定义IVR接口 |
4 | 播放内容接口 |
5 | 挂断时同步通话记录 |
6 | 同步电话服务记录字段 |
7 | 接起时同步通话记录 |
8 | 外呼时同步通话信息 |
9 | 外呼任务同步自定义字段 |
10 | 回铃音检测结果 |
11 | IVR数据请求 |
七鱼服务器向第三方接口请求信息时,采用密钥安全认证机制,保证第三方系统的信息安全。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 调用说明
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# curl请求样例如下
1.电话呼入或呼出时,获取并更新打通用户信息(包括访客名称、VIP级别)或更新呼入路由信息(路由客服、客服组或IVR)
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 1,
"phone": "15854582215", //访客号码
"staffphone": "05718669163" //客服号码
}'
2.IVR校验请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 2,
"phone": "15854582215", //访客号码
"staffphone": "05718669163", //客服号码
"sessionid": 216629286, //会话ID
"ivrid": 3545, //IVR导航ID
"keyrecord": "2-1-0", //按键记录
"input": "110226198501272116" //访客按键输入值
}'
3.IVR过程中自定义IVR接口
事件通知
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 3,
"phone": "15854582215",
"staffphone": "05718669163",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "1-3"
}'
4.IVR过程中播放内容接口
请求播放内容
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 4,
"phone": "15854582215",
"staffphone": "05718669163",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "1-2"
}'
5.通话结束后同步通话记录
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 5,
"sessionid": 216629286, //通话记录ID
"direction": "呼入", //方向,呼入或呼出
"createtime": "2022-04-22 16:41:15", //通话创建时间
"endtime": "2022-04-22 16:41:16", //通话结束时间
"connectionbeginetime": "2022-04-22 16:41:16", //接通时间
"connectionendtime": "2022-04-22 16:41:16", //挂断时间
"from": "15854582215", //主叫号码
"to": "05718690766", //被叫号码
"user": "客户名称",
"category": "售后问题/退货", //咨询分类
"staffid": 642656, //接待客服ID
"staffname": "丽娜", //接待客服名称
"status": "接通", //会话状态
"visittimes": 1, //重复咨询次数
"duration": "10:15", //通话时长
"evaluation": "满意", //满意度评价
"recordurl": "https://ysf.nosdn.127.net/9f670ff01dae290ad4bf83401d291069.wav", //通话录音文件地址
"overflowFrom": "溢出来源",
"shuntGroupName":"分流客服组",
"ivrPath":"ivr路径",
"mobileArea":"号码归属地",
"waitDuration":"5分10秒", //排队等待时长
"ringDuration":"1小时10分", //振铃时长
"sessionIdFrom": 216629286, //转接至该会话的上一通会话id
"firstEndDirection":"用户", //挂机方,客服、用户、--
}'
6.通话结束后同步电话服务记录字段
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 6,
"sessionid": 216629286,
"from": "15854582215",
"to": "05718690766",
"counselCategory":"咨询分类1/咨询分析2/咨询分类3",
"remarks":"咨询小计",
"customValueArray":[
{
"key":"自定义字段1",
"value":"自定义value1"
},
{
"key":"自定义字段2",
"value":"自定义value2"
}
]
}'
7.通话接起时同步通话记录
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 7,
"sessionid": 216629286,
"direction": "呼入",
"createtime": "2022-04-22 16:41:15",
"connectionbeginetime": "2022-04-22 16:41:16",
"from": "15854582215",
"to": "05718690766",
"user": "客户名称",
"staffid": 642656,
"staffname": "丽娜",
"status": "接通", //会话状态
"visittimes": 1, //重复咨询次数
"overflowFrom": "溢出来源", // 溢出来源组名称
"shuntGroupName":"分流客服组",
"ivrPath":"ivr路径",
"mobileArea":"号码归属地",
"sessionIdFrom": 216629286, //转接至该会话的上一通会话id
}'
8.坐席外呼时同步通话信息
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 8,
"sessionid": 216629286,
"direction": "呼出",
"createtime":"2022-04-22 16:41:15",
"from": "15854582215",
"to": "05718690766",
"user": "客户名称",
"staffid": 642656,
"staffname": "丽娜",
"mobileArea":"号码归属地"
}'
9.外呼结束时同步任务自定义字段
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 9,
"sessionid": 216629286, //通话ID
"callTaskId": 111, //任务ID
"guestPhone": "15854582215", //客户手机号
"guestName": "张三", //客户名称
"remarks": "" //外呼更多资料(备注)
}'
10.外呼未接通时同步回铃音检测结果
请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 10,
"sessionid": 216629286, //通话ID
"from": "15854582215", //主叫
"to": "05718690766", //被叫
"status": "无法接通-关机" //检测结果(无法接通-无法接通、无法接通-忙线中、无法接通-关机、无法接通-停机、无法接通-空号、无法接通-欠费、无法接通-外呼失败)
}'
11.IVR到数据请求节点时获取数据
请求,请求的参数字段,为ivr数据请求节点上面设置的参数字段,字段名称保持一致
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 11,
"city":"杭州"
}'
通话记录数据项补充说明:
- resolved : 通话问题解决状态,0表示未解决,1表示已解决,2表示解决中
- connectionbeginetime : 主叫和被叫双方通道开始建立的时间
- connectionendtime : 主叫或被叫通道最早断开的时间
- createtime : 主叫发起通话的时间
- endtime : 主叫或被叫通道最晚断开的时间
- direction : 通话方向
- 呼入
- 呼出
- status : 通话的最终状态
- 接通
- 客服未接听
- 无法接通-无法接通
- 无法接通-忙线中
- 无法接通-关机
- 无法接通-停机
- 无法接通-空号
- 无法接通-欠费
- 无法接通-外呼失败
- 无法接通-网络不稳定
- 无法接通-骚扰拦截
- 无人应答
- IVR中放弃
- 队列中放弃
- 队列中溢出
- 不在服务时间
- 无客服在线
- 转接成功
- IVR服务
- IVR信息校验失败
- 客户快速挂机
- 客服未接听(自动外呼)
- 无空闲坐席(自动外呼)
- evaluation : 评价结果
- 非常满意
- 满意
- 一般
- 不满意
- 非常不满意
# 第三方接口需返回的数据的说明
接口返回数据为JSON格式,最外层参数如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
code | 是 | 返回码,200表示成功。如eventtype=2时,200就表示校验通过;eventtype=3时,200表示动作执行成功等。 |
result | 否 | code为200时,该返回值有效。eventtype=1时返回访客信息,为JSON格式数据;eventtype=4时返回播放的文本内容,为String格式数据;eventtype= 11时返回IVR数据请求节点需要的信息,字段与ivr数据请求节点设置字段名称保持一致,为JSON格式,其他值可以为空。 |
message | 否 | 请求错误时,填错误提示信息。 |
当eventtype=1时,result
数据格式如下:
参数 | 是否必须 | 数据类型 | 参数说明 |
---|---|---|---|
uid | 否 | String | 访客唯一标识ID |
name | 否 | String | 访客姓名 |
level | 否 | Int | 访客VIP级别,值为0到10 |
groupId | 否 | Int | 分流客服组ID(呼入) |
staffId | 否 | Int | 分流客服ID(呼入) |
ivrId | 否 | Int | 分流到指定IVR(呼入) |
- 非VIP用户
level
等于0,VIP级别等级为1到10数值 groupId
和staffId
值对应七鱼系统中的客服组ID和客服ID,从七鱼管理后台「在线系统」->「设置」->「会话流程」->「访客分配」->「分配规则」->「ID查询」中查找获取。ivrId
对应七鱼系统中的ivrId
,从七鱼管理系统「呼叫系统」->「设置」->「路由策略」->「IVR语音导航」中查找获取。三种ID的优先级为:staffId
->groupId
->ivrId
。- 如果只设置了
staffId
,七鱼会查找staffId
对应的呼叫客服,如果该客服正好空闲的话,电话将优先分配给他。 - 如果设置了
staffId
和groupId
,七鱼会优先查找staffId
对应的呼叫客服,如果该客服正好空闲,电话将优先分配给他,否则系统判断是否有返回groupId
值。如果有groupId
值,系统再优先查找groupId
对应的呼叫客服组进行分配。 - 如果只设置了
groupId
,七鱼会优先查找groupId
对应的呼叫客服组,如果该客服组内正好有空闲客服,电话将随机分配给空闲的客服。如果该客服组内没有空闲客服,若有溢出规则,则按溢出规则走。 - 如果只设置了
ivrId
,七鱼会优先按照ivrId
来进行分配,会忽略ivr会员等级分配策略。 - 如果没有返回
staffId
、groupId
和ivrId
三种中的任意一种,或者返回的值不存在,则七鱼将执行一般IVR分流。
- 如果只设置了
返回的完整参数格式如下:
{
"code": 200,
"message": "",
"result": {
"level": 0,
"groupId": 415451,
"staffId": 2164623,
...
}
}
# 第三方接口样例
以SpringMVC
框架为例,第三方系统提供的接口如下:
@RequestMapping(value = "/crminfo", method = RequestMethod.POST)
@ResponseBody
public String getClientCrmInfoByPhone(
@RequestParam(value = "checksum", required = true) String checksum,
@RequestParam(value = "time", required = true) String time,
@RequestBody(required = true) String jsonStr
) {
// 此处省略业务代码
}
# 外呼任务
# 创建外呼任务
该接口由七鱼提供,第三方调用该接口可以自动生成营销相关的外呼任务,方便呼叫客服及时联系客户,从而提升营销质量
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 请求示例
POST请求body参数为jsonStr格式,POST请求参数样例如下:
{
"name": "意向客户回访",
"description": "新注册用户回访",
...
...
}
# 参数说明
外呼任务的客服类型支持客服和客服组三种模式,当seatType
=0|1,需要同时传递seatIds
,当seatType
=3,需要同时传递amount
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
name | String | 是 | 任务名称 |
description | String | 否 | 任务描述 |
startTime | Long | 否 | 任务绝对开始时间,单位为毫秒 |
endTime | Long | 否 | 任务绝对结束时间,单位为毫秒 |
seatType | Integer | 否 | 指定客服类型,0-客服,1-客服组,2-按客户关系分配 3-按自定义客户分配 |
seatIds | String | 否 | 客服的id串或者客服组id串,以逗号分隔。当seatType =0时,代表客服的id;当seatType =1时,代表客服组的id,会顺序分配给指定组内的呼叫客服。客服客服组信息查询 (opens new window) |
amount | List JsonObject | 否 | 指定客服分配信息健值对,为Json数组 |
customerInfo | List JsonObject | 是 | 用户号码信息键值对,为Json数组(用户信息数量最大为2000条) |
customerInfo.name | String | 是 | 用户名 |
customerInfo.value | String | 是 | 用户手机号 |
customerInfo.staffId | Long | 否 | 客户负责人staffId |
forecastType | Integer | 否 | 任务类型, 0:普通外呼任务, 1:自动外呼任务 |
forecastRate | Double | 否 | 自动外呼任务的倍率值,取值范围:0.01 至 5.00, forecastType=1时有效 |
forecastDids | String | 否 | 自动外呼任务的企业号码DID, 格式为:a,b,c 号码用英文逗号隔开的数组 |
customTemplateId | Long | 否 | 外呼任务信息模板, 非必填, 默认系统预设模板 ,详情请查看获取服务记录模板 |
repeatSwitch | Integer | 否 | 自动外呼的重复呼叫的开关 0:关闭,1:开启 (只有在自动外呼情况下使用) |
repeatStatus | List Integer | 否 | 自动外呼的重复呼叫状态条件,类型:List 3:无法接通,4:无人应答,14:客服未接听(自动外呼),15:无空闲客服(自动外呼)(仅在自动外呼且重复呼叫开启时生效) |
repeatNum | Integer | 否 | 自动外呼的重复呼叫次数, 取值:1或者2 (仅在自动外呼且重复呼叫开启时生效) |
repeatInterval | Integer | 否 | 自动外呼的重复呼叫时间间隔,取值:1到1440,单位分钟 (仅在自动外呼且重复呼叫开启时生效) |
具体响应格式如下:
参数 | 参数说明 |
---|---|
code | 错误码 |
message | 错误描述 |
data | json对象 |
data.id | 任务ID |
# 请求示例
接口说明: 接口路径
https://www.qiyukf.com/openapi/ipcc/calltask/marketing
已经停止维护,请使用新的接口路径https://www.qiyukf.com/openapi/ipcc/calltask/add
curl请求样例如下:
1.指定分配到客服,即seatType
=0时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"name": "意向客户回访",
"description": "新注册用户回访",
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 0,
"seatIds": "40004,40005",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"remarks": ""
}
]
}'
2.指定分配到客服组,即seatType
=1时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"name": "意向客户回访",
"description": "新注册用户回访",
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 1,
"seatIds": "62451,511186",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"remarks": ""
}
]
}'
3.指定按客户关系分配(按照参数指定的分配客服),即seatType
=2时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"name": "意向客户回访",
"description": "新注册用户回访",
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 2,
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"staffId": "1234",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"staffId": "1235",
"remarks": ""
}
]
}'
4.指定按自定义的客户分配(给指定客服分配指定数量的外呼),即seatType
=3时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 3,
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"remarks": ""
}
],
"amount": [
{
"count": 1,
"seatId": "21321"
},
{
"count": 1,
"seatId": "12312"
}
]
}'
5.如果是自动外呼任务时,只需要扩展七项参数即可,其它参数保持不变
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 0,
"seatIds": "40004,40005",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"remarks": ""
}
],
"forecastType":1,
"forecastRate":1.05,
"forecastDids":"057110000000,057110000001,057110000002",
"repeatSwitch":1,
"repeatStatus":[3,4,14,15],
"repeatNum":1,
"repeatInterval":5
}'
# 补充自动外呼号码
该接口由七鱼提供,第三方调用该接口可以补充自动外呼任务的号码,方便呼叫客服及时联系客户,从而提升营销质量
# 接口限制条件
- 1、任务类型:自动外呼任务
- 2、任务周期:周期不大于1周的任务
- 3、任务状态:未过期任务
- 4、一次插入条数:小于等于1000条号码
- 5、频次:上一次外呼任务插入未完成,则接口调用失败
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
taskId | Long | 是 | 任务ID |
customerInfo.name | String | 否 | 客户名称 |
customerInfo.value | String | 是 | 客户号码 |
customerInfo.remarks | String | 否 | 备注(外呼更多资料) |
具体响应格式如下:
参数 | 参数说明 |
---|---|
code | 错误码 |
message | 错误描述 |
# 请求示例
curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"taskId": 1,
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912",
"remarks": ""
},
{
"name": "小喽喽",
"value": "15411660066",
"remarks": ""
}
]
}'
# 获取外呼任务详情
该接口由七鱼提供,第三方调用该接口获取任务详情
# 接口限制条件
- 1、任务类型:自动外呼任务 , 手动外呼任务
- 2、频次:一分钟
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 请求示例
POST请求body参数为jsonStr格式,POST请求参数样例如下:
{
"taskId": 1,
}
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
taskId | Long | 是 | 任务ID |
具体响应格式如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
code | Integer | 返回码 |
message | String | 错误信息描述 |
data.forecastType | Integer | 任务类型,0:预览式外呼, 1:预测式外呼 |
data.status | Integer | 状态 |
data.customCount | Integer | 客户数量 |
data.staffCount | Integer | 客服数量 |
data.startTime | Long | 开始时间 |
data.endTime | Long | 结束时间 |
data.exeCount | Integer | 执行数量 |
data.answerCount | Integer | 接通数量 |
data.desc | String | 描述 |
data.name | String | 任务名称 |
data.seatNames | String | 分配坐席 |
响应数据说明:
- status : 状态
- 0 : 正常
- 1 : 暂停
- 2 : 已删除
- 3 : 未分配
# 请求示例
接口说明: 接口路径
https://www.qiyukf.com/openapi/ipcc/autoCalltask/get
已经停止维护,请使用新的接口路径https://www.qiyukf.com/openapi/ipcc/calltask/get
curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/get?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{"taskId": 1}'
# 获取外呼任务明细详情
该接口由七鱼提供,第三方调用该接口获取任务明细详情
# 接口限制条件
- 频次:一分钟
- 分页: 一页
2000
条
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 请求示例
POST请求body参数为jsonStr格式,POST请求参数样例如下:
{
"taskId": 1,
"page": 1
}
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
taskId | Long | 是 | 任务ID |
page | Integer | 否 | 页码,默认从1开始 |
具体响应格式如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
code | Integer | 返回码 |
message | String | 错误描述 |
data.id | Long | 任务明细ID |
data.taskId | Long | 任务ID |
data.guestName | String | 客户名称 |
data.guestNumber | String | 电话号码 |
data.staffName | String | 分配坐席 |
data.callCount | Integer | 呼叫次数 |
data.callResult | String | 结果 |
data.remarks | String | 外呼更多资料 |
data.callOutDuration | Long | 通话时长(秒) |
data.sessionId | Long | 通话ID |
响应结果数据说明:
- callResult
- 0 : 未呼叫
- 1 : 未接通
- 2 : 已接通
# 请求示例
curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/get?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{"taskId":1659354,"page":1}'
{
"code": 200,
"data": {
"total": 100,
"data":[
{
"id": 18113113, //任务明细ID
"taskId": 1659354, //任务ID
"guestName": "guest66987", //客户名称
"guestNumber": "13123456789", //电话号码
"staffName": "",//分配坐席
"callCount": 1,//呼叫次数
"callResult": 1,//结果
"remarks": "", //外呼更多资料
"callOutDuration": -1 //通话时长
"sessionId": 1234567890 //通话ID
}
]
},
"message": ""
}
# 编辑手动外呼任务
该接口由七鱼提供,第三方调用该接口可编辑手动外呼任务详情,减少因为内部原因产生的错误呼出量及对用户体验的伤害
# 接口限制条件
- 1、任务类型:手动外呼任务
- 2、任务状态:待分配,未开始,进行中
- 3、任务明细状态:未呼叫
- 4、一次编辑条数:小于等于100条号码
- 5、一次编辑的影响的任务数:小于等于100个
- 6、频次:上一次外呼任务编辑未完成,则接口调用失败
- 7、数据安全:编辑任务详情时候,会锁定任务。故不要高频操作,3分钟内只能操作一次。
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 请求示例
POST请求body参数为jsonStr格式,POST请求参数样例如下:
{
"taskId": 1,
"taskDetails": [
{
"id":"1110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"1111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
...
...
}
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
taskId | Long | 是 | 任务ID |
taskDetails | List JsonObject | 是 | 任务详情 |
taskDetails.id | Long | 是 | 任务详情Id |
taskDetails.username | String | 否 | 客户名称 |
taskDetails.phone | String | 否 | 客户电话号码 |
taskDetails.description | String | 否 | 备注(外呼更多资料) |
具体响应格式如下:
参数 | 参数说明 |
---|---|
code | 错误码 |
message | 错误描述 |
任务详情编辑请求样例 curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/update?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '[
{
"taskId": 1,
"taskDetails": [
{
"id":"1110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"1111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
},{
"taskId": 2,
"taskDetails": [
{
"id":"2110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"2111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
}
]'
# 删除外呼任务号码
该接口由七鱼提供,第三方调用该接口可删除手动外呼任务详情,减少由于内部原因产生的错误呼出量及对用户体验的伤害
# 接口限制条件
- 1、任务类型:手动外呼任务
- 2、任务状态:待分配,未开始,进行中
- 3、任务明细状态:未呼叫
- 4、一次删除条数:小于等于100条号码
- 5、一次删除的影响的任务数:小于等于100个
- 6、频次:上一次外呼任务删除未完成,则接口调用失败
- 7、数据安全:删除任务详情时,会锁定任务。故不要高频操作,3分钟内只能操作一次
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 请求示例
POST请求body参数为jsonStr格式,POST请求参数样例如下:
{
"taskId": 1,
"taskDetailIds": [123,1213],
...
...
}
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
taskDetailIds | List Long | 是 | 任务详情Ids |
具体响应格式如下:
参数 | 参数说明 |
---|---|
code | 错误码 |
message | 错误描述 |
任务详情编辑请求样例 curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/delete?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '[
{
"taskDetailIds": [123,1231]
},{
"taskDetailIds": [1232,12312]
}
]'
# 服务记录
# 获取服务记录模板
该接口由七鱼提供,第三方调用该接口获取服务记录模板
# 接口限制条件
- 1、返回指定模板的所有启用状态模板
# 接口调用
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
templateType | Integer | 是 | 模板类型, 必传, 1: 外呼任务信息模板 |
具体响应格式如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
code | Integer | 返回码 |
message | String | 错误描述 |
data.id | Long | 模板id |
data.name | String | 模板名称 |
data.description | String | 模板描述 |
# 请求示例
curl请求样例如下:
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/customfield/template/get?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"templateType": 1
}'
# 数据接口
# 呼叫总览数据
注: 此接口频控1分钟10次
POST 请求
https://qiyukf.com/openapi/ipcc/realtime/overview/data?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
# 请求体参数说明
示例:
{
"kefuGroupList": [123323,3232]
}
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
kefuGroupList | List Long | 否 | 客服组ID列表 |
# 返回值说明:
{
"code": 200,
"message": "success",
"data": {
...
}
}
其中"data"说明如下:
{
"queueSize":0, // 当前排队量
"inTotal":1494, // 呼入总量
"outTotal":2367, // 呼出总量
"relativeSatisfactionRatio":0.9279, // 满意度
"callSessionTotalCount":3861, // 电话总量
"callSessionTotalTime":361349091, // 通话总时长
"callInTotalTime":223537960, // 呼入总时长
"callOutTotalTime":137811131, // 呼出总时长
"queueTimeMax":137811131, // 最长排队时长
"avgQueueTime":23569, // 平均排队时长
"callInRadio":0.7718, // 呼入接起率
"callOutRadio":0.5006, // 呼出接起率
"callingStaffCount":5, // 正在通话中的客服数量
"resoveStaffCount":0, // 处理中的客服数量
"restStaffCount":0, // 小休坐席数
"hangupStaffCount":0, // 挂起坐席数
"onlineStaffCount":2, // 空闲坐席数
"sipOnlineStaffCount":4, // sip在线坐席数
"mobileOnlineStaffCount":5, // 手机在线坐席数
"forecastOnlineStaffCount":5, // 自动外呼坐席数
"evaluatedRadio":0.5006, // 参评率
"evaluatedCount":6, // 参评数
"queueAnswerRadio":0.5006, // 队列接通率
"ringingPickRatio":0.5006 // 振铃摘机率
}
# 呼叫总览数据(废弃)
(此接口不再升级维护,会逐步下线掉,建议使用新接口替代)
注: 此接口连续两次请求间隔不能小于五分钟
POST 请求
https://qiyukf.com/openapi/data/overview/ipcc?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容为空(空json对象即"{}"),但是也要加入鉴权
返回值说明:
{
"code":200,
"message":"{..}"
}
其中message说明如下:
{
"queueSize":0, // 当前排队量
"inTotal":1494, // 呼入总量
"outTotal":2367, // 呼出总量
"relativeSatisfactionRatio":0.9279, // 满意度
"callSessionTotalCount":3861, // 电话总量
"callSessionTotalTime":361349091, // 通话总时长
"callInTotalTime":223537960, // 呼入总时长
"callOutTotalTime":137811131, // 呼出总时长
"avgQueueTime":23569, // 平均排队时长
"callInRadio":0.7718, // 呼入接起率
"callOutRadio":0.5006, // 呼出接起率
"callingStaffCount":5, // 正在通话中的客服数量
"resoveStaffCount":0, // 处理中的客服数量
"restStaffCount":0, // 小休坐席数
"hangupStaffCount":0, // 挂起坐席数
"onlineStaffCount":2 // 空闲坐席数
}
# 呼叫坐席历史数据
# 接口说明
- 数据时长为
T+1
的数据 - 接口连续两次请求间隔不小于五分钟
- 请求最大时长为
90
天
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
startTime | Long | 否 | 开始时间,时间戳 |
endTime | Long | 否 | 结束时间,时间戳.开始和结束时间均不传的情况下,会查询近一个月的数据 |
model | Integer | 否 | 1-全部(默认),2-客服组列表,3-客服列表 |
staffGroupList | List Long | 否 | 客服组ID列表,模式 2 时有效 |
staffIdList | List Long | 否 | 客服ID列表,模式 1 时有效 |
# 请求示例
注: 此接口连续两次请求间隔不能小于五分钟 POST 请求
https://qiyukf.com/openapi/ipcc/history/seat?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
{
"startTime": 1615950729000,
"endTime": 1615950729000,
"model": 1,
"staffGroupList": [1,2,3],
"staffIdList":[1,2,3]
}
# 返回值说明:
{
"code":200,
"message": "[{..}]" //字符串
}
其中message说明如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
staffId | Number | 客服ID |
staffName | String | 客服名字 |
startTime | Number | 统计日期开始时间 |
endTime | Number | 统计日期结束时间 |
totalCount | Number | 话务总量 |
callInCount | Number | 呼入量 |
callOutCount | Number | 呼出量 |
callDuration | Number | 通话总时长 |
callInDuration | Number | 呼入总时长 |
callOutDuration | Number | 呼出总时长 |
avgCallDuration | Number | 平均通话时长 |
avgCallInDuration | Number | 平均呼入时长 |
avgCallOutDuration | Number | 平均呼出时长 |
callOutAnsweredRatio | Number | 呼出接通率 |
satisfactionRatio | Number | 相对满意率 |
evaluateCount | Number | 参评数 |
evaluateRatio | Number | 参评率 |
inviteEvaluateCount | Number | 邀评数 |
inviteEvaluateRatio | Number | 邀评率 |
onlineDuration | Number | 在线总时长 |
forecastDuration | Number | 自动外呼时长 |
# 呼叫团队历史总览数据
# 接口说明
- 数据时长为
T+1
的数据 - 接口连续两次请求间隔不小于五分钟
- 请求最大时长为
90
天
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
startTime | Long | 否 | 开始时间,时间戳 |
endTime | Long | 否 | 结束时间,时间戳.开始和结束时间均不传的情况下,会查询近一个月的数据 |
staffGroupList | List Long | 否 | 客服组ID列表, |
# 请求示例
注: 此接口连续两次请求间隔不能小于五分钟 POST 请求
https://qiyukf.com/openapi/ipcc/history/team?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
{
"startTime": 1615950729000,
"endTime": 1615950729000,
"staffGroupList": [1,2,3]
}
# 返回值说明:
{
"code":200,
"message": "[{..}]" //字符串
}
其中message说明如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
callSessionTotalCount | Number | 话务总量 |
callInCount | Number | 呼入量 |
callOutCount | Number | 呼出量 |
callInIc2HumanCount | Number | 外呼机器人转人工量 |
callInAnswerCount | Number | 呼入接通量 |
callOutAnswerCount | Number | 呼出接通量 |
inServiceCallInCount | Number | 服务时间呼入量 |
inServiceCallInAnswerRatio | Number | 服务时间呼入接通率 |
pickupSecondRatio | Number | x秒振铃摘机率 |
staffPickupSecondRatio | Number | x秒客服振铃摘机率 |
ringUpAnsweredSecond | Number | 振铃摘机率时间区间 |
callOutAnswerRatio | Number | 呼出接通率 |
callInLength | Number | 呼入时长(毫秒) |
callOutLength | Number | 呼出时长(毫秒) |
avgCallInTime | Number | 呼入平均时长(毫秒) |
avgCallOutTime | Number | 呼出平均时长(毫秒) |
oneOffRatio | Number | 一次性解决率 |
queueCount | Number | 排队量 |
avgQueueTime | Number | 平均排队时长(毫秒) |
callLossCount | Number | 呼损量 |
inServiceCallLossCount | Number | 服务时间呼损量 |
seatUseRatio | Number | 客服利用率 |
queueCallInCount | Number | 队列呼入量 |
queueConnectedRatio | Number | 队列接通率 |
connectSecondRatio | Number | x秒队列接通率 |
connectSecond | Number | 队列接通率时间区间 |
callLossRadio | Number | 呼损率 |
inServiceCallLossRatio | Number | 服务时间呼损率 |
ivrGiveUpCount | Number | IVR中放弃量 |
queueGiveUpCount | Number | 队列中放弃量 |
queueOverflowCount | Number | 队列中溢出量 |
notInServiceCount | Number | 非服务时间呼入量 |
noKefuCount | Number | 无客服在线量 |
unAnswerCount | Number | 客服未接听量 |
missedCallinPlanCount | Number | 顺振未接听量 |
ivrCheckFailedCount | Number | IVR信息校验失败量 |
unConnectCount | Number | 无法接通量 |
quickHangupCount | Number | 客户快速挂机量 |
satisfactionRatio | Number | 满意率 |
callInSatisfactionRatio | Number | 呼入满意率 |
callOutSatisfactionRatio | Number | 呼出满意率 |
satisfactionDetailTotal | Object | 满意率详情(satisfaction) |
satisfactionDetailCallIn | Object | 呼入满意率详情(satisfaction) |
satisfactionDetailCallOut | Object | 呼出满意率详情(satisfaction) |
evaluateCount | Number | 参评数 |
evaluateRatio | Number | 参评率 |
inviteEvaluateCount | Number | 邀评数 |
inviteEvaluateRatio | Number | 邀评率 |
其中 satisfaction
说明如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
level2BadCount | Number | 二级不满意量 |
level2GoodCount | Number | 二级满意量 |
level3BadCount | Number | 三级不满意量 |
level3GoodCount | Number | 三级满意量 |
level3SosoCount | Number | 三级一般量 |
level4BadCount | Number | 四级不满意量 |
level4GoodCount | Number | 四级满意量 |
level4VeryBadCount | Number | 四级非常不满意量 |
level4VeryGoodCount | Number | 四级非常满意量 |
level5BadCount | Number | 五级不满意量 |
level5GoodCount | Number | 五级满意量 |
level5SosoCount | Number | 五级一般量 |
level5VeryBadCount | Number | 五级非常不满意量 |
level5VeryGoodCount | Number | 五级非常满意量 |
# 坐席考勤报表
# 接口说明
提供呼叫系统->历史数据->坐席报表->坐席考勤报表,推荐查询周期在一个月(31天)内的数据,频率限制为1分钟一次,默认只查询所传参数获取数据的前100条数据,若想获取全部客服或客服组的数据,请分批次传客服/客服组
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
startTime | Long | 否 | 开始时间,时间戳 |
endTime | Long | 否 | 结束时间,时间戳.开始和结束时间均不传的情况下,会查询近一个月的数据 |
model | Integer | 否 | 1-全部(默认),2-客服组列表,3-客服列表 |
staffGroupList | List Long | 否 | 客服组ID列表,模式 2 时有效 |
staffIdList | List Long | 否 | 客服ID列表,模式 1 时有效 |
page | Integer | 否 | 当前分页查询的页码,从1开始,默认为1 |
pageSize | Integer | 否 | 分页查询的数量,取值范围1~1000,默认为100 |
# 请求示例
注: 此接口连续两次请求间隔不能小于一分钟 POST 请求
https://qiyukf.com/openapi/ipcc/history/seatAttendance?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
{
"startTime": 1615950729000,
"endTime": 1615950729000,
"model": 1,
"staffGroupList": [1,2,3],
"staffIdList": [63294,80624,46334],
"page": 1,
"pageSize": 100
}
# 返回值说明:
{
"code":200,
"message": "[{..}]" //字符串
}
其中message说明如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
starttime | Number | 日期 |
id | Number | 坐席ID |
username | Number | 坐席姓名 |
workDuration | Number | 值班时长 |
firstLoginSystem | Number | 首次登陆时间 |
onlineDuration | Number | 在线时长 |
onlineFreeDuration | Number | 在线空闲时长 |
forecastCallDuration | Number | 自动外呼时长 |
restDuration | Number | 小休总时长 |
rest1Duration | Number | 小休-就餐时长 |
rest2Duration | Number | 小休-会议时长 |
rest3Duration | Number | 小休-培训时长 |
rest4Duration | Number | 小休-休息时长 |
rest5Duration | Number | 小休-洗手间时长 |
rest6Duration | Number | 小休-其他时长 |
pendDuration | Number | 挂起时长 |
dealingDuration | Number | 处理时长 |
talkingDuration | Number | 通话时长 |
outTalkingDuration | Number | 呼出通话时长 |
inTalkingDuration | Number | 呼入通话时长 |
onMobileDuration | Number | 手机在线时长 |
firstLogin | Number | 首次上线时间 |
lastLogout | Number | 最后登出时间 |
# 坐席当前状态报表
# 接口说明
在使用本接口前,请选阅读七鱼消息接口的通用加密和鉴权规范,地址为 七鱼消息接口开发文档。使用该接口,可以获取到本企业当前所有已登录的客服状态,以便管理客服,以及动态调整客服会话分配规则等。由于涉及到统计操作,该接口有频控管理,目前限制为每分钟 60次。
# 参数说明
具体请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
model | Integer | 否 | 1-全部(默认),2-客服组列表,3-客服列表 |
staffGroupList | List Long | 否 | 客服组ID列表,模式 2 时有效,上限100个 |
staffIdList | List Long | 否 | 客服ID列表,模式 1 时有效,上限1000个 |
page | Integer | 否 | 当前分页查询的页码,从1开始,默认为1 |
pageSize | Integer | 否 | 分页查询的数量,取值范围1~1000,默认为1000 |
# 请求示例
POST 请求
https://qiyukf.com/openapi/ipcc/seatStatus?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
{
"model": 1,
"staffGroupList": [1,2,3],
"staffIdList": [63294,80624,46334],
"page": 1,
"pageSize": 1000
}
# 返回值说明:
{
"code":200,
"message": "[{..}]" //字符串
}
其中message说明如下:
参数 | 参数类型 | 参数说明 |
---|---|---|
id | Number | 坐席ID |
state | String | 坐席状态 |
stateDuration | Number | 当前状态持续时间 |
# 获取咨询分类
该接口用于获取企业管理后台配置的咨询分类,以五级树状结构的形式给出。
接口请求示例
POST https://qiyukf.com/openapi/ipcc/category/list?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求字段说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
type | 是 | 目前固定传1,代表获取呼叫会话的咨询分类 |
请求内容示例:
{
"type": 1
}
接口返回管理后台设置的咨询分类,格式为 JSON,字段说明如下:
数据键名 | 数据类型 | 数据说明 |
---|---|---|
id | Long | 可唯一标识一个分类的ID |
name | String | 咨询分类的名称 |
children | List | 该分类下的子分类 |
# 呼叫工具条
呼叫工具条功能作为一个嵌入式插件提供给需要呼叫工具条的第三方网站使用。建议第三方在需要嵌入的页面加载成功后,通过异步接口向自己服务器端发起请求,获取工具条的SDK
地址,并完成工具条SDK
加载以及外呼拨号对接后即可使用。在异步接口中,第三方需要根据当前登录的客服,获取客服对应的账号信息,向七鱼发起HttpClient请求,来获取七鱼动态生成的SDK
文件地址。前端页面拿到SDK
地址之后,将其作为js文件进行加载即可完成工具条的初始化,再配合工具条提供的拨号接口,即可完成工具条功能的接入。
功能使用步骤拆解:
步骤1: 向自己服务器端发起异步请求,获取工具条的`SDK`地址;
步骤2: 加载SDK并进行初始化设置;
步骤3: (按需使用) 初始化完成后,进行SDK接口调用;
# 注意
# 确保使用https协议的页面
由于呼叫工具条使用了 webRTC 功能,必须在 https 页面中加载呼叫工具条(本地调试可以使用 localhost 页面)
# Safari 浏览器和 iOS webview 登录注意事项
由于Safari浏览器对第三方 Cookie的限制 (opens new window),Safari浏览器和iOS webview无法按正常流程无感登录,需要用户进行额外的操作:
# 1. 监听cookieAccessibleChanged事件
代码示例:
qiConnect.on({cookieAccessibleChanged: function(data){
if (data.result) {
console.log('此时可以获取cookie');
} else {
console.log('没有获取cookie权限');
// 【非常重要】如果已经隐藏了工具条,请务必暂时将工具条置为可见状态,才能点击按钮授权
}
}});
该事件会监听呼叫工具条获取cookie权限的变化,当可以正常获取cookie时,无需其他操作;如果呼叫工具条没有获取cookie的权限,界面会展示一个【获取授权】按钮:
# 2. 点击按钮授权
点击【获取授权】按钮,浏览器会打开一个新的tab页,提示授权成功。点击页面内的【确定】按钮,该页面会关闭,回到加载呼叫工具条的页面
# 3. 再次授权
回到加载呼叫工具条的页面后,可以看到原来的【获取授权】按钮变为【请再次获取授权】,点击按钮,即可加载呼叫工具条。同时也会监听到cookieAccessibleChanged事件,提示此时可以正常获取cookie
# 说明
以上流程不是每次加载呼叫工具条都必须操作。根据Webkit的说法,如果用户在30天内在授权成功页面点击过【确定】按钮,呼叫工具条可以正常获取cookie,此时呼叫功能会无感加载
# 获取SDK
接入地址
第三方向七鱼请求SDK
接入地址的时候,七鱼会执行客服在七鱼的登录事件,并生成含动态口令的SDK
接入地址返回给第三方
接口调用及数据校验规则参考上面营销接口调用及校验
curl请求样例如下:
curl -X POST \
'http://qiyukf.com/openapi/ipcc/login?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{"staffName": "admin"}'
# 参数说明
具体请求参数说明如下:
参数 | 是否必须 | 数据类型 | 参数说明 |
---|---|---|---|
staffName | 是 | String | 使用工具条的客服在七鱼这边对应的客服名(此处对应的参数值为客服账号) |
接口返回数据为JSON格式,最外层参数如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示设置成功。 |
result | code为200时,返回值有效。 |
message | 请求错误时,填错误提示信息 |
如果code
等于200表示客服登录成功,result
内容为json数据,返回样例如下:
{
"code": 200,
"message": "",
"result": {
"sdk_url": "https://xxx.qiyukf.com/toolbar/script/get?token=cb1ec3c43089493eb4039945685ebf51",
"corp_code": "xxx",
"token": "cb1ec3c43089493eb4039945685ebf51"
}
}
result内的参数说明如下:
参数 | 数据类型 | 参数说明 |
---|---|---|
sdk_url | String | 生成的含动态登录口令的SDK 接入地址 |
corp_code | String | 登录客服对应的七鱼企业域名 |
token | String | 动态登录口令 |
# 初始化SDK
前端页面通过上面异步接口获得sdk_url
之后,动态加载这个sdk_url
对应的js文件,即可完成工具条的初始化
动态加载js样例
var sdk = document.createElement('script');
sdk.async = !0;
sdk.src = url;
sdk.onload = function(){//sdk加载成功后,注册呼叫工具条事件
qiConnect.on({
onload: function() {//呼叫工具条加载完毕的事件通知。此事件完成后才可调用外呼接口
console.log('呼叫工具条加载完毕!');
},
/**
* 建立新呼叫会话的事件,包括外呼和呼入
* @param {Object} session 呼叫会话的session信息
*
* @param {String} session.address 号码归属地
* @param {String} session.usernumber 客户号码
* @param {Number} session.sessionid 会话id
* @param {String} session.staffnumber 坐席号码
* @param {Number} session.staffid 坐席id
* @param {String} session.staffname 坐席账号
* @param {Number} session.direction 会话方向,1表示呼入,2表示呼出
*/
session: function(session){
console.log('session',session);
}
});
};
document.body.appendChild(sdk);
呼叫工具条加载完成后,会在接入页面添加id为CONTAINER-CC-TOOLBAR
的工具条容器元素,可通过定义该容器的样式,定制呼叫工具条的位置以及叠放层级。
自定义样式示例
<style>
#CONTAINER-CC-TOOLBAR {
top: 100px;
right: 100px;
z-index: 100001;
}
</style>
呼叫工具条SDK
加载完成后,SDK
会在全局对象window
上挂载qiConnect
对象,该对象实现了SDK 接口功能:SDK事件、SDK方法。
# SDK事件
qiConnect
对象提供了一系列事件监听功能,通过qiConnect.on({ [eventType]:[eventHandler] })进行注册。
注意: SDK事件操作需要在sdk脚本加载完成后才能注册监听。
事件 eventType | 说明 |
---|---|
onload | 加载成功 |
initSuccess | 初始化成功 |
session | 会话开始 |
answered | 会话接通 |
byeFailed | 通话挂断失败 |
sessionClose | 会话结束 |
statusOptionsChanged | 状态可选项变更 |
statusChanged | 状态设置成功 |
statusChangeFailed | 状态设置失败 |
overProcess | 完成处理 |
acceptedByKefu | 双向回呼,客服已接起 |
asrContentUpdate | asr识别结果 |
cookieAccessibleChanged | 【Safari浏览器、iOS webview】获取cookie权限发生变化 |
# 加载完成 onload
工具条加载完成后,可进行面板操作或调用SDK方法。
# 使用方式
qiConnect.on({onload: function(){
// other code ……
}});
# 初始化成功 initSuccess
工具条初始化完成后,可以设置状态
# 使用方式
qiConnect.on({initSuccess: function(){
// other code ……
}});
# 会话开始事件 session
呼叫会话的创建事件,包括外呼和呼入。监听该事件可获取当前会话信息。
# 使用方式
qiConnect.on({session: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
sessionid | Number | 会话id |
address | String | 号码归属地 |
usernumber | Number | 客户号码 |
staffnumber | Number | 坐席号码 |
staffid | Number | 坐席id |
staffname | String | 坐席名 |
direction | Number | 会话方向 1 呼入 2 呼出 |
ivrpathname | String | IVR路径名称 格式:节点名称1-节点名称2……-节点名称N |
sessionIdFrom | Number | 转接至该会话的上一通会话id |
# 会话结束事件 sessionClose
呼叫会话的结束事件,包括呼出和呼入。监听该事件可获取当前会话信息。
# 使用方式
qiConnect.on({sessionClose: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
address | Number | 号码归属地 |
usernumber | Number | 客户号码 |
sessionid | Number | 会话id |
staffid | Number | |
staffname | Number | 坐席名 |
throughData | string | call(numbers, throughData)方法透传字段 |
# 会话接通事件 answered
表示会话双发已准备就绪,可以开始通话。当呼叫会话为呼入时,坐席接起电话后触发的事件 或者 当呼叫会话为呼出时,被外呼客户接起后触发的事件。监听该事件可获取当前会话的拨号方式和接起方式。
# 使用方式
qiConnect.on({ answered: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
direction | String | "IN" 呼入通话 "OUT" 外呼通话 |
type | String | "SIP" sip话机 "AUTOANSWER" 自动应答 "CALLPANEL" 面板点击 "" 外呼通话接起类型未知 |
# 通话挂断失败事件 byeFailed
当执行挂断通话的操作失败后触发,如当前处于非通话状态时,调用了bye()方法,故建议在有answered事件相应后调用bye()方法。监听该事件可获取失败原因。
# 使用方式
qiConnect.on({ byeFailed: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
hasError | Boolean | 是否有错误 |
cause | String | 挂断失败的具体原因 |
# 坐席可选状态变更事件 statusOptionsChanged
坐席可选状态变更事件,当软电话、SIP话机、手机在线等服务模式发生变更时,伴随着坐席可用状态的变更,此事件会通知变更信息。
# 使用方式
qiConnect.on({statusOptionsChanged: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
status | Array | 当前状态 |
statusOptions | Array | 可选状态选项 |
# 坐席状态设置成功事件 statusChanged
坐席状态设置成功事件,工具条坐席当前状态发生变更,此事件会通知变更成功的状态。
# 使用方式
qiConnect.on({statusChanged: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
status | Array | 当前设置的状态 |
# data.status枚举如下(管理端设置、电话模式等设置可能会导致某些状态不会出现):
status值 | 含义 | 备注 |
---|---|---|
['0'] | 离线 | |
['1'] | 软电话在线 | |
['2', 小休细分状态] | 小休 | 例如小休-就餐,对应值为['2', '1'] |
['3'] | 通话中 | |
['4'] | 手机在线 | |
['5'] | sip话机在线 | |
['6'] | 挂起 | |
['7'] | 处理中 | |
['8'] | 自动外呼 |
# 小休细分状态枚举如下(管理端设置可能会导致某些状态不会出现):
小休细分状态值 | 含义 |
---|---|
'0' | 无细分状态 |
'1' | 就餐 |
'2' | 会议 |
'3' | 培训 |
'4' | 休息 |
'5' | 洗手间 |
'6' | 其他 |
# 坐席状态设置失败事件 statusChangeFailed
坐席状态设置失败事件,此事件会通知变更失败的状态以及失败原因。
# 使用方式
qiConnect.on({statusChangeFailed: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
status | Array | 设置的状态 |
errorMsg | string | 失败信息 |
# 完成处理事件 overProcess
# 使用方式
qiConnect.on({overProcess: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
address | string | 号码归属地 |
sessionid | number | 会话id |
staffid | number | 坐席id |
staffname | string | 坐席账号 |
usernumber | string | 客户号码 |
# 双向回呼,客服已接起 acceptedByKefu
# 使用方式
qiConnect.on({acceptedByKefu: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
sessionid | number | 会话id |
# asr识别结果事件 asrContentUpdate
# 使用方式
qiConnect.on({asrContentUpdate: function(data){
// other code ……
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
content | string | 音频内容 |
createTime | number | 消息生成时间 |
userType | 0 | 1 | 音频来源方类型:0-坐席 1-访客 |
userId | string | 坐席或访客id |
userName | string | 坐席或访客名称 |
# 获取cookie权限发生变化【只对Safari浏览器、iOS Webview生效】 cookieAccessibleChanged
# 使用方式
qiConnect.on({cookieAccessibleChanged: function(data){
if (data.result) {
console.log('此时可以获取cookie');
} else {
console.log('没有获取cookie权限');
// 此时工具条会展示授权按钮
// 如果已经隐藏了工具条,请务必暂时将工具条置为可见状态,才能点击按钮授权
}
}});
# data字段
名称 | 类型 | 含义 |
---|---|---|
result | boolean | 是否有获取cookie权限 |
# SDK方法
qiConnect
对象提供了一系列方法。 需要在qiConnect的onload事件完成(呼叫功能加载完成)之后才能执行。使用格式 qiConnect.fn(), fn如下:
注意: SDK操作需要在qiConnect的onload事件完成(呼叫功能加载完成)之后才能执行。
方法 Method | 说明 |
---|---|
call() | 外呼 |
bye() | 挂断当前通话 |
logoff() | 账号登出(同步) |
logoffAsync() | 账号登出(异步) |
clean() | 销毁工具条 |
setStatus() | 设置坐席状态 |
setMode() | 设置呼叫服务模式 |
keepPanelUnfold() | 面板保持展开 |
getCaptcha() | 获取手机验证码 |
bindPhone() | 绑定手机号 |
exportLocaleLogs() | 导出本地日志 |
# 外呼拨号 qiConnect.call(numbers, throughData)
该接口实现了一键外呼的功能,传入需要外呼的号码直接调用即可。
# 传参释义
名称 | 类型 | 含义 |
---|---|---|
numbers | string | 外呼号码 |
throughData | any | 透传字段,该字段会通过JSON.stringify()进格式化处理,当通话结束时通过sessionClose事件进行回传 |
使用样例如下
<form onsubmit="return false;" id="yyy">
<p id="call">外呼号码<input type="text" name="mobile" />
<input type="button" value="外呼" name="buttonCall" />
</p>
</form>
document.getElementById('yyy').buttonCall.onclick = function() {
if (!form.mobile.value) return alert('请输入电话号码');
qiConnect.call(form.mobile.value);
}
# 挂断通话 qiConnect.bye()
该接口实现了挂断当前通话的功能,直接调用即可。如当前处于非通话状态时无法执行操作,强行调用会有异常错误相应可通过监听事件处理, 建议在answered事件响应后进行挂断场景处理。
<form onsubmit="return false;" id="yyy">
<p id="call">外呼号码<input type="text" name="mobile" />
<input type="button" value="挂断" name="buttonBye" />
</p>
</form>
var isCalling = false;
qiConnect.on({
answered: function(data){
isCalling = true;
},
sessionClose: function() {
isCalling = false;
},
byeFailed: function(data) {
alert('挂断异常:'+data.cause);
}
});
document.getElementById('yyy').buttonBye.onclick = function() {
if(isCalling){
qiConnect.bye();
}
}
# 退出系统(同步方法) qiConnect.logoff()
该接口实现了退出七鱼系统的功能,直接调用即可。退出后工具条所有功能将不可用,若想再次启用呼叫功能需重新走一遍功能使用的几个步骤。
使用样例如下
<form onsubmit="return false;" id="exampleLogoff">
<input type="button" value="退出七鱼工具条" name="buttonLogoff" />
</form>
document.getElementById('exampleLogoff').buttonLogoff.onclick = function() {
// some code...
var conditionLogoffQiyu = true; //退出七鱼系统的条件
if (conditionLogoffQiyu) {
window.qiConnect.logoff();
}
// some code...
}
# 退出系统(异步方法) qiConnect.logoffAsync()
该接口实现了退出七鱼系统的功能,直接调用即可。退出后工具条所有功能将不可用,若想再次启用呼叫功能需重新走一遍功能使用的几个步骤。
使用样例如下
<form onsubmit="return false;" id="exampleLogoffAsync">
<input type="button" value="退出七鱼工具条" name="buttonLogoffAsync" />
</form>
document.getElementById('exampleLogoffAsync').buttonLogoffAsync.onclick = function() {
// some code...
var conditionLogoffQiyu = true; //退出七鱼系统的条件
if (conditionLogoffQiyu) {
// 使用Promise
window.qiConnect.logoffAsync().then(() => {
console.log('登出成功')
}).catch(({ message }) => {
console.error(message)
});
// 使用回调
window.qiConnect.logoffAsync({}, ({ status, message }) => {
if (status) {
console.log('登出成功')
} else {
console.error(message)
}
})
}
// some code...
}
# 销毁工具条 qiConnect.clean()
销毁工具条,为重新加载做准备:
- 销毁注册的事件
- 销毁界面
- 还原内部状态
- 清除window.qiConnect对象 一般在logoffAsync api之后调用
# 设置坐席状态 qiConnect.setStatus(status)
该接口实现了重置坐席服务状态的功能,需传入当前服务模式可用的坐席状态。
@param status {Array} 初始化成功后状态默认为 qiConnect.status
, 可设置状态来自 qiConnect.statusOptions
, 当服务模式(软电话/SIP话机/手机在线)发生改变时, 可选坐席状态也将发生对应更新,可通过事件 statusOptionsChanged
获取更新的状态信息
qiConnect.statusOptions {Array} 可状态列表,格式 [{ label , value, children} ] 示例如下:
// qiConnect.statusOptions
[
{ "label": "离线", "value": "0" },
{ "label": "小休", "value": "1",
"children": [
{ "label": "会议", value: "0" }
]
},
...
]
使用样例如下:
<form onsubmit="return false;" id="yyy">
<label> 请选择状态:
<select name="chooseStatus">
// qiConnect.statusOptions 当前可选状态
<option value="statusOption.value">statusOption.label</option>
</select>
</label>
</form>
const selectElement = document.querySelector('[name="chooseStatus"');
selectElement.addEventListener('change', (event) => {
const status = event.target.value;
// 可选状态若存在二级状态 参数格式示例 [status, subStatus]
qiConnect.setStatus([status]);
});
# 设置呼叫服务模式 qiConnect.setMode(options, callback)
该接口实现了设置呼叫服务模式的功能,类型为({ mode: 0 | 1 | 2 | 3 | 4 }, ({ status: boolean; message: string; statusOptions: number[]; }) => void) => Promise<{ status: boolean; message: string; statusOptions: number[]; }>;
大部分场景下可以通过回调函数获取设置结果,包含是否设置成功、提示信息、新模式下可选坐席状态等数据;
如果浏览器支持Promise,可以不传回调函数,setMode方法会返回promise,在then和catch中获取以上信息
# 传参释义
名称 | 类型 | 含义 |
---|---|---|
options | { mode: 0 | 1 | 2 | 3 | 4 } | 必填;0-软电话 1-手机在线 2-sip话机 3-双向回呼 4-AXB |
callback | ({ status: boolean; message: string; statusOptions: number[]; }) => void | 选填;status-是否设置成功;message-提示信息;statusOptions-在新模式下可选坐席状态,qiConnect.setStatus会用到 |
使用样例如下:
// 在回调函数中进一步处理流程
// 切换为软电话模式
qiConnect.setMode({ mode: 0 }, ({ status, message, code }) => {
if (status) {
// 呼叫服务模式设置成功
console.info('服务模式设置成功');
} else {
// 呼叫服务模式设置失败
console.error('服务模式设置失败', message);
// 如果code为18051,表示没有设置转接的手机号码,此时需要获取验证码
if (code === 18051) {
// 输入手机号
const mobile = prompt('请输入手机号');
// 获取手机验证码
qiConnect.getCaptcha({ mobile })
.then(() => {
console.info('获取手机验证码成功');
}).then(() => {
// 输入验证码
const captcha = prompt('请输入手机验证码');
return qiConnect.bindPhone({ mobile, captcha })
}).then(() => {
console.info('绑定手机号成功');
}).catch(({ message }) => {
// 获取手机验证码/绑定手机号失败
console.error(message);
});
}
}
});
// 在promise中进一步处理流程
// 切换为sip话机模式
qiConnect.setMode({ mode: 2 }).then(() => {
// 呼叫服务模式设置成功
console.info('服务模式设置成功');
}).catch(({ message, code }) => {
// 呼叫服务模式设置失败
console.error('服务模式设置失败', message);
// 如果code为18051,表示没有设置转接的手机号码,此时需要获取验证码
if (code === 18051) {
// 输入手机号
const mobile = prompt('请输入手机号');
// 获取手机验证码
qiConnect.getCaptcha({ mobile })
.then(() => {
console.info('获取手机验证码成功');
}).then(() => {
// 输入验证码
const captcha = prompt('请输入手机验证码');
return qiConnect.bindPhone({ mobile, captcha })
}).then(() => {
console.info('绑定手机号成功');
}).catch(({ message }) => {
// 获取手机验证码/绑定手机号失败
console.error(message);
});
}
});
# 设置面板保持展开状态 qiConnect.keepPanelUnfold(flag)
该接口实现了面板保持展开状态的功能。面板默认不展开,通话接通时若面板为展开状态则会自动收起,如需面板一直保持展开状态可使用该功能,设置成功后,点击工具条依然可以手动操作展开和收起动作,或根据需求取消该功能。
@param flag {boolean} 默认为 false
示例场景-初始化成功后一直保持展开,使用样例如下:
qiConnect.on({
onload: () => {//呼叫工具条加载完毕的事件通知
console.log('demo info: 呼叫工具条加载完毕!');
qiConnect.keepPanelUnfold(true);
}
});
# 获取手机验证码 qiConnect.getCaptcha(options, callback)
使用手机在线或双向回呼模式之前,要绑定客服手机号,为了确保手机号为客服所有,要先获取手机验证码,校验通过后再绑定手机号
# 传参释义
名称 | 类型 | 含义 |
---|---|---|
options | { mobile: string } | 必填;options.mobile-手机号 |
callback | ({ status: boolean; message: string; }) => void | 选填;status-是否获取成功;message-提示信息 |
示例场景-切换到手机在线或双向回呼模式之前,使用样例如下:
// 在回调函数中进一步处理流程
qiConnect.getCaptcha({ mobile: '1xxxxxxxxxx' }, ({ status, message }) => {
if (status) {
console.info('获取手机验证码成功');
} else {
console.error('获取手机验证码失败', message);
}
});
// 在promise中进一步处理流程
qiConnect.getCaptcha({ mobile: '1xxxxxxxxxx' }).then(() => {
console.info('获取手机验证码成功');
}).catch(({ message }) => {
console.error('获取手机验证码失败', message);
});
# 绑定手机号 qiConnect.bindPhone(options, callback)
获取到手机验证码后,绑定客服手机号。切换到手机在线/双向回呼模式都会将通话接通至该手机号
# 传参释义
名称 | 类型 | 含义 |
---|---|---|
options | { mobile: string; captcha: string } | 必填;options.mobile-手机号;options.captcha-验证码 |
callback | ({ status: boolean; message: string; }) => void | 选填;status-是否绑定成功;message-提示信息 |
示例场景-切换到手机在线或双向回呼模式之前,获取手机验证码之后,使用样例如下:
// 输入手机号
const mobile = prompt('请输入手机号');
// 获取手机验证码
qiConnect.getCaptcha({ mobile })
.then(() => {
console.info('获取手机验证码成功');
}).then(() => {
// 输入验证码
const captcha = prompt('请输入手机验证码');
return qiConnect.bindPhone({ mobile, captcha })
}).then(() => {
console.info('绑定手机号成功');
}).catch(({ message }) => {
// 获取手机验证码/绑定手机号失败
console.error(message);
});
# 绑定手机号 qiConnect.exportLocaleLogs(options)
导出储存在本地的呼叫业务日志,会触发浏览器下载txt日志文件,可以转发给七鱼对接同学进行进一步问题排查
# 传参释义
名称 | 类型 | 含义 |
---|---|---|
options | { range?: [number, number] } | 选填;options.range-导出日志的起止时间的毫秒数,如果省略该字段,会导出所有日志 |
示例场景-出现呼叫问题时:
// 1. 确认出现问题的大致起止时间
// 假设问题开始时间为2023-12-12 13:10
const startTime = new Date(2023, 11, 12, 13, 10, 0, 0)
// 假设问题结束时间为2023-12-12 13:30
const endTime = new Date(2023, 11, 12, 13, 30, 0, 0)
// 2. 为了导出日志上下文,前后各预留5分钟
const buffer = 5 * 60 * 1000;
const range = [startTime.getTime() - buffer, startTime.getTime() + buffer];
// 3. 导出日志
qiConnect.exportLocaleLogs({ range });
// 4. 把日志文件转发给七鱼对接同学
# 外呼机器人
# 枚举类型说明
# 任务状态枚举
value | desc |
---|---|
"NOT_STARTED" | 未开始 |
"IN_PROCESS" | 进行中 |
"COMPLETED" | 已完成 |
"RUNNABLE" | 可运行 |
"USER_PAUSE" | 用户暂停 |
"SYSTEM_SUSPENDED" | 系统暂停 |
"TERMINATE" | 已终止 |
"IN_QUEUE" | 排队中 |
"SYSTEM_HANG_UP" | 系统挂起 |
"WAITING_FOR_REDIAL" | 等待重呼 |
"ACCOUNT_DISABLE" | 账户禁用 |
"MAINTAIN" | 系统维护 |
"EXPIRED" | 任务超时 |
# 通话结果枚举
value | desc |
---|---|
"ANSWERED" | 已接听 |
"NO_ANSWER" | 无应答 |
"BUSY" | 忙线中 |
"POWER_OFF" | 关机 |
"OUT_OF_SERVICE" | 停机 |
"REFUSED" | 拒接 |
"VACANT_NUMBER" | 空号 |
"CAN_NOT_CONNECT" | 无法接通 |
"FROM_PHONE_ERROR" | 主叫欠费 |
"SYSTEM_ERROR" | 外呼失败 |
"CALL_LOSS" | 多并发呼损 |
"TRANSFER_ARTIFICIAL" | 转人工呼损 |
"EXTENSION_NUMBER" | 分机号错误 |
# 外呼机器人事件对接
- 外呼机器人使用过程中,七鱼系统通过该接口向第三方系统推送相关数据信息。包括
通话记录回调
:每次机器人通话结束后,推送相关通话记录信息;任务状态变更通知
:外呼任务状态发生变更时自动推送通知;过滤客户回调
:外呼每过滤一个客户会自动调用回调程序向用户配置的回调地址发送本次过滤客户的信息。通过参数dataType
进行区分。
参数dataType
类型说明:
参数值 | 参数说明 |
---|---|
"ROBOT_CALL_RECORD" | 通话记录回调 |
"ROBOT_CALL_JOB" | 任务状态变更通知 |
"FILER_TASK" | 外呼拦截过滤客户回调 |
"ROBOT_CALL_RINGING" | 用户振铃时回调 |
# 调用说明
请您在对接接口前,务必配置好回调地址,否则回调将无法成功。对接URL配置在七鱼系统中:系统管理》扩展与集成》信息对接》外呼机器人对接接口URL;
务必确认您的回调接口可用且性能正常,平均RT200ms左右。若出现大量回调异常或超时,系统会自动屏蔽掉该URL;
七鱼服务器向第三方接口请求信息时,采用密钥安全认证机制,保证第三方系统的信息安全。接口鉴权参考通用说明-数据校验 (opens new window);
所有回调接口采用POST请求发起,请求Content-Type类型为:application/json;charset=utf-8,返回类型为JSON,同时进行UTF-8编码;
回调极少概率可能出现重复回调,接口中建议做幂等处理。
# 第三方接口需返回的数据体说明
接口返回数据体为JSON格式,最外层参数如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
code | 是 | 返回码,200表示成功。 |
result | 否 | 需返回的数据内容,code为200时,该返回值有效。 |
message | 否 | 业务异常失败时,填错误提示信息。 |
# curl请求样例及具体参数说明如下
1.当一次通话完成后,会自动调用回调程序向用户配置的回调地址发送本次通话详情
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"dataType":"ROBOT_CALL_RECORD",
"data":{
"callRecordId":119,
"robotCallJobId":43,
"dialogFlowId":12,
"calledPhoneNumber":"17751279857",
"resultStatus":"ANSWERED",
"intentLevel":"A",
"customerConcern":["价格"],
"fullAudioUrl":"https://ai-call-platform-daily.oss- cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1/CallJobId43/RHGKTLBG_TaskId_1305203/ai_user.wav",
"customerAudioUrl":"https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1/CallJobId43/RHGKTLBG_TaskId_1305203/user.wav",
"analysisBasis":"判断依据",
"startTime":"2018-10-12 18:46:55",
"endTime":"2018-10-12 18:47:42",
"chatDuration":37,
"chatRound":0,
"attributes":["有钱"],
"properties": {"生日": "2019年10月1日"},
"intentLevelTagId": 0,
"intentLevelCode": 1,
"intentLevelDetailName":"C(待筛选)",
"dynamicProperties": {
"姓名": "kz",
"联系电话": "18099998888",
"结果": "18156755675",
"按键": "4125",
"性别": "女士"
},
"callDetailList":[
{
"text":"喂,您好, (停顿2s),您好,想问下您位于江北纬七路隧道附近,均价17000的高端商业综合体,我可以给您介绍一下吗?",
"type":"ROBOT",
"callDetailId": 1
},
{
"text":"嗯",
"type":"PERSON",
"callDetailId": 2
}
]
}
}'
- 具体请求参数说明如下:
参数 | 类型 | 说明 |
---|---|---|
dataType | String | 回调类型(始终为 ROBOT_CALL_RECORD ) |
callRecordId | Long | 通话记录id |
dialogFlowId | Long | 话术id |
robotCallJobId | Long | 任务id |
calledPhoneNumber | String | 电话号码 |
resultStatus | String | 通话结果,详见枚举类型说明中的通话结果枚举 |
intentLevel | String | 意向等级, 如:(A, "A级(较强)"),(B, "B级(一般)"),(C, "C级(无法判断)"),(D, "D级(很少)"),(E, "E级别(需要再次跟进)"),(F, "F级别(无需再次跟进)") |
customerConcern | List | 用户关注点 |
fullAudioUrl | String | 用户和AI合成的录音 |
customerAudioUrl | String | 用户的录音 |
analysisBasis | String | 意向分析判断依据 |
startTime | String | 拨打开始时间 |
endTime | String | 拨打结束时间 |
chatDuration | Long | 通话时长(单位秒) |
chatRound | Long | 通话轮次 |
attributes | Set | 用户属性 |
properties | Map | 自定义字段 |
intentLevelTagId | Long | 意向标签组id |
intentLevelCode | Integer | 意向标签code(可理解为标签在组里的索引,0是第一个标签,1是第二个) |
intentLevelDetailName | String | 意向标签名称,如"C(待筛选)" |
dynamicProperties | Map | 通话过程中收集的动态变量 |
callDetailList | List | 对话内容 |
text | String | 对话说的具体文字内容 |
type | String | 说话者 (PERSON, "人"), (ROBOT, "机器人") |
callDetailId | Long | 对话详情id |
- 每当任务的状态有变更时,七鱼会自动调用回调程序向用户配置的回调地址发送本次任务状态变更的信息。
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"dataType":"ROBOT_CALL_JOB",
"data":{
"robotCallJobId":43,
"status":"COMPLETED"
}
}'
- 具体请求参数说明如下:
参数 | 类型 | 说明 |
---|---|---|
dataType | String | 回调类型(始终为ROBOT_CALL_JOB) |
robotCallJobId | Long | 任务id |
status | String | 任务状态,详见枚举类型说明中的任务状态枚举 |
- 外呼每过滤一个客户会自动调用回调程序向用户配置的回调地址发送本次过滤客户的信息。
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"dataType": "FILER_TASK",
"data": {
"filteredRobotCallTaskId": 172360,
"robotCallJobId": 7840,
"robotCallJobName":"任务名称"
"dialogFlowId": 7602,
"customerPersonId": 11605713,
"customerPersonName": "测试lx",
"calledPhoneNumber": "18326042077",
"filterType": "INTERCEPT",
"tenantPhoneNumberId": null,
"location":"浙江杭州"
}
}'
- 具体请求参数说明如下:
参数 | 类型 | 说明 |
---|---|---|
dataType | String | 回调类型(始终为FILER_TASK) |
filteredRobotCallTaskId | Long | 过滤记录id |
robotCallJobId | Long | 任务id |
robotCallJobName | String | 任务名称 |
dialogFlowId | Long | 话术id |
customerPersonId | Long | 客户id |
customerPersonName | String | 客户姓名 |
calledPhoneNumber | String | 联系电话 |
filterType | String | 过滤类型 DEAD_ZONE 线路盲区 OPERATOR_RESTRICT 运营商限制 SHARE_WHITE_LIST 共享白名单拦截 JOB_WHITE_LIST 任务白名单拦截 INTERCEPT 外呼拦截 CALL_UPPER_LIMIT 拨打上限 LACK_PROPERTIES 自定义变量缺失 BLACK_LIST 大数据黑名单拦截 |
tenantPhoneNumberId | Long | 线路id |
location | String | 号码归属地 |
- 用户开始振铃时会自动调用回调程序向用户配置的回调地址发送本次通话相关信息。
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"dataType": "ROBOT_CALL_RINGING",
"data": {
"robotCallJobId": 13431, //任务id
"phoneNumberId": 3230, // 线路Id
"calledPhoneNumber": "15040056373", //被叫号码
"startTime": "2022-08-09 17:29:04" //呼叫开始时间
}
}'
# 获取机器人话术列表
通过此接口可以获取所有配置完成的机器人话术。注意:该接口仅能获取发布过的话术(即审核通过或曾今审核通过的,新建外呼任务可选择的话术)。如果想获取全部话术,参考:模糊搜索获取话术列表接口
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/dialogFlow/getDialogFlowList?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求体内容为空(空json对象即"{}")
返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
dialogFlowId | Long | 机器人话术id |
name | String | 机器人话术名称 |
status | String | 话术状态(DRAFT 草稿 PENDING_APPROVAL 等待审核 REJECTED 拒绝 APPROVED 审核通过) |
createTime | String | 创建时间 |
- 返回内容示例:
{
"code": 200,
"message": "获取成功",
"data":[
{
"dialogFlowId": 96,
"name": "金融理财--行业体验demo",
"status": "PENDING_APPROVAL",
"createTime": "2019-05-23 14:10:49"
},
{
"dialogFlowId": 136,
"name": "测试变量",
"status": "PENDING_APPROVAL",
"createTime": "2019-05-23 14:10:49"
}
]
}
# 模糊搜索获取话术列表
通过此接口可以模糊搜索获取所有相关话术列表
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/dialogFlow/fuzzySearch?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
name | String | 是 | 话术名称,模糊搜索 |
pageNum | Integer | 否 | 页码,默认1 |
pageSize | Integer | 否 | 每页条数,默认20 |
- 请求内容示例:
{
"pageNum": 1,
"pageSize": 20,
"name": "test"
}
- 返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
number | Integer | 当前页码 |
pageSize | Integer | 每页数量 |
totalElements | Integer | 总记录数 |
pages | Integer | 总页数 |
dialogFlowId | Long | 机器人话术id |
name | String | 机器人话术名称 |
status | String | 话术状态(DRAFT 草稿 PENDING_APPROVAL 等待审核 REJECTED 拒绝 APPROVED 审核通过) |
createTime | String | 创建时间 |
- 返回内容示例:
{
"code": 200,
"message": "获取成功",
"data":{
"number": 1,
"pageSize": 20,
"totalElements": 1,
"pages": 1,
"content":[
{
"dialogFlowId": 96,
"name": "金融理财--行业体验demo",
"status": "PENDING_APPROVAL",
"createTime": "2019-05-23 14:10:49"
},
{
"dialogFlowId": 136,
"name": "测试变量",
"status": "PENDING_APPROVAL",
"createTime": "2019-05-23 14:10:49"
}
]
}
}
# 获取外呼拦截组配置列表
通过此接口可以获取所有设置的拦截组
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/callIntercept/list?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求体内容为空(空json对象即"{}")
返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
tenantCallInterceptId | Long | 拦截组Id |
name | String | 拦截组名称 |
callOutRestrict | String | 是否开启外呼上限设置(YES 开启 NO 不开启) |
callOutDays | Integer | 外呼次数天数内限制 如7天内 |
callOutCount | Integer | 外呼次数上限限制 如限制3次 |
getThroughRestrict | String | 是否开启接通上限设置(YES 开启 NO 不开启) |
getThroughDays | Integer | 接通次数天数内限制 如7天内 |
getThroughCount | Integer | 接通次数上限限制 如限制3次 |
notExistDays | Integer | 空号天数限制 0为不开启 30天内号码为空号 |
notServiceDays | Integer | 停机天数限制 0为不开启 30天内手机停机 |
defaultStatus | Boolean | 是否默认规则 |
source | String | 拦截组来源 SYSTEM 系统规则 CUSTOM 自定义规则 |
type | String | 生效范围 ALL 全网 TENANT 公司内部 |
createTime | String | 创建时间 |
updateTime | String | 更新时间 |
- 返回内容示例:
{
"code": 200,
"message": "获取成功",
"data":[
{
"createTime":"2021-09-28 17:56:08",
"updateTime":"2021-11-11 14:57:03",
"tenantCallInterceptId":4264,
"callOutRestrict":"YES",
"callOutDays":1,
"callOutCount":3,
"getThroughRestrict":"YES",
"getThroughDays":7,
"getThroughCount":1,
"notExistDays":30,
"notServiceDays":30,
"defaultStatus":false,
"source":"CUSTOM",
"type":"TENANT",
"name":"内部员工演示",
}
]
}
# 获取所有可用外呼线路列表
通过接口可以获取所有可用的外呼线路列表
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/phone/getLineList?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求体内容为空(空json对象即"{}")
返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
tenantPhoneNumberId | Long | 线路id |
phoneLineName | String | 线路名称 |
phoneLineType | String | 号码类型(MOBILE, “手机”),(LANDLINE, “固话”) |
- 返回内容示例:
{
"code": 200,
"message": "获取成功",
"data":[
{
"tenantPhoneNumberId": 96,
"phoneLineName": "金融理财--行业体验demo",
"phoneLineType": "LANDLINE"
},
{
"tenantPhoneNumberId": 136,
"phoneLineName": "测试变量",
"phoneLineType": "LANDLINE"
}
]
}
# 创建外呼机器人外呼任务
通过此接口可以创建外呼机器人新的任务。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/create?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
concurrencyQuota | Integer | 是 | 并发数,默认与任务使用的AI并发数(robotCount)相同 |
jobPhoneNumberIdList | List Long | 是 | 通过获取外呼线路获取 tenantPhoneNumberId;size只能是1,一般同一账户仅有一条线路,遇到多条线路时请联系七鱼服务同学获取支持 |
robotCallJob | RobotCallJob | 是 | 任务详细信息 |
- 任务详细信息参数说明(RobotCallJob)
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
name | String | 是 | 任务名称 |
isPrior | Boolean | 是 | 是否设置为优先 |
dialogFlowId | Long | 是 | 话术id |
tenantCallInterceptId | Long | 否 | 拦截组id,可通过获取外呼拦截组配置列表获取。 |
mode | String | 是 | 任务类型 (AUTO, "自动任务"),(MANUAL, "手动任务") |
startTime | String | 自动任务:必填 手动任务:非必填 | 任务开始日期 "2022-02-08 10:00:00" |
endTime | String | 否 | 结束日期 "2019-10-10 23:59:59" |
dailyStartTime | String | 是 | 当天可拨打开始时间,不可以早于9点 "09:00" |
dailyEndTime | String | 是 | 当天可拨打结束时间,不可以晚于20点 "20:00" |
inactiveTimeList | List TimeSlot | 否 | 不可拨打时间段列表,最大三个不可拨打时段 [{"startTime":"12:00", "endTime":"13:00"}] |
daysOfWeek | List String | 否 | 一周内可拨打的日期 ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"] |
inactiveDateList | List DateSlot | 否 | 不可拨打日期 [{"startDate":"2020-01-01", "endDate":"2020-01-03"}] |
phoneType | String | 是 | 号码类型 (MOBILE, "手机号码"),(LANDLINE, "固话"),(CALL_POLICY_GROUP, "外呼策略组") |
robotCount | Integer | 是 | AI坐席数 |
redialCondition | Set String | 选择自动重拨时必填 | 重拨条件(CALL_LOSS,"呼损客户"),(NO_ANSWER,"无应答"),(BUSY,"忙线中"),(REFUSED,"拒接"),(POWER_OFF,"关机"),(OUT_OF_SERVICE,"停机"),(CAN_NOT_CONNECT,“无法接通“),(FROM_PHONE_ERROR,"主叫欠费"),(SYSTEM_ERROR,"外呼失败") |
redialInterval | Integer | 选择自动重拨时必填 | 重拨间隔(分钟,取值范围6分钟~24 x 60分钟) |
redialTimes | Integer | 选择自动重拨时必填 | 重拨次数(取值范围1~10) |
connectRedialCondition | List Long | 否 | 电话接通后需要重拨的意向分类id,如果电话挂断后分析意向结果在该集合内则自动重拨 |
description | String | 否 | 备注 |
- 时间参数说明(TimeSlot)
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
startTime | String | 是 | 开始时间点 "12:00" |
endTime | String | 是 | 结束时间点 "12:00" |
- 日期参数说明(DateSlot)
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
startDate | String | 是 | 开始日期 "2020-01-01" |
endDate | String | 是 | 结束日期 "2020-01-03" |
- 请求内容示例:
{
"concurrencyQuota": 10,
"jobPhoneNumberIdList": [
2112
],
"robotCallJob": {
"name":"test",
"isPrior":true,
"dialogFlowId":6601,
"mode":"AUTO",
"startTime": "2020-07-22 04:32:00",
"endTime": "2020-07-23 04:32:00",
"dailyEndTime": "21:00",
"dailyStartTime": "09:00",
"phoneType":"LANDLINE",
"robotCount": 10
}
}
- 返回参数说明:
参数 | 说明 |
---|---|
code | 错误码 ,200 表示成功 |
message | 提示信息 |
data | 返回内容 |
- 返回内容示例:
{
"code": 200,
"message":"创建成功",
"data": {"robotCallJobId":139}
}
# 获取指定任务的话术中变量
通过接口可以获取该任务中的话术变量。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/get/jobproperties?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回参数说明:
参数 | 说明 |
---|---|
code | 错误码 ,200 表示成功 |
message | 提示信息 |
data | 返回部分失败内容和提示信息 |
- 返回内容示例:
{
"code": 200,
"message":"获取任务变量成功",
"data": [
"欠款金额",
"最后还款日期"
]
}
# 向外呼任务中导入客户
通过此接口可以向指定的任务导入客户信息,用于拨打电话。(单次导入客户数量不能大于100) 此接口是公网服务,所有客户共用,为保证接口响应速度和吞吐量,并控制服务器压力,将单次导入个数定位100个。数据量大时可以重复调用此接口来实现。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/importcustomer?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
callRecordDup | boolean | 否 | 是否已呼列表去重 默认false |
customerPersons | List CustomerPerson | 是 | 客户资料信息列表 |
- 客户资料信息列表参数说明(CustomerPerson):
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
name | String | 否 | 客户名称 |
gender | String | 否 | 性别: MALE 男 FEMALE 女 |
phoneNumber | String | 是 | 客户手机号 |
properties | Map String, Object | 否 | 话术中变量内容(可通过获取指定任务的话术中变量获取变量名称) |
- 请求内容示例:
{
"robotCallJobId": 28,
"customerPersons": [{
"name": "test",
"phoneNumber": "11111111111",
"gender": "MALE",
"properties": {
"欠款金额": "10.13",
"最后还款日期": "2018年10月3日"
}
}
]
}
- 返回参数说明:
参数 | 说明 |
---|---|
code | 错误码 ,200 表示成功 |
message | 提示信息 |
data | 返回部分失败内容和提示信息 |
- 返回内容示例:
{
"code": 200,
"message":"部分导入失败",
"data": [
{
"phoneNumber": "18283748928",
"errorMsg": "线路限制地内"
}
]
}
# 启动外呼任务
通过此接口可以启动指定的外呼任务
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/start?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回内容示例:
{
"code": 200,
"message": "修改成功",
"data": null
}
# 暂停外呼任务
通过此接口可以暂停指定的外呼任务
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/pause?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回内容示例:
{
"code": 200,
"message": "修改成功",
"data": null
}
# 删除外呼任务
通过此接口可以删除指定的外呼任务
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/delete?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回内容示例:
{
"code": 200,
"message": "删除成功",
"data": null
}
# 终止外呼任务
通过此接口可以终止指定的外呼任务
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/terminate?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回内容示例:
{
"code": 200,
"message": "修改成功",
"data": null
}
# 获取任务列表
通过此接口可以获取外呼任务列表
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/jobs/get?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
name | String | 否 | 任务名称 |
status | String | 否 | 任务状态,详见枚举类型说明中的任务状态枚举 |
pageNum | Integer | 否 | 页码,默认1 |
pageSize | Integer | 否 | 每页条数,默认20,最大20 |
- 请求内容示例:
{
"pageNum": 1,
"pageSize": 20,
"name": "test"
}
- 返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
number | Integer | 当前页码 |
pageSize | Integer | 每页数量 |
totalElements | Integer | 总记录数 |
pages | Integer | 总页数 |
robotCallJobId | Long | 任务id |
name | String | 任务名称 |
status | String | 任务状态 |
createTime | String | 创建时间 |
createUserName | String | 创建人 |
taskTotal | Integer | 任务总数 |
taskCompleted | Integer | 完成的任务数 |
filteredTask | Integer | 过滤外呼数量 |
- 返回内容示例:
{
"code": 200,
"message": "获取外呼任务列表成功",
"data": {
"number": 1,
"pageSize": 20,
"totalElements": 1,
"pages": 1,
"content": [
{
"robotCallJobId": 1,
"name": "dialog测试",
"status": "NOT_STARTED",
"createTime": "2018-09-26 18:07",
"createUserName": "测试",
"taskCount": {
"taskTotal": 2,
"taskCompleted": 1,
"filteredTask": 2
}
}
]
}
}
# 获取任务详情
通过此接口可以获取指定任务的详细信息。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/get/jobdetail?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务id |
- 请求内容示例:
{
"robotCallJobId": 10
}
- 返回参数说明:
参数 | 说明 |
---|---|
code | 错误码 ,200 表示成功 |
message | 提示信息 |
data | 返回内容 |
参数 | 字段类型 | 参数说明 |
---|---|---|
robotCallJobId | Long | 任务id |
dialogFlowId | Long | 话术id |
name | String | 任务名称 |
mode | String | 任务类型 (AUTO, "自动任务"),(MANUAL, "手动任务") |
phoneType | String | 线路类型 (MOBILE, "手机"),(LANDLINE, "固话"),(UNFIXED_CALL,"无主叫固话"),(CALL_POLICY_GROUP,"外呼策略组") |
robotCount | Integer | 任务占用的坐席数量 |
dailyStartTime | String | 可拨打开始时间 |
dailyEndTime | String | 可拨打结束时间 |
inactiveTimeList | List | 不可拨打时间段列表 |
description | String | 任务注释 |
alertUsers | String | 提示人员 |
earlyWarningAlertUsers | String | 预警提示人员 |
createTime | String | 任务创建时间 |
updateTime | String | 任务修改时间 |
startTime | String | 任务开始时间 |
nextStartTime | String | 下一次任务开始时间 |
status | String | 任务状态,详见枚举类型说明中的任务状态枚举 |
jobPhoneNumberList | List | 任务主叫线路列表 |
policyGroupPhoneNumberList | List | 外呼策略组包含的线路信息 |
transferPhoneNumber | List | 转人工号码 |
dialogFlowName | String | 话术名称 |
redialCondition | List | 设置的自动重拨的状态集,(CALL_LOSS,"呼损客户"),(NO_ANSWER,"无应答"),(BUSY,"忙线中"),(REFUSED,"拒接"),(POWER_OFF,"关机"),(OUT_OF_SERVICE,"停机"),(CAN_NOT_CONNECT,“无法接通“),(FROM_PHONE_ERROR,"主叫欠费"),(SYSTEM_ERROR,"外呼失败") |
redialInterval | Integer | 重拨间隔(分钟) |
redialTimes | Integer | 重拨次数 |
- 返回内容示例:
{
"code": 200,
"message":"获取任务详情成功",
"data": {
"robotCallJob": {
"robotCallJobId": 1,
"tenantId": 1,
"dialogFlowId": 1,
"dialogFlowName":"金融行业体验demo-优化版",
"name": "dialog测试",
"mode": "MANUAL",
"robotCount": 12,
"smsTemplateId": null,
"phoneType": "LANDLINE",
"dailyStartTime": "15:08:31",
"dailyEndTime": "15:08:36",
"inactiveTimeList": [{"startTime":"12:00", "endTime":"13:00"}],
"description": null,
"wechatAlertLevel": [],
"wechatAlertLevelCode":[],
"smsAlertLevel": [],
"smsAlertLevelCode":[],
"wechatConditionAlertLevel":[],
"wechatConditionAlertLevelCode":[],
"alertUsers": [],
"wechatSendMethod": "SENDTOALL",
"status": "TERMINATE",
"startTime": null,
"nextStartTime": "00:00:00",
"createTime": "2018-10-09 15:08:54",
"updateTime": "2018-10-09 15:11:20",
"earlyWarningAlertUsers": [],
"wechatPushConditionList": [
{
"intentLevelCodes": [0],
"durationThreshold": 1,
"userIds": [1878],
"wechatSendMethod": "SENDTOALL",
"transferCustomer": false,
"pushIndex": 0
},
{
"intentLevelCodes": [1],
"durationThreshold": 2,
"userIds": [1878],
"wechatSendMethod": "SENDTOONE",
"transferCustomer": false,
"pushIndex": 0
}
],
"redialCondition":["CALL_LOSS", "FROM_PHONE_ERROR", "POWER_OFF", "OUT_OF_SERVICE", "REFUSED", "CAN_NOT_CONNECT"],
"redialInterval":6,
"redialTimes":1
},
"jobPhoneNumberList": [{
"tenantPhoneNumberId": 675,
"phoneNumber": "13576084683",
"phoneName": "",
"enabledStatus": 1,
"phoneType": "LANDLINE",
"concurrencyQuota": 5
}],
"transferPhoneNumber": [
"1523654789",
"1758426896"
],
"completedTask": 3612,
"taskCallTotal": 166
}
}
# 从已呼客户列表重新添加到呼叫任务
通过接口可以把客户从已呼客户列表中重新添加到呼叫任务。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/job/readdcustomer?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务ID |
customerPersonIds | List Long | 是 | 需要添加的客户id (可通过获取已经完成外呼的客户信息列表获取) |
lastCallRecord | Boolean | 否 | 是否过滤重复通话记录只显示最近的一条 |
searchWords | String | 否 | 通过手机号码或者用户名通话记录ID模糊搜索筛选 |
customerGroupId | Long | 否 | 分组ID |
resultStatuses | List String | 否 | 通话结果,详见枚举类型说明中的通话结果枚举 |
intentLevels | List String | 否 | 意向等级 A(0, "A级(较强)"), B(1, "B级(一般)"), C(2, "C级(无法判断)"), D(3, "D级(很少)"),E(4, "E级别(需要再次跟进)"), F(5, "F级别(无需再次跟进)"); |
followStatus | String | 否 | 跟进状态 CLUE(0, "线索"), AI_INITIAL_VISIT(1, "AI初访"), PEOPLE_INITIAL_VISIT(2, "人工初访"), AI_FOLLOW_UP(3, "AI持续跟进"), PEOPLE_FOLLOW_UP(4, "人工持续跟进"), QUOTE(5, "报价"), DEAL(6, "成交"), LOSS(7, "流失"); |
dialogFlowId | Long | 否 | 话术ID |
earliestCreationTime | String | 否 | 最早创建时间,日期标准格式,请不要包含时间"2018-07-25" |
latestCreationTime | String | 否 | 最晚创建时间,日期标准格式,请不要包含时间"2018-07-25" |
- 请求内容示例:
{
"robotCallJobId": 1,
"customerPersonIds": [1919005, 1919006],
"lastCallRecord": true,
"searchWords": "12323424",
"customerGroupId": 1,
"resultStatuses": ["ANSWERED", "REFUSED"],
"intentLevels": ["A"],
"followStatus": "AI_INITIAL_VISIT",
"dialogFlowId": 2,
"earliestCreationTime" : "2018-07-25" ,
"latestCreationTime" : "2018-07-30"
}
- 返回参数说明:
参数 | 说明 |
---|---|
code | 错误码 ,200 表示成功 |
message | 提示信息 |
- 返回内容示例:
{
"code": 200,
"message":"添加成功"
}
# 获取已经完成外呼的客户信息列表
通过此接口可以获取指定外呼任务中已经完成外呼的客户。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/get/customer?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotCallJobId | Long | 是 | 任务ID |
- 请求内容示例:
{
"robotCallJobId": 1
}
- 返回数据体参数说明:
参数 | 字段类型 | 参数说明 |
---|---|---|
customerPersonId | Long | 被叫客户id |
calledPhoneNumber | String | 被叫客户电话号码 |
- 返回内容示例:
{
"code": 200,
"message": "获取已完成客户信息成功",
"data": [
{"customerPersonId":1513632507, "calledPhoneNumber": "17701080699"},
{"customerPersonId":1513632507, "calledPhoneNumber": "17701080699"}
]
}
# 获取指定单通外呼机器人通话记录
通过此接口可以获取指定单通外呼机器人通话记录信息(每分钟频控20)。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/record/get?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
callRecordId | Long | 否 | 外呼机器人通话记录ID |
sessionId | Long | 否 | 外呼机器人转人工,人工客服通话记录ID |
- 请求内容示例:
{
"callRecordId": 132323,
"sessionId": 132323
}
返回数据体参数说明:(参考外呼机器人事件对接-"ROBOT_CALL_RECORD"-通话记录回调的参数说明)
返回内容示例:
{
"code": 200,
"message": "success",
"data": {
"analysisBasis": "命中节点:跳转结点, 该节点设置了意向等级为:A(意向较强)",
"callRecordId": 885434795,
"calledPhoneNumber": "15058115581",
"chatDuration": 42,
"chatRound": 2,
"corpId": 59001,
"customerAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6185/KSKB_JId_6185_SId_-1_TId_5806183/user.wav?Expires=1601363784&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=xQ0EnC6t5WVAHix3rMUkXFn%2F%2FVo%3D",
"dialogFlowId": 7088,
"endTime": "2020-09-28 15:15:58",
"fullAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6185/KSKB_JId_6185_SId_-1_TId_5806183/ai_user_transfer.wav?Expires=1601363784&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=Q3CR37ia%2FZQgIU7jmCoS%2F4AfajI%3D",
"id": 101069,
"intentLevel": "A",
"resultStatus": "ANSWERED",
"robotCallJobId": 6185,
"sessionId": 15167246,
"startTime": "2020-09-28 15:15:14",
"callDetailList": [{
"callDetailId": 716162,
"text": "喂,您好, (停顿2s),322您好,想问下您位于钱塘江边、奥体中心附近,均价只要20000的现房楼盘,有兴趣了解一下吗?",
"type": "ROBOT"
},
{
"callDetailId": 716163,
"text": "好的",
"type": "PERSON"
}]
}
}
# 获取指定时间段内外呼机器人通话记录
通过此接口可以获取指定时间段内(时间间隔限制30分钟)的外呼机器人通话记录列表(每分钟频控10)。
- 接口请求示例:
POST https://qiyukf.com/openapi/icoutcall/recordList/get?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
- 具体请求参数说明如下:
参数 | 字段类型 | 是否必须 | 参数说明 |
---|---|---|---|
startTime | Long | 是 | 开始时间戳 |
endTime | Long | 是 | 结束时间戳 |
- 请求内容示例:
{
"startTime": 1601277314000,
"endTime": 1601279114000
}
返回数据体参数说明:(参考外呼机器人事件对接-"ROBOT_CALL_RECORD"-通话记录回调的参数说明)
返回内容示例:
{
"code": 200,
"message": "success",
"data": [{
"analysisBasis": "命中节点:跳转结点, 该节点设置了意向等级为:A(意向较强)",
"callRecordId": 885434795,
"calledPhoneNumber": "15058115581",
"chatDuration": 42,
"chatRound": 2,
"corpId": 59001,
"customerAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6185/KSKB_JId_6185_SId_-1_TId_5806183/user.wav?Expires=1601363784&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=xQ0EnC6t5WVAHix3rMUkXFn%2F%2FVo%3D",
"dialogFlowId": 7088,
"endTime": "2020-09-28 15:15:58",
"fullAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6185/KSKB_JId_6185_SId_-1_TId_5806183/ai_user_transfer.wav?Expires=1601363784&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=Q3CR37ia%2FZQgIU7jmCoS%2F4AfajI%3D",
"id": 101069,
"intentLevel": "A",
"resultStatus": "ANSWERED",
"robotCallJobId": 6185,
"sessionId": 15167246,
"startTime": "2020-09-28 15:15:14",
"callDetailList": [{
"callDetailId": 716162,
"text": "喂,您好, (停顿2s),322您好,想问下您位于钱塘江边、奥体中心附近,均价只要20000的现房楼盘,有兴趣了解一下吗?",
"type": "ROBOT"
}, {
"callDetailId": 716163,
"text": "好的",
"type": "PERSON"
}]
},
{
"analysisBasis": "命中节点:跳转结点, 该节点设置了意向等级为:A(意向较强)",
"callRecordId": 885434801,
"calledPhoneNumber": "17610217100",
"chatDuration": 29,
"chatRound": 2,
"corpId": 59001,
"customerAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6186/VFMS_JId_6186_SId_-1_TId_5806111/user.wav?Expires=1601365112&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=y%2BmbJa3jBTI0g3JsICGb5yGdXbs%3D",
"dialogFlowId": 7088,
"endTime": "2020-09-28 15:38:12",
"fullAudioUrl": "https://ai-call-platform-daily.oss-cn-hangzhou.aliyuncs.com/DialogueRecording/TenantId1501/CallJobId6186/VFMS_JId_6186_SId_-1_TId_5806111/ai_user_transfer.wav?Expires=1601365112&OSSAccessKeyId=LTAICuX7MOmHW6Oy&Signature=G%2F7mY%2FhESlhdxlQ1vUhOCc5MfFk%3D",
"id": 101070,
"intentLevel": "A",
"resultStatus": "ANSWERED",
"robotCallJobId": 6186,
"sessionId": 15167250,
"startTime": "2020-09-28 15:37:47",
"callDetailList": [{
"callDetailId": 716184,
"text": "喂,您好, (停顿2s),xiayang您好,想问下您位于钱塘江边、奥体中心附近,均价只要20000的现房楼盘,有兴趣了解一下吗?",
"type": "ROBOT"
}, {
"callDetailId": 716185,
"text": "喂",
"type": "PERSON"
}]
}]
}