# 员工管理

# 客服管理

# 创建客服

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	否	联系电话
email	否	用户邮件
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	否	联系电话
email	否	用户邮件
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	用户电话
email	用户邮件
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	否	客服昵称
email	否	客服邮箱
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=超级管理员。

← 客户管理在线系统 →