# 员工管理
# 客服管理
# 创建客服
POST 请求为:
POST https://qiyukf.com/openapi/kefu/add?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"username": "yourUsername",
"password": "yourPassword",
"role": 0,
"subRoleId": 107,
"realname": "张三",
"nickname": "三哥",
"pinyin": "zhangsan",
"mobile": "13412345678",
"email": "aa@bb.com",
"maxSession":10,
"groupIds":[49,55],
"callEnable":0,
"skillScoreChat": 5,
"skillScoreIpcc": 1
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
username | 是 | 客服账号,仅支持数字、字母、下划线、圆点,首字母必须是字母,不超过20个长度 |
password | 是 | 客服密码,需要使用md5加密算法加密后转小写,长度是32位,不能包含'-'字符 |
role | 是 | 角色种类 0 普通客服,1 管理员,-1 工单客服,-2 呼叫客服 |
subRoleId | 是 | 角色id,目前只能通过浏览器的开发者工具查看获得。请以超级管理员角色登录七鱼后,点击左侧导航树"角色权限管理"菜单, 对应的请求url为 /api/kefu/role/list/get |
realname | 否 | 用户名称,不超过20个长度 |
nickname | 否 | 昵称,不超过20个长度 |
pinyin | 否 | 客服名称拼音 |
mobile | 否 | 联系电话 |
否 | 用户邮件 | |
maxSession | 否 | 客服最大接待数 |
groupIds | 否 | 客服分组id数组,是数组[],不是字符串 |
callEnable | 否 | 是否有电话权限, 0 否 1 有 |
skillScoreChat | 否 | 在线会话技能值(0-10) |
skillScoreIpcc | 否 | 电话技能值(0-10) |
响应示例如下:
{
"code": 200,
"message": "success",
"id": 75
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示客服创建成功 |
id | 客服id |
错误码说明如下:
错误码 | 说明 |
---|---|
14004 | 参数内容不正确 |
14703 | 没有权限 |
14704 | 客服已经被创建过了 |
14705 | 客服名称格式不正确 |
14706 | 用户名称格式不正确 |
14707 | 昵称格式不正确 |
14708 | 电话格式不正确 |
14709 | 邮箱格式不正确 |
14710 | 角色不正确 |
14711 | 创建客服失败 |
147011 | 创建客服失败 |
# 修改客服
POST 请求为:
POST https://qiyukf.com/openapi/kefu/update?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"id":"100",
"password": "yourPassword",
"role": 0,
"subRoleId": 107,
"realname": "张三",
"nickname": "三哥",
"pinyin": "zhangsan",
"mobile": "13412345678",
"email": "aa@bb.com",
"maxSession":10,
"groupIds":[49,55],
"callEnable":0,
"skillScoreChat": 5,
"skillScoreIpcc": 1
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
id | 是 | 客服id |
password | 否 | 客服密码,需要使用md5加密算法加密后转小写,长度是32位,不能包含'-'字符,传空不会更新 |
role | 否 | 角色种类 0 普通客服,1 管理员,-1 工单客服,-2 呼叫客服 |
subRoleId | 否 | 角色id,目前只能通过浏览器的开发者工具查看获得。请以管理员角色登录七鱼后,点击左侧导航树"客服管理"菜单,在打开的页面上点击"角色设置"选项卡, 对应的请求url为 api/kefuSet/list/get |
realname | 否 | 用户名称,不超过20个长度 |
nickname | 否 | 昵称,不超过20个长度 |
pinyin | 否 | 客服名称拼音 |
mobile | 否 | 联系电话 |
否 | 用户邮件 | |
maxSession | 否 | 客服最大接待数 |
groupIds | 否 | 客服分组id数组,是数组[],不是字符串 |
callEnable | 否 | 是否有电话权限, 0 否 1 有 |
skillScoreChat | 否 | 在线会话技能值(0-10) |
skillScoreIpcc | 否 | 电话技能值(0-10) |
响应示例如下:
{
"code": 200,
"message": "success"
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示客服创建成功 |
错误码说明参考创建客服
# 删除客服
该接口不支持对企业超级管理员进行删除。
POST 请求为:
POST https://qiyukf.com/openapi/kefu/delete?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"id":"100"
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
id | 是 | 客服id |
响应示例如下:
{
"code": 200,
"message": "success"
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示客服创建成功 |
# 获取客服列表
POST 请求为:
https://qiyukf.com/openapi/v2/staff/list/new?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"status":0,
"role":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
status | 否 | 客服状态,默认所有状态 |
role | 否 | 客服角色,默认所有角色 |
{
"code":200,
"message":"OK",
"data": [
{
"id":123,
"username": "登录用户名",
"realname": "真实姓名",
"nickname": "昵称",
"role": 0,
"roleId": 123,
"phone": "18888888888",
"email": "some@b.c",
"status": 1,
"createtime": 1498736257082,
"updateTime": 1498736257082,
"maxServiceCount": 1,
"skillScoreChat": 5,
"skillScoreIpcc": 5,
"workNumber": "a123456"
}
]
}
返回对应客服列表,其中参数详细说明如下:
参数 | 参数说明 |
---|---|
id | 客服id |
username | 客服登录账号 |
realname | 用户名称,不超过40个长度 |
nickname | 昵称,不超过40个长度 |
role | 角色种类 0 普通客服,1 管理员,2=超级管理员,-1 工单客服,-2 呼叫客服 |
roleId | 角色ID |
phone | 用户电话 |
用户邮件 | |
status | 客服状态,status取1=正常,2=已删除,3=已停用 |
createtime | 客服创建的时间,1970年到现在的毫秒数 |
updateTime | 客服更新的时间,1970年到现在的毫秒数 |
maxServiceCount | 客服最大接待数 |
skillScoreChat | 在线会话技能值(0-10) |
skillScoreIpcc | 电话技能值(0-10) |
workNumber | 工号 |
# 条件查询客服信息
该接口可用于获取单个客服的相关信息,也可进行多条件查询,根据传入的条件参数进行全匹配检索,返回客服的详细信息字段。
POST 请求为:
POST https://qiyukf.com/openapi/kefu/v2/condition/query?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"id": 238749,
"nickname": "张三",
"email": "test@163.com",
"phone": "18812345678",
"workNumber": "WY001",
"realname": ""
}
请求参数说明如下: 注意:参数中id,nickname,email,phone,workNumber,realname必传其一
参数 | 是否必须 | 参数说明 |
---|---|---|
id | 否 | 客服 ID,可通过页面查询或 获取客服组下员工列表 接口获取 |
nickname | 否 | 客服昵称 |
否 | 客服邮箱 | |
phone | 否 | 客服联系电话(用于企业内部通信,注意和"手机号"的区别) |
workNumber | 否 | 客服工号 |
realname | 否 | 客服姓名 |
响应示例如下:
{
"code":200,
"message":"OK",
"data":
{
"id":123,
"username": "登录用户名",
"realname": "真实姓名",
"nickname": "昵称",
"role": 0,
"phone": "18888888888",
"email": "some@b.c",
"status": 1,
"createtime": 1498736257082,
"maxServiceCount": 1,
"skillScoreChat": 5,
"skillScoreIpcc": 5,
"workNumber": "a123456",
"staffGroupIds":[
567121,
600786
],
"groups":[
{
"id":567121,
"name":"测试",
"parent":0,
"pinyin":"ceshi",
"rank":22
},
{
"id":600786,
"name":"一级分组/二级分组/三级分组",
"parent":600785,
"pinyin":"yijifenzu/erjifenzu/sanjifenzu",
"rank":1
}
]
}
}
参数 | 参数说明 |
---|---|
staffGroupIds | 客服所在分组的组ID |
groups | 客服所在分组的组详细信息(和staffGroupIds相对应) |
groups.id | 客服组ID |
groups.name | 客服组名称(多级分组以"/"进行分隔) |
groups.parent | 上级组ID |
groups.pinyin | 组名称的拼音 |
groups.rank | 客服组排序字段 |
其他参数含义与上面的列表接口相同。
# 查询已登录客服信息接口
在使用本接口前,请选阅读七鱼消息接口的通用加密和鉴权规范,地址为 七鱼消息接口开发文档.
使用该接口,可以获取到本企业当前所有已登录的客服状态,以便管理客服,以及动态调整客服会话分配规则等。由于涉及到统计操作,该接口有频控管理,目前限制为每分钟500次。
POST 请求为:
https://qiyukf.com/openapi/data/overview/staff/list/online?appKey=972e4cec01fd9aa0f55610a7e87d8693&time=1519636898
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"groupIds":[531773]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
groupIds | 否 | 指定需要查询登录客服信息的分组列表,如为空,则查询企业所有的已登录客服。 |
请求响应内容示例如下:
{
"code":200,
"message":"success",
"list":[
{
"staffId":62070,
"userName":"sch",
"role":1,
"status":9,
"groupIds":[292827,531773,292829],
"sessionCount":0,
"maxCount":10
}
]
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 响应码。200表示查询成功。14009表示调用太频繁。其他通用错误码见上述官网开发文档。 |
message | 响应码描述字段。 |
list | 已登录客服信息列表。 |
staffId | 客服ID |
userName | 客服登录用户名。 |
role | 客服角色,0 - 普通客服,1 - 管理员,2 - 超管,-1 - 工单客服,-2 - 呼叫客服。 |
status | 当前客服状态,0 - 离线,1 - 在线可接待, 2 - 挂起, 3 - 小休, 9 - 管理端在线。 |
groupIds | 该客服所在的客服组ID列表。 |
sessionCount | 该客服当前已接待的会话数。 |
maxCount | 该客服最大能同时接待的会话数。 |
# 客服组管理
# 创建客服组
POST 请求为:
POST https://qiyukf.com/openapi/kefuGroup/add?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"name":"group name"
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
name | 是 | 客服组名称,不超过60个字符 |
响应示例如下:
{
"code": 200,
"message": "success",
"id": 160
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示设置成功。 |
id | 客服组ID |
# 修改客服组
POST 请求为:
POST https://qiyukf.com/openapi/kefuGroup/update?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"groupId":"10",
"name":"group name"
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
groupId | 是 | 客服组id |
name | 是 | 客服组名称,不超过60个字符 |
响应示例如下:
{
"code": 200,
"message": "success"
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示设置成功。 |
# 删除客服组
POST 请求为:
POST https://qiyukf.com/openapi/kefuGroup/delete?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"groupId":"10"
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
groupId | 是 | 客服组id |
响应示例如下:
{
"code": 200,
"message": "success"
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示设置成功。 |
# 分配客服到客服组
使用该接口可以分配多个客服到指定分组。
POST 请求为:
POST https://qiyukf.com/openapi/kefuGroup/updateKefus?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"groupId": 154,
"kefuIds": [49,54]
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
groupId | 是 | 客服组ID。 |
kefuIds | 是 | 客服ID数组。 |
响应示例如下:
{
"code": 200,
"message": "success"
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示分配成功。 |
# 获取客服组列表
POST 请求为:
https://qiyukf.com/openapi/v2/staff/group/list/new?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"staff":false,
"emptyGroup":false
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
staff | 否 | 是否包含客服ID列表,默认不包含 |
emptyGroup | 否 | 是否返回包含未被分配客服的客服组,默认不返回 |
{
"code":200,
"message":"OK",
"data": [
{
"id":123,
"name": "客服分组名",
"staffIdList": [111,222,333]
}
]
}
返回对客服分组列表。其中staffIdList为该分组下的客服ID列表。
# 获取客服组下员工列表
POST 请求为:
https://qiyukf.com/openapi/v2/staff/group/members/new?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"groupId":12345,
"role":0
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
groupId | 是 | 客服分组ID |
role | 否 | 角色 |
{
"code":200,
"message": "OK",
"data": [
{
"id":123,
"username": "登录用户名",
"realname": "真实姓名",
"nickname": "昵称",
"role": 0,
"phone": "18888888888",
"email": "some@b.c",
"status": 1,
"createtime": 1498736257082,
"maxServiceCount": 1
}
]
}
返回指定客服分组的成员客服列表。其中role取-1=工单客服,0=普通客服,1=管理员,2=超级管理员。