# 工单系统
工单接口V2版本旨在抽象七鱼客服、客服分组、工单等部分业务操作,为第三方系统和七鱼工单集成提供一定的便利。 工单的操作严格按照七鱼工单系统的可操作行为来定义接口。
# 接口鉴权
接口鉴权参考通用说明-数据校验 (opens new window)
# 接口协议
接口属性描述了接口的方法、地址和Content-Type
,Payload部分描述了接口的协议内容。
# 错误码
参数 | 参数说明 |
---|---|
200 | 成功 |
8802 | 客服没有权限 |
14001 | App Key错误 |
14002 | 请求校验失败 |
14003 | 时间错误 |
14004 | 请求参数错误 |
14500 | 内部错误 |
14100 | 客服不存在 |
14101 | 分类不存在 |
14102 | 客服分组不存在 |
14103 | 附件个数超出限制 |
14104 | 附件大小超出限制 |
14105 | 用户不存在 |
14106 | 工单不存在 |
14107 | 附件大小超出企业总大小限制 |
14108 | 工单重复创建 |
14109 | uniqueId超过长度限制 |
14110 | 工单模板不存在 |
14200 | 不支持的分类类型 |
16001 | 服务不可用 |
附录 [1] 工单状态:1:已提交,5:待申领, 10:处理中,20:已完结, 50:已挂起
# 工单接口对接
- 该接口用于创建工单时,七鱼系统通过该接口向第三方系统获取用户信息,包括访客VIP级别,访客UID,访客CRM信息等,通过参数
eventType
进行区分不同场景下的调用。 - 对接URL配置在七鱼系统中:系统管理》扩展与集成》CRM信息对接》工单对接接口URL
参数eventType
类型说明:
参数值 | 参数说明 |
---|---|
1 | 邮件工单通过邮件收件人地址+发件人地址获取访客CRM信息 |
七鱼服务器向第三方接口请求信息时,采用密钥安全认证机制,保证第三方系统的信息安全。
# 数据校验
接口鉴权参考通用说明-数据校验 (opens new window)
# 调用说明
本接口只支持POST请求;
本接口请求Content-Type类型为:application/json;charset=utf-8;
本接口返回类型为JSON,同时进行UTF-8编码。
# curl请求样例如下
1.邮件工单通过邮件收件人地址+发件人地址,获取访客用户信息,包括访客VIP级别、访客UID、crm信息
curl -X POST \
'http://www.xxx.com/api/ticket/crm/info?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"sender": "some@163.com", //发件人邮件地址
"receiver": "other@163.com" //收件人邮件地址
}'
# 响应样例如下
- 本接口返回的数据中,code返回200代表成功
- 本接口返回的数据中,message可用于code非200,即响应错误时的说明
- result代表返回的数据内容,JSON格式;其中data为String类型,data中字段具体说明参考CRM对接-crm轻量对接-参数说明 (opens new window)
{
"code": 200,
"result": {
"uid": "testUid",
"viplevel": 3,
"data": "[
{ \"key\":\"real_name\", \"value\":\"testname122601\" },
{ \"key\":\"mobile_phone\", \"hidden\":true, \"value\":\"14800000000\" },
{ \"key\":\"email\", \"value\":\"14800000000@163.com\" },
{ \"index\":0, \"key\":\"account\", \"label\":\"账号\", \"value\":\"zhangsan\" , \"href\":\"http://example.domain/user/zhangsan\" },
{ \"index\":1, \"key\":\"sex\", \"label\":\"性别\", \"value\":\"先生\" },
{ \"index\":5, \"key\":\"reg_date\", \"label\":\"注册日期\", \"value\":\"2015-11-16\" },
{ \"index\":6, \"key\":\"last_login\", \"label\":\"上次登录时间\", \"value\":\"2015-12-22 15:38:54\" },
{ \"index\":7, \"key\": \"tags\", \"label\": \"标签\", \"value\": \"ceshi,测试一下\" },
{ \"index\":8, \"key\": \"leaderId\", \"value\": \"1001\" }
] ",
},
"message": "返回说明"
}
# 创建工单
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/create?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"title":"工单标题",
"uid":"someone",
"uniqueId":"123456789ABCDE",
"typeId":12345,
"content":"我有一个问题",
"userName":"游客1",
"userMobile":"18888888888",
"userEmail":"some@163.com",
"toEmail":"other@163.com",
"targetStaffId":12345,
"targetGroupId":12345,
"staffId":12345,
"priority": 5,
"templateId":1234,
"followerIds":["1001","1003"],
"attachments":[
{
"fileName":"附件1.txt",
"type":1,
"payload":"附件BASE64"
}
],
"properties":[
{
"key":"服务器",
"value":"瘦西湖"
},
{
"key":"玩家ID",
"value":"12345"
}
],
"customFields":[
{
"id":12345,
"value":"你好"
},
{
"id":12346,
"value":"恩"
},
{
"id": 66,
"value": "619546,619549,619210" //如果是级联自定义字段入参按这个格式拼接,ID的顺序也是级联的顺序
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
title | 是 | 工单标题,不超过100个字符 |
uid | 否 | 开发者的应用里的用户ID,不超过64个字符(如果没有userMobile则必传) |
typeId | 否 | 分类ID,0表示未分类 |
content | 是 | 工单内容,不超过3000个字符 |
userName | 否 | 用户姓名,不超过128个字符 |
userMobile | 否 | 用户联系方式,不超过128个字符(如果没有uid则必传) |
userEmail | 否 | 用户联系邮箱,不超过255个字符 (当fromType=8的时候则必传) |
toEmail | 否 | 收件人邮箱 |
targetGroupId | 否 | 指定客服分组ID(开启自动流转请勿传此字段) |
staffId | 是 | 托管客服ID (当fromType=8的时候则不是必传) |
priority | 否 | 优先级,2=低;5=一般;8=紧急;10=非常紧急 |
templateId | 否 | 模板ID |
connectionId | 否 | 关联会话ID(七鱼在线或呼叫系统的会话ID) |
followerIds | 否 | 工单关注人 |
attachments | 否 | 附件列表 |
attachments.fileName | 是 | 附件的文件名,不超过128个字符 |
attachments.type | 是 | 附件的类型,1=文件的Base64,目前仅支持此类型 |
attachments.payload | 是 | 对应type的内容 |
customFields | 否 | 自定义字段 |
customFields.id | 是 | 自定义字段的ID,对应获取工单模板字段接口返回的fieldId字段 |
customFields.value | 是 | 自定义字段的值 如果是级联字段,需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取 |
properties | 否 | 附加属性对,json格式,不超过1024个字符 |
fromType | 否 | 工单类型 8=邮件工单,不传则是普通工单 |
- userMobile和userEmail二者必填其一;
- 普通工单targetStaffId和targetGroupId二者必填其一,自动流转类型工单则不必满足;
- 创建工单接口上传附件大小目前限制最多5个附件,总大小不超过50M。
响应
{
"code":200,
"message":12345
}
响应码为200时,message内容为工单ID
# 修改工单
修改工单部分属性。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/modify?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"type": 0,
"customId":12345,
"fieldId":12345,
"value":"值" // 如果是级联字段入参按这个格式拼接,ID的顺序也是级联的顺序"619546,619549"
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID |
type | 是 | 修改类型,0=自定义字段,1=标题,2=优先级,3=分类 |
customId | 是 | type=0时,填写自定义字段ID,否则填0 |
fieldId | 是 | type=0时,填写自定义字段FieldId,否则填0, 对应获取工单模板字段接口返回的fieldId字段, 暂不支持级联类型自定义字段, customId 和 fieldId 同时存在,以fieldId为准 |
value | 是 | 新值 如果是级联字段,需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取 |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
响应码为8803时,actionStatus为1表示已提交,5表示已分配待申领(考虑待分配状态) 未受理,10表示已领取/已受理/处理中,20为已完结,25为已驳回,999为已删除
# 批量修改工单
修改工单部分属性。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/batch/modify?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId": 12345,
"staffId": 123, //传-1时代表访客补充材料
"customFields": [
{
"id": 12345,
"fieldId": 12345,
"value": "你好"
},
{
"id": 12346,
"fieldId": 12345,
"value": "恩"
},
{
"id": 12346,
"fieldId": 12345,
"value": "619546,619549,619275" //如果是级联字段入参按这个格式拼接,ID的顺序也是级联的顺序,访客补充材料不支持级联字段
},
{
"id": 12346,
"fieldId": 12345,
"value": "[{\"fileName\":\"1.jpg\",\"payload\":\"base64code\"}]" //如果是附件字段传附件名称和base64编码,仅访客补充材料支持
},
{
"id": 0,
"fieldId": 0,
"value": "[{\"fileName\":\"2.jpg\",\"payload\":\"base64code\"}]",
"name" : "uploadFile" //固定值,补充工单模板附件时需要传该字段,仅访客补充材料支持
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID,填-1时表示访客补充材料 |
customFields | 是 | 自定义字段更新列表, 最多20个 |
customFields.id | 是 | 自定义字段ID |
customFields.fieldId | 是 | 自定义字段FieldId,对应工单模板字段接口返回的fieldId字段,fieldId和id同时存在 以fieldId为准 |
customFields.value | 是 | 新值 如果是级联字段,需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取 |
customFields.name | 否 | 固定值uploadFile,补充工单模板附件时需要传该字段,仅访客补充材料支持 |
响应
{
"code":200,
"message": {
"custom[id1,field1]": {
"code":200,
"message": true
},
"custom[id2,field2]": {
"code":14106,
"message": "工单不存在"
}
}
}
返回成功或者失败。
# 申领工单
工单在分组内时,可先由组内处理人申领方能继续处理。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/apply?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 客服ID |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
# 转交工单
此接口可将工单转交给其他处理人或者客服分组继续处理。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/transfer?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"comment": "转交他人继续处理",
"targetGroupId":0,
"targetStaffId":1,
"attachments":[
{
"fileName":"附件1",
"type":1,
"payload":"附件BASE64"
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID |
targetGroupId | 否 | 目标客服分组 |
targetStaffId | 否 | 和targetGroupId二选一,目标客服分组 |
comment | 否 | 评论内容 |
attachments | 否 | 附件内容,具体含义参阅创建工单 |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
# 回复工单
此接口用于对工单发表回复或添加附件等处理行为。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/reply?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"comment": "已处理",
"attachments":[
{
"fileName":"附件1",
"type":1,
"payload":"附件BASE64"
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID |
comment | 否 | 评论内容 |
attachments | 否 | 附件内容,具体含义参阅创建工单 |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
# 催单接口
此接口用于对未完结的工单执行催单操作。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/reminder?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"comment": "这是催单",
"attachments":[
{
"fileName":"附件1",
"type":1,
"payload":"附件BASE64"
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 发起催单客服的ID |
comment | 是 | 催单内容 |
attachments | 否 | 催单附件 |
响应
{
"code":200,
"message": 1321
}
返回催单ID。
# 完结工单
此接口用于对已处理完成的工单执行完结操作。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/finish?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"comment": "已完成",
"attachments":[
{
"fileName":"附件1",
"type":1,
"payload":"附件BASE64"
}
]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID |
comment | 否 | 评论内容 |
attachments | 否 | 附件内容,具体含义参阅创建工单 |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
# 重新打开工单
此接口可将工单转交给其他处理人或者客服分组继续处理。
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/reopen?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345,
"staffId":123,
"comment": "转交他人继续处理",
"targetGroup":0,
"targetStaff":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
staffId | 是 | 持有工单的客服ID |
targetGroup | 是 | 目标客服分组 |
targetStaff | 是 | 和targetGroupId二选一,目标客服分组 |
comment | 是 | 评论内容 |
响应
{
"code":200,
"message": true
}
返回成功或者失败。
# 搜索工单
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/search?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":123,
"mobile":"18668686868",
"limit":50,
"offset": 0,
"sortBy":"ct",
"order":"asc",
"start":1498736257082,
"end":1498736257082,
"opStart":1498736257082,
"opEnd":1498736257082,
"withCustomField":false,
"uid":"abc175"
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 否 | 工单ID |
mobile | 否 | 用户手机号 |
limit | 否 | 一次请求获取的工单数上限,最大为50 |
offset | 否 | 偏移量 |
sortBy | 否 | 排序方式,默认为"ct"创建时间 |
order | 否 | 升降序,默认desc,降序 |
start | 否 | 起始毫秒时间戳(若不传该参数,则默认支持时间跨度为30天) |
end | 否 | 截止毫秒时间戳 |
opStart | 否 | 操作时间起始毫秒时间戳 |
opEnd | 否 | 操作时间截止毫秒时间戳(不超过90天) |
withCustomField | 否 | 是否包含自定义字段信息 |
uid | 否 | 访客的foreignid |
其中自定义字段如果是级联类型的,其fieldValue格式如:
{
"path": "1级/1.1级", // 每一级的完整名称
"idpath": [1555974, 1555977], // 每一级对应的ID
"id": 1555977 //级联自定义字段ID
}
ticketId和mobile二选一,时间跨度不得超过90天。
响应
{
"code":200,
"message":{
"total":100,
"tickets":[
{
"id":123,
"staffId":123456,
"templateId":12345,
"userName":"大门",
"userEmail":"a@b.c",
"userMobile":"18668686868",
"typeId":11,
"priority":1,
"groupId":12345,
"title":"退货",
"content":"太好了",
"status":5,
"properties":"{}",
"createTime":1498736257082,
"custom": [
{
"id":111,
"name":"abc",
"value":"def"
}
],
"connectionType": 1,
"connectionId": 123
}
]
}
}
响应码为200时,message包含指定用户当前过滤器下的工单数量以及工单列表。其中,id为工单id,staffId为客服ID,templateId为模板ID,userName为用户名,userEmail为邮箱,userMobile为用户手机号,typeId为分类ID,priority为优先级,groupId为客服分组,title为工单标题,content为工单内容,status为工单状态[1],properties为工单属性,createtime为工单创建时间。该列表按创建时间降序排列,custom为该工单包含的自定义字段,其中id为字段编号,name为字段名,value为字段值,connectionType为关联类型:0=无关联、1=关联会话、2=社媒渠道,connectionId为关联ID。
# 获取工单详情
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/new/detail?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
响应
{
"code": 200,
"data": {
"attachments": [
{
"name": "工单附件.xlsx",
"size": 9847,
"type": 0,
"url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
}
],
"content": "这里记录的是工单的内容",
"createTime": 1631081162000,
"crmForeignId": "",
"crmId": "60d02bd9108bfa001d68c0fc",
"crmUserEmail": "18888888888@163.com",
"crmUserName": "张三1",
"crmUserPhone": "18888888888",
"custom": [
{
"fieldId": 45756,
"id": 2782984,
"name": "自定义字段name1",
"value": "自定义字段1内容"
},
{
"fieldId": 45919,
"id": 2782985,
"name": "自定义字段name2",
"value": "自定义字段2内容"
}
],
"follower": {
192054: "李四",
178669: "超级管理员"
},
"fromType": 3,
"groupId": 1718465,
"holderCorp": 0,
"holderId": 191473,
"id": 12345,
"isCrossCorp": 0,
"priority": 5,
"properties": "",
"questionType": {
"id": 1709053,
"name": "企业name",
"parent": 1708930,
"path": "一级分类/二级分类"
},
"relationCorp": 0,
"relationWorksheet": 0,
"staffId": 178669,
"status": 10,
"templateId": 127237,
"templateName": "模版名称",
"title": "这是工单标题",
"typeId": 1709053,
"userEmail": "",
"userId": 0,
"userMobile": "",
"userName": "",
"sender": "123@abc.com",
"foreword": "456@def.com",
"lastFinishTime": 1631081162000,
"connectionType": 1,
"connectionId": 123
}
}
参数说明如下:
参数 | 参数说明 | 备注 |
---|---|---|
content | 工单内容 | |
templateName | 模版名称 | |
title | 工单标题 | |
targetGroup | 受理组名称 | |
status | 工单状态 | 查看附录[1] |
attachments | 附件 | name为文件名,url为资源地址,size为文件大小,字节数 |
createTime | 工单创建时间 | 时间戳 |
crmForeignId | 客户foreignID | 用户的uid,如果传了,则作为客户资料的唯一标识,否则使用phone作为唯一标识 |
crmId | 客户id | 七鱼系统中的客户id |
crmUserEmail | 客户邮箱地址 | 七鱼系统中的客户邮箱地址 |
crmUserName | 客户用户名 | 七鱼系统中的客户用户名 |
crmUserPhone | 客户手机 | 七鱼系统中的客户手机 |
custom | 自定义字段 | 工单里面的自定义字段值 |
follower | 工单关注人 | |
groupId | 客服组id | 若选择分配到客服组改值不为0 |
holderCorp | 当前受理企业ID | 跨企业工单特有 |
holderId | 当前客服ID | 跨企业工单需要和holderCorp配合使用 |
id | 工单id | |
isCrossCorp | 跨企业标示 | 0:企业内工单;1:跨企业工单 |
priority | 优先级 | 优先级:2=低;5=一般;8=紧急;10=非常紧急 |
properties | 附加属性对 | |
questionType | 工单分类 | |
relationCorp | 跨企业所关联企业ID | 默认为0,只有跨企业工单创建方才会有值 |
relationWorksheet | 跨企业所关联工单ID | 跨企业工单特有 |
staffId | 创建工单的客服id | |
templateId | 模板id | |
typeId | 工单分类id | |
userEmail | 用户邮箱 | |
userId | 用户ID | |
userMobile | 用户手机 | |
userName | 用户姓名 | |
sender | 邮件工单发件人 | |
receiver | 邮件工单接收邮箱(废弃),用foreword字段代替 | |
foreword | 邮件工单接收邮箱 | |
lastFinishTime | 最近一次完结时间 | |
fromType | 来源渠道 | 来源渠道:1=工单系统-坐席创建 2=工单系统-接口创建 3=在线会话-坐席创建 4=呼叫通话-坐席创建 41=呼叫通话访客留言创建 5=在线会话-访客自助填写 51=在线会话-坐席邀请访客填写 6=机器人会话-访客自助填写 61=工单系统-工单插件 7=工单系统-表格导入 8=邮件工单 9=社媒工单-googleplay 10=社媒工单-苹果商店 11=社媒工单-facebook |
connectionType | 关联类型 | 关联类型: 0=无关联, 1=关联会话, 2=社媒渠道 |
connectionId | 关联ID |
# 获取工单日志列表
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/log?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":12345
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
响应
{
"code": 200,
"data": [
{
"action": "更新工单",
"actionType": 123,
"corpName": "操作方企业名称",
"id": 1626751,
"info": [
{
"content": "由 “企业名称1” 更改为 “企业名称2”",
"title": "受理企业",
"titleLang": "受理企业"
},
{
"content": "由 “分组名称1” 更改为 “分组名称2”",
"title": "受理组",
"titleLang": "受理组"
},
{
"content": "由 “张三” 更改为 “李四”",
"title": "受理人",
"titleLang": "受理人"
},
{
"content": "转交备注",
"title": "",
"titleLang": ""
}
],
"operator": "超级管理员",
"operatorCorpId": 89265,
"operatorId": 178669,
"time": 1631082000000
},
{
"action": "新建工单",
"actionLang": "新建工单",
"actionType": 2,
"attachments": [
{
"name": "工单附件1.xlsx",
"size": 9847,
"type": 0,
"url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
}
],
"corpName": "操作方企业名称",
"id": 1627561,
"info": [
{
"content": "这是工单标题",
"title": "工单标题",
"titleLang": "工单标题"
},
{
"content": "这里记录的是工单的内容",
"title": "工单内容",
"titleLang": "工单内容"
},
{
"content": "一级分类/二级分类",
"title": "工单分类",
"titleLang": "工单分类"
},
{
"content": "工单模版名称1",
"title": "模板类型",
"titleLang": "模板类型"
},
{
"content": "受理中",
"title": "工单状态",
"titleLang": "工单状态"
},
{
"content": "一般",
"title": "优先级",
"titleLang": "优先级"
},
{
"content": "企业名称1",
"title": "受理企业",
"titleLang": ""
},
{
"content": "分组名称1",
"title": "受理组",
"titleLang": "受理组"
},
{
"content": "张三",
"title": "受理人",
"titleLang": "受理人"
},
{
"content": "",
"title": "用户姓名",
"titleLang": "用户姓名"
},
{
"content": "",
"title": "邮箱",
"titleLang": "邮箱"
},
{
"content": "",
"title": "手机号码",
"titleLang": "用户手机"
}
],
"operator": "超级管理员",
"operatorCorpId": 89265,
"operatorId": 178669,
"time": 1631081162000
},
{
"action": "回复工单",
"actionLang": "回复工单",
"actionType": 20,
"attachments": [
{
"name": "工单附件1.xlsx",
"size": 9847,
"type": 0,
"url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
}
],
"corpName": "操作方企业名称",
"id": 1627561,
"info": [
{
"content": "回复内容",
"title": "",
"titleLang": ""
}
],
"operator": "超级管理员",
"operatorCorpId": 89265,
"operatorId": 178669,
"time": 1631081162000,
"customerSee": true
}
]
}
部分参数说明如下:
参数 | 参数说明 | 备注 |
---|---|---|
corpName | 操作方企业名称 | 跨企业工单返回操作者所在企业名称 |
operatorCorpId | 操作方企业ID | 跨企业工单返回操作者所在企业ID |
operator | 操作人姓名 | |
operatorId | 操作客服ID | |
actionType | 变更操作类型 | 详细说明见:actionType说明 |
actionType说明:
int UNDEFINED = 0;
int CREATE = 1;//创建
int CREATE_TO_GROUP_WITH_STAFF = 2;//创建工单时同时指定受理人和受理组
int DISPATCH_TO_GROUP = 5;//转交到组
int DISPATCH_TO_GROUP_WITH_STAFF = 6;//转交到组时同时指定受理人
int DISPATCH_TO_STAFF = 10;//转交
int APPLY = 15;//领取
int DEAL_WITH = 20;//回复\编辑\更新\评论等处理操作
int FINISH = 25;//关闭
int INVITE_EVALUATION = 26;//邀请评价
int EVALUATE = 35;//评价
int FLOW_TO_STAFF = 40;//流转到客服(批准)
int FLOW_TO_GROUP = 45;//流转达客服组(批准)
int REJECT = 50;//驳回工单
int REBORN = 55;//重新发起,已驳回工单发起者重新发起
int REOPEN = 60;//重新打开
int REOPEN_TO_GROUP_WITH_STAFF = 61;//reopen时给最后处理的受理组和受理人
int UPDATE_PATH_NODE_TO_STAFF = 65;//自动流转节点改变导致的重新流转(到人)
int UPDATE_PATH_NODE_TO_GROUP = 70;//自动流转节点改变导致的重新流转(到组)
int MODIFY = 100;//修改工单
int MODIFY_REPLY = 101;//修改工单回复
int AUTO_APPLY = 105;//客服自动接单 自动分配给某一客服
int REMINDER = 110;//催单
int RELATION = 115;//关联工单
int RELATION_CANCEL = 116;//取消关联工单
int DISPATCH_TO_CORP_WITH_GROUP = 121;//转交到其他企业受理组
int DISPATCH_TO_CORP_WITH_GROUP_AND_STAFF = 123;//转交到其他企业受理组和受理人
int DISPATCH_TO_CORP_WITH_STAFF = 124;//转交到其他企业受理人
int DISPATCH_FROM_CORP = 125;//从其他企业转入
int DISPATCH_TO_CORP_WITH_GROUP_FOR_CREATE = 127;//创建并转交到其他企业受理组
int DISPATCH_TO_CORP_WITH_GROUP_AND_STAFF_FOR_CREATE = 128;//转交到其他企业受理组和受理人
int DISPATCH_TO_CORP_WITH_STAFF_FOR_CREATE = 129;//转交到其他企业受理人
int DISPATCH_FROM_CORP_FOR_CREATE = 130;//创建并从其他企业转入
int PENDING = 200;//挂起
int CANCEL_PENDING = 210;//取消挂起
# 获取工单过滤器列表
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/filter/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"staffId":12345,
"status":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
staffId | 否 | 客服ID不填列举管理员视角的过滤器列表,否则为某个客服视角的过滤器列表 |
status | 否 | 0=所有,1=已启用的过滤器列表 |
响应
{
"code":200,
"message": [
{
"id":123,
"name":"过滤器名",
"status":1,
"crossType":0
}
]
}
返回对应条件的过滤器列表。status取值1=启用,2=已禁用; crossType取值0=企业内过滤器,1=跨企业过滤器。
# 获取过滤器下的工单数量
用以查询某个过滤器下的工单数量
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/filter/count?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"staffId":12345,
"filterId":123
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
staffId | 是 | 客服ID |
filterId | 是 | 过滤器ID |
响应
{
"code":200,
"message": 89757
}
返回对应过滤器下的工单数量。
# 获取过滤器下的工单
POST 请求为:
https://qiyukf.com/openapi/v2/ticket/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"staffId":12345,
"filterId":123,
"limit":3,
"offset":0,
"sortBy": "ct",
"order":"asc"
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
staffId | 是 | 客服ID |
filterId | 是 | 过滤器ID |
limit | 否 | 一次请求获取的工单数上限,最大为50 |
offset | 否 | 偏移量 |
sortBy | 否 | 排序方式,默认为"ct"创建时间 |
order | 否 | 升降序,默认desc,降序 |
响应
{
"code":200,
"message":{
"total":100,
"tickets":[
{
"id":123,
"staffId":123456,
"templateId":12345,
"userName":"大门",
"userEmail":"a@b.c",
"userMobile":"18668686868",
"typeId":11,
"priority":1,
"groupId":12345,
"title":"退货",
"follower":["1111","1112"],
"content":"太好了",
"status":5,
"properties":"{}",
"createTime":1498736257082,
"connectionType": 1,
"connectionId": 123
}
]
}
}
响应码为200时,message包含指定用户当前过滤器下的工单数量以及工单列表。其中,id为工单id,staffId为客服ID,templateId为模板ID,userName为用户名,userEmail为邮箱,userMobile为用户手机号,typeId为分类ID,priority为优先级,groupId为客服分组,title为工单标题,content为工单内容,status为工单状态[1],properties为工单属性,createtime为工单创建时间,connectionType为关联类型:0=无关联、1=关联会话、2=社媒渠道,connectionId为关联ID。该列表按创建时间降序排列。
# 获取工单关注人
POST 请求为
https://qiyukf.com/openapi/v2/ticket/followers/update?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":1111,
"staffId":27663,
"optype":0,
"followers":["111","2222"]
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 企业id |
staffId | 是 | 操作客服id |
optype | 是 | 操作类型0 关注 1 取消关注 |
followers | 是 | 关注人列表 |
响应内容:
{
"code":200,
"total": 2,
"message": [{"1111": "kefu1", "2222": "kefu2"}]
}
# 获取工单模板
POST 请求为:
https://qiyukf.com//openapi/v2/ticket/template/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"status":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
status | 否 | 模板状态,-1为全部状态 |
{
"code":200,
"message": [
{
"id":12345,
"name":"模板名",
"status":1,
"autoFlow":0,
"createTime":1498736257082
}
]
}
返回指定状态的工单模板列表。status取0=停用,1=启用,2=已删除。autoFlow为是否自动流转,1=是,0=否。
# 获取工单模板字段
POST 请求为:
https://qiyukf.com//openapi/v2/ticket/template/fields?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"templateId":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
templateId | 是 | 工单模板ID |
{
"code":200,
"message": [
{
"id":12345,
"fieldId":123,
"name":"字段名",
"required":1,
"type":1,
"status":1,
"description":"字段描述",
"prefill":"预填值",
"hint":"暗纹",
"customer":0
}
]
}
返回指定模板的字段列表。id为自增字段,暂无用处。fieldId为自定义字段id。required=1为必填,0=非必填。type为0=文本,1=单选,2=多选,3=时间控件,6=级联,7=附件。status为0=正常,1=删除。customer访客填写为0=关,1=开。
# 获取级联字段子字段详细信息
POST 请求为:
https://qiyukf.com/openapi/category/get?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"fieldId":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
fieldId | 是 | 自定义字段ID |
{
"code": 200,
"data": {
"result": [
{
"id": 2115348,
"name": "1AAA",
"children": [
{
"id": 2115350,
"name": "2AAA",
"children": null,
"disabled": false,
"highlight": null,
"ai": 0,
"sort": 4,
"cloud": false
},
{
"id": 2115351,
"name": "2BBB",
"children": [
{
"id": 2114619,
"name": "3AAA",
"children": null,
"disabled": false,
"highlight": null,
"ai": 0,
"sort": 4,
"cloud": false
}
],
"disabled": false,
"highlight": null,
"ai": 0,
"sort": 4,
"cloud": false
}
],
"disabled": false,
"highlight": null,
"ai": 0,
"sort": 4,
"cloud": false
},
{
"id": 2115349,
"name": "1BBB",
"children": null,
"disabled": false,
"highlight": null,
"ai": 0,
"sort": 4,
"cloud": false
}
],
"total": 5
}
}
部分参数说明如下:
参数 | 参数说明 | 备注 |
---|---|---|
result.id | 级联自定义字段的子集id | 用于创建、修改、批量修改接口,自定义字段的value入参 |
result.name | 级联自定义字段子集名字 | |
result.children | 当前字段的子集 | |
total | 级联字段的子集的总数 |
# 获取工单满意度评价状态
POST 请求为:
https://qiyukf.com//openapi/worksheet/satisfaction/getEvaluationStatus?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
{
"code": 200,
"data": {
"evaluationTxt": "抱歉,评价已完成,不可重复评价!",
"evaluationStatus": 2 //状态
}
}
返回指定状态对应关系如下:
- evaluationStatus=0; //不可以评价(受规则限制等)
- evaluationStatus=1;//可以评价
- evaluationStatus=2;//已完成评价
- evaluationStatus=3;//已过期
- evaluationStatus=4;//已失效 (对于工单来说可评价的状态,但是此时评价规则又是关闭的)
# 获取工单满意度评价规则
POST 请求为:
https://qiyukf.com//openapi/worksheet/satisfaction/getRule?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
{
"code": 200,
"data": {
"evaluationWay": 4,
"list": [
{
"model": 2,
"resolvedEnabled": 0,
"resolvedRequired": 0,
"settings": [
{
"commentRequired": false,
"name": "满意",
"tagList": [
"sdsd",
"aaa"
],
"tagRequired": false,
"value": 100
},
{
"commentRequired": false,
"name": "不满意",
"tagList": [
"123131",
"bbb"
],
"tagRequired": true,
"value": 1
}
],
"title": "模式1"
},
{
"model": 3,
"resolvedEnabled": 0,
"resolvedRequired": 0,
"settings": [
{
"commentRequired": false,
"name": "满意",
"tagList": [],
"tagRequired": false,
"value": 100
},
{
"commentRequired": false,
"name": "一般",
"tagList": [],
"tagRequired": false,
"value": 50
},
{
"commentRequired": false,
"name": "不满意",
"tagList": [],
"tagRequired": false,
"value": 1
}
],
"title": "模式2"
},
{
"model": 4,
"resolvedEnabled": 0,
"resolvedRequired": 0,
"settings": [
{
"commentRequired": false,
"name": "非常满意",
"tagList": [
"a"
],
"tagRequired": false,
"value": 100
},
{
"commentRequired": false,
"name": "满意",
"tagList": [
"b"
],
"tagRequired": false,
"value": 75
},
{
"commentRequired": false,
"name": "不满意",
"tagList": [
"aadsada",
"sdsda",
"1123"
],
"tagRequired": true,
"value": 25
},
{
"commentRequired": true,
"name": "非常不满意",
"tagList": [
"sdsdsdsdsds",
"aaa"
],
"tagRequired": true,
"value": 1
}
],
"title": "模式3"
},
{
"model": 5,
"resolvedEnabled": 1,
"resolvedRequired": 1,
"settings": [
{
"commentRequired": false,
"name": "非常满意",
"tagList": [
"非常整洁"
],
"tagRequired": false,
"value": 100
},
{
"commentRequired": false,
"name": "满意",
"tagList": [
"整洁",
"小角落不太干净"
],
"tagRequired": false,
"value": 75
},
{
"commentRequired": true,
"name": "一般",
"tagList": [
"大体过得去",
"表面干净整洁",
"觉得少有遗憾",
"体验一般"
],
"tagRequired": true,
"value": 50
},
{
"commentRequired": true,
"name": "不满意",
"tagList": [
"脏乱差",
"不满意的一次体验"
],
"tagRequired": true,
"value": 25
},
{
"commentRequired": true,
"name": "非常不满意",
"tagList": [
"非常糟糕",
"无处下脚"
],
"tagRequired": true,
"value": 1
}
],
"title": "模式4"
}
],
"messageDuplicate": "抱歉,评价已完成,不可重复评价!",
"messageExpired": "抱歉,评价已过有效期!",
"messageInvite": "请您对我们的工作进行评价!",
"messageReopen": "抱歉,工单被重新开启,评价失效!",
"messageThanks": "感谢您对我们的评价!",
"model": 5,
"resolvedEnabled": 1,
"resolvedRequired": 1
}
}
部分参数说明如下:
参数 | 参数说明 | 备注 |
---|---|---|
result.list | 规则列表 | |
result.model | 表示使用的是哪个模板,对应选用的模板编号 | |
list.model | 评价模板编号 | |
list.resolvedEnabled | 表示是否展示在界面上 | 不需要可以忽略 |
list.resolvedRequired | 是否需要勾选已解决 | 表示是否必填 |
list.model.settings | 评价模板对应的评价规则 | |
list.model.title | 评价模板对应的模板名字 | |
list.model.settings.commentRequired | 是否需要评论 | true:需要; false:不需要; |
list.model.settings.name | 评价名 | |
list.model.settings.tagList | 评价标签 | |
list.model.settings.tagRequired | 标签是否需要 | true:需要; false:不需要; |
list.model.settings.value | 评价对应的分值 |
# 工单满意度评价
POST 请求为:
https://qiyukf.com/openapi/worksheet/satisfaction/clickEvaluation?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":1,
"evaluationValue":"100",
"evaluationModel":"5",
"tagList":"整洁,小角落不太干净",
"content":"评价内容",
"evaluationWay":"评价内容",
"isSolved":"评价内容"
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
evaluationValue | 是 | 评价分值,0为未评价,1为不满意(二级)或非常不满意,100为满意(二级)或非常满意,50为一般(三级或五级),25为不满意(四级或五级)75为满意(四级或五级) |
evaluationModel | 是 | 评价模型,0为未评价,2为二级评价模型,3为三级评价模型,4为四级评价模型,5为五级评价模型 |
tagList | 根据模板规则 | 评价标签 |
content | 根据模板规则 | 评价内容 |
evaluationWay | 是 | 评价方式,从模板中拿 |
isSolved | 根据模板规则 | 是否已解决,根据模板规则,规则如果是必填,则必填。2=未解决;1=已解决;0=未评价已解决或未解决; |
{
"code": 200,
"data": true
}
# 获取工单满意度评价结果
POST 请求为:
https://qiyukf.com/openapi/worksheet/satisfaction/getEvaluationWithRule?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"ticketId":1
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
ticketId | 是 | 工单ID |
{
"code": 200,
"data": {
"evaluation": {
"attachmentsCount": 0,
"crmId": "",
"crossCorpWorksheet": false,
"evaluationContent": "评价内容",
"evaluationModel": 5,
"evaluationStatus": 2,
"evaluationTags": "非常整洁",
"evaluationTxt": "MESSAGE_DUPLICATE",
"evaluationValue": 100,
"needEvaluation": true,
"organizerCorp": false,
"originAuth": false,
"typeId": 0
},
"isResolved": 1
}
}
部分参数说明如下:
参数 | 参数说明 | 备注 |
---|---|---|
evaluationContent | 评价内容 | |
evaluationTags | 评价标签 | |
evaluationModel | 评价模板编号 | |
evaluationStatus | 评价状态 | 参考获取工单满意度评价状态 接口对应状态关系 |
evaluationValue | 评价模板对应的分值 | |
isResolved | 是否解决 | 2=未解决;1=已解决;0=未评价已解决或未解决; |
# 工单推送
# 说明
工单推送: 七鱼向企业(以下称第三方)接口 推送工单变更事件
推送时机: 当某一工单被回复、完结等等操作时进行实时推送
接收地址: 第三方应该提供一个 http 格式的 url 作为事件接收的地址,如: http://xxxx/receive。 请求的Content-Type:application/json;charset=utf-8
为了方便做完整性校验,七鱼请求该 url 时,会在参数中增加 checksum 参数,其具体计算和校验规则 参考 通用说明-数据校验 (opens new window)
接收参数: 七鱼会以【POST】方式推送数据,且所有数据在请求体内,因此你需要看以下关于数据的说明。
注: 当七鱼发现某一工单发生事件变更时会进行实时推送,但是由于数据包在网络中传输等各种原因,因此第三方企业不能以七鱼推送事件的顺序作为工单变更的顺序。应以请求体中的time字段描述的时间为准.
# 请求体说明
以下是推送数据的定义
- 元数据
目前支持的工单事件及定义
object WorksheetEvent {
val UNDEFINED = -1 // 未定义
val CREATE = 0 // 创建工单
val REPLY = 1 // 回复工单
val FINISH = 2 // 完结工单
val TRANSMIT = 3 // 转交工单
val MODIFY = 4 // 修改工单
val APPLY = 5 // 申领(分配)工单
val AUTO_APPLY = 6 // 系统分配工单
val REBORN = 7 // 重新发起
val APPROVE = 8 // 批准工单
val REJECT = 9 // 驳回工单
val REOPEN = 10 // 重新打开工单
val REMINDER = 11 // 催单
val CREATE_CROSS = 12 // 创建跨企业
val TRANSMIT_CROSS = 13 // 转交跨企业
val DELETE = 14 //删除工单
val SLA_PUSH = 15;//SLA推送
val EVALUATE=35 //工单满意度评价结果
val PENDING=40 //工单挂起
val CANCEL_PENDING=41 //工单取消挂起
}
细分的工单事件及定义
object WorksheetSubEvent {
val UNDEFINED = -1 // 未定义
val CREATE = 0 // 创建
val REBORN_TO_STAFF = 10 // 重新发起工单给客服
val REBORN_TO_GROUP = 11 // 重新发起工单给客服组
val APPROVE_FLOW_TO_STAFF = 20 // 批准工单自动流转到客服
val APPROVE_FLOW_TO_GROUP = 21 // 批准工单自动流转到客服组
val APPROVE_UPDATE_PATH_NODE_TO_STAFF = 22 // 自动流转节点变更到客服
val TRANSMIT_DISPATCH_TO_STAFF = 30 // 转交给客服
val TRANSMIT_DISPATCH_TO_GROUP = 31 // 转交给客服组
val TRANSMIT_DISPATCH_TO_GROUP_WITH_STAFF = 32 // 转交时指定了客服组组和客服
val AUTO_APPLY_CREATE = 40 // 创建时
val AUTO_APPLY_DISPATCH_TO_GROUP = 41 // 因为自动分配到组导致的自动分配
val AUTO_APPLY_UPDATE_PATH_NODE_TO_GROUP = 42 // 因为更新模板路径自动分配到组导致的自动分配
val AUTO_APPLY_REOPEN_TO_GROUP = 43 // reopen 到组导致的自动分配
val AUTO_APPLY_CROSS_TO_GROUP = 44 // 跨企业工单重新打开时候,如果此时之前受理人已被删除,则会触发重新分配的逻辑。
val MODIFY_CUSTOM = 50 // 修改自定义字段
val MODIFY_TITLE = 51 // 修改标题
val MODIFY_PRIORITY = 52 // 修改工单优先级
val MODIFY_TYPE = 53 // 修改工单分类
val MODIFY_USER_NAME = 54 // 修改用户信息,姓名
val MODIFY_USER_PHONE = 55 // 修改用户信息,手机号
val MODIFY_USER_EMAIL = 56 // 修改用户信息,邮箱
}
object Status {
val UNDEFINED = 0 // 未定义
val COMMITTED = 1 // 已提交
val WAITING_FOR_BEING_APPLIED = 5; // 已分配待申领,未受理
val APPLIED = 10; // 已领取/已受理/处理中
val FINISHED = 20; // 完结
val REJECTED = 25; // 已驳回
val PENDING = 50; // 已挂起
}
工单中指定的User对象
class UserVO {
var name: String = _ // 姓名
var phone: String = _ // 手机号
var email: String = _ // 邮箱地址
}
客服对象
class StaffVO {
var corpId: Long = _ // 企业id
var id: Long = _ // 客服id
var name: String = _ // 客服名字
}
客服组对象
class GroupVO {
var corpId: Long = _ // 企业id
var id: Long = _ // 组id
var name: String = _ // 组名字
}
企业对象
class CorpVO {
var id: Long = _ // 企业id
var name: String = _ // 企业名字
}
自定义字段对象
class CustomFiledVO {
var key: String = _ // 字段名
var value: String = _ // 字段值
}
其中自定义字段如果是级联类型的,其fieldValue格式如:
{
"path": "1级/1.1级", // 每一级的完整名称
"idpath": [1555974, 1555977], // 每一级对应的ID
"id": 1555977 //级联自定义字段ID
}
工单分类对象
class CategoryVO {
var id: Long = _ // 分类id
var name: String = _ // 分类名字
}
模板对象
class TemplateVO {
var id: Long = _ // 模板id
var name: String = _ // 模板名字
}
- 请求体
创建工单时推送的对象
class WorksheetVO{
val event: Int = WorksheetEvent.CREATE // 事件类型
var sheetId: Long = _ // 工单id
var title: String = _ // 工单标题
var content: String = _ // 工单内容
var attachList: List[String] = _ // 附件地址列表
var creator: StaffVO = _ // 创建的客服
var priority: Int = _ // 优先级
var toStaff: StaffVO = _ // 被分配的客服
var toGroup: GroupVO = _ // 被分配的组
var category: CategoryVO = _ // 工单分类
var template: TemplateVO = _ // 工单模板
var time: Long = _ // 事件发生的时间
var user: UserVO = _ // user对象
var customFiledList: List[CustomFiledVO] = _ // 自定义字段
var crmId: String = _ // 七鱼的客户中心Id
var status: Int = _ // 工单状态
var connectionType: Int = _ // 关联类型 0=无关联、1=关联会话、2=社媒渠道
var connectionId: Long = _ // 关联id
}
跨企业工单 -- 创建工单时推送的对象
class CrossWorksheetVO {
// 事件类型
val event: Int = WorksheetEvent.CREATE_CROSS
// 工单id
var sheetId: Long = _
// 工单标题
var title: String = _
// 工单内容
var content: String = _
// 附件地址列表
var attachList: util.List[String] = _
// 创建的客服
var creator: StaffVO = _
// 工单状态
var status: Int = _
// 优先级
var priority: Int = _
// 被分配的企业
var toCorp: CorpVO = _
// 被分配的客服
var toStaff: StaffVO = _
// 被分配的组
var toGroup: GroupVO = _
// 工单分类
var category: CategoryVO = _
// 工单模板
var template: TemplateVO = _
// 事件发生的时间
var time: Long = _
// user对象
var user: UserVO = _
// 自定义字段
var customFiledList: util.List[CustomFiledVO] = _
// crmId
var crmId: String = _
// foreignId
var foreignId: String = _
// 上一节点所属企业
var preCorp: CorpVO = _
// 上一节点所属客服
var preStaff: StaffVO = _
// 上一节点所属分组
var preGroup: GroupVO = _
}
回复工单事件
class ReplyVO{
val event: Int = WorksheetEvent.REPLY // 事件类型
var sheetId: Long = _ // 工单id
var operator: StaffVO = _ // 事件操作者
var remark: String = _ // 备注
var attachList: List[String] = _ // 附件
var time: Long = _ // 事件发生的时间
var status: Int = _ // 工单状态
var customerSee: Boolean = _ // 是否访客可见
}
修改工单事件
class ModifyVO{
val event: Int = WorksheetEvent.MODIFY
var sheetId: Long = _
var operator: StaffVO = _
var time: Long = _
var fieldId: Long = _ // 自定义字段ID
var pre: java.lang.Object = _ // 修改前的值
var after: java.lang.Object = _ // 修改后的值
var status: Int = _ // 工单状态
var supEvent: Int = _ // WorksheetSubEvent
}
申领(分配)工单事件
class ApplyVO{
val event: Int = WorksheetEvent.APPLY
var sheetId: Long = _
var operator: StaffVO = _
var time: Long = _
var status: Int = _
}
自动分配工单事件
class AutoApplyVO{
val event: Int = WorksheetEvent.AUTO_APPLY
var supEvent: Int = _ // WorksheetSubEvent
var sheetId: Long = _
var time: Long = _
var toStaff: StaffVO = _
var status: Int = _
}
转交工单事件
class TransmitVO{
val event: Int = WorksheetEvent.TRANSMIT
var sheetId: Long = _
var toStaff: StaffVO = _
var toGroup: GroupVO = _
var operator: StaffVO = _
var attachList: List[String] = _
var remark: String = _
var time: Long = _
var status: Int = _
var foreignId: String = _
}
转交工单事件 - 跨企业工单
class CorpTransmitVO {
val event: Int = WorksheetEvent.TRANSMIT_CROSS
var corpId: Long = _
var sheetId: Long = _
var operator: StaffVO = _
var attachList: util.List[String] = _
var remark: String = _
var time: Long = _
//非必然返回,无返回则表示未涉及
var toCorp: CorpVO = _ //下一个节点所属企业
var toStaff: StaffVO = _ //下一个节点所属客服
var toGroup: GroupVO = _ //下一个节点所属分组
//非必然返回,无返回则表示未涉及
var preCorp: CorpVO = _ //上一个节点所属企业
var preStaff: StaffVO = _ //上一个节点所属客服
var preGroup: GroupVO = _ //上一个节点所属分组
//工单状态
var status: Int = _
}
批准工单事件
class ApproveVO{
val event: Int = WorksheetEvent.APPROVE
var supEvent: Int = _ // WorksheetSubEvent
var sheetId: Long = _
var time: Long = _
var operator: StaffVO = _
var toStaff: StaffVO = _
var toGroup: GroupVO = _
var attachList: List[String] = _
var remark: String = _
var status: Int = _
}
驳回工单事件
class RejectVO{
val event: Int = WorksheetEvent.REJECT
var sheetId: Long = _
var time: Long = _
var operator: StaffVO = _
var toStaff: StaffVO = _
var attachList: List[String] = _
var remark: String = _
var status: Int = _
}
已驳回工单发起者重新发起
class RebornVO{
val event: Int = WorksheetEvent.REBORN
var supEvent: Int = _ // WorksheetSubEvent
var sheetId: Long = _
var time: Long = _
var operator: StaffVO = _
var toStaff: StaffVO = _
var toGroup: GroupVO = _
var attachList: List[String] = _
var remark: String = _
var status: Int = _
}
完结工单事件
class FinishVO{
val event: Int = WorksheetEvent.FINISH
var sheetId: Long = _
var operator: StaffVO = _
var remark: String = _
var attachList: List[String] = _
var time: Long = _
var status: Int = _
}
已完结工单重新打开
class ReopenVO{
val event: Int = WorksheetEvent.REOPEN
var sheetId: Long = _
var time: Long = _
var operator: StaffVO = _
var toStaff: StaffVO = _
var toGroup: GroupVO = _
var remark: String = _
var status: Int = _
//跨企业工单重新打开-再分配的企业
var toCorp: CorpVO = _
//跨企业工单重新打开-再分配前的企业、客服组、客服
var preCorp: CorpVO = _
var preStaff: StaffVO = _
var preGroup: GroupVO = _
}
催单事件
class ReminderVO{
val event: Int = WorksheetEvent.REMINDER
var sheetId: Long = _
var operator: StaffVO = _
var remark: String = _
var attachList: util.List[String] = _
var time: Long = _
var status: Int = _
}
删除工单事件
class DeleteVO{
val event: Int = WorksheetEvent.DELETE
var sheetId: Long = _
var operator: StaffVO = _
var remark: String = _
var time: Long = _
}
工单满意度评价结果
class EvaluateVO {
val event: Int = WorksheetEvent.EVALUATE //事件类型
var sheetId:Long = _ //工单ID
var evaluationModel: Int = _ //评价模式
var evaluationValue: Int = _ //评价结果
var evaluationTags:String = _ //评价标签
var evaluationContent:String = _ //评价内容
var isSolved: Int = _ //是否解决
}
class SLAPushVO {
// 事件类型
val event: Int = WorksheetEvent.SLA_PUSH
// 工单id
var sheetId: Long = _
// SLA ID
var slaId: Long = _
// slaName
var slaName: String = _
//工单状态
var status: Int = _
}
// 挂起工单事件
class PendingVO {
val event: Int = WorksheetEvent.PENDING //事件类型
var sheetId: Long = _ //工单ID
var operator: StaffVO = _ // 事件操作者
var remark: String = _ // 备注
var attachList: List[String] = _ // 附件
var time: Long = _ // 事件发生的时间
var status: Int = _ // 工单状态
}
// 取消挂起工单事件
class CancelPendingVO {
val event: Int = WorksheetEvent.CANCEL_PENDING //事件类型
var sheetId: Long = _ //工单ID
var operator: StaffVO = _ // 事件操作者
var remark: String = _ // 备注
var attachList: List[String] = _ // 附件
var time: Long = _ // 事件发生的时间
var status: Int = _ // 工单状态
}
# 工单开放能力
# 说明
- 开放能力是指,在工单系统中将工单的部分能力开放,能让第三方介入到工单的流程中。目前支持触发器和SLA。
# 触发器开放能力
# 触发器-条件接口
- 说明:用于触发器中触发工单范围、触发器条件中的条件选项
- 请求方式:POST
- 请求字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
ticketId | Long | 工单id |
triggerName | String | 触发器名称 |
triggerId | Long | 触发器id |
{
"ticketId":123,
"triggerName":"触发器名称",
"triggerId":123
}
- 响应字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
code | Long | 响应码 200-代表成功;其他-代表失败 |
message | String | 响应信息 |
result | Boolean | 响应结果 true-满足条件;false-不满足条件 |
{
"code":200,
"message":"success",
"result":true
}
# 触发器-第三方通知接口
- 说明:用于触发器中执行操作中的第三方通知
- 请求方式:POST
- 请求字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
ticketId | Long | 工单id |
triggerName | String | 触发器名称 |
triggerId | Long | 触发器id |
{
"ticketId":123,
"triggerName":"触发器名称",
"triggerId":123
}
- 响应字段说明: (触发器对响应结果不关心,只负责触发;如果要返回结果,可以参考如下格式返回)
参数 | 类型 | 参数说明 |
---|---|---|
code | Long | 响应码 200-代表成功;其他-代表失败 |
message | String | 响应信息 |
result | Boolean | 响应结果 true-满足条件;false-不满足条件 |
{
"code":200,
"message":"success",
"result":true
}
# SLA开放能力
# SLA-条件接口
- 说明:用于SLA服务目标中筛选条件中的条件选项
- 请求方式:POST
- 请求字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
ticketId | Long | 工单id |
slaName | String | SLA名称 |
slaId | Long | SLA的id |
{
"ticketId":12313,
"slaName":"sla名称",
"slaId":123
}
- 响应字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
code | Long | 响应码 200-代表成功;其他-代表失败 |
message | String | 响应信息 |
result | Boolean | 响应结果 true-满足条件;false-不满足条件 |
{
"code":200,
"message":"success",
"result":true
}
# SLA-第三方服务目标接口
- 说明:用于SLA服务目标中选择第三方服务目标设置
- 请求方式:POST
- 请求字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
ticketId | Long | 工单id |
slaName | String | SLA名称 |
slaId | Long | SLA的id |
slaNodeType | String | SLA目标节点类型,用于SLA目标节点的区分;比如首次响应,完结等;非必填,若传该值时,代表只返回sla目标节点类型为该值的数据 |
{
"ticketId":123123,
"slaName":"sla名称",
"slaId":123,
"slaNodeType":"create"
}
- 响应字段说明:
参数 | 类型 | 是否必填 | 参数说明 |
---|---|---|---|
code | Long | Y | 响应码 200-代表成功;其他-代表失败 |
message | String | Y | 响应信息 |
result | ObjectArray | Y | 响应结果(对象数据) |
- result字段说明:
参数 | 类型 | 是否必填 | 参数说明 |
---|---|---|---|
name | String | Y | sla目标节点名称 |
type | String | Y | sla目标节点类型 |
time | List | Y | 提醒时间点 |
reminder | Object | Y | 提醒数据 |
- reminder字段说明:
参数 | 类型 | 是否必填 | 参数说明 |
---|---|---|---|
actionSettings | ObjectArray | Y | 提醒渠道 |
target | Object | Y | 提醒对象 |
- actionSettings字段说明:
参数 | 类型 | 是否必填 | 参数说明 |
---|---|---|---|
action | Long | Y | 1-邮件提醒;2-短信提醒;4-站内通知;5-第三方接口通知 |
value | String | N | 第三方接口通知时才有值,比如第三方通知的接口地址 |
- target字段说明:
参数 | 类型 | 是否必填 | 参数说明 | 备注 |
---|---|---|---|---|
target | Boolean | N | 受理人 | 这3个至少得有一个有值 |
creator | Boolean | N | 发起人 | 这3个至少得有一个有值 |
custom | Boolean | N | 自定义坐席 | 这3个至少得有一个有值 |
customTargets | LongArray | N | 自定义坐席的id | 设置为自定义时,customTargets传坐席id |
{
"code":200,
"msg":"success",
"result":[
{
"name":"目标1",
"type":"create",
"time":1690192205210,
"reminder":{
"actionSettings":[
{
"action":5,
"value":"http://abc.com"
},{
"action":1
}
],
"target": {
"target": true,
"creator": true,
"custom": true,
"customTargets": ["6281062"]
}
}
},
{
"name":"目标2",
"type":"apply",
"time":1690192205210,
"reminder":{
"actionSettings":[
{
"action":4
},{
"action":1
}
],
"target": {
"target": false,
"creator": false,
"custom": true,
"customTargets": ["6281062"]
}
}
}
]
}
# SLA-第三方通知接口
- 说明:用于SLA中提醒节点中的第三方通知
- 请求方式:POST
- 请求字段说明:
参数 | 类型 | 参数说明 |
---|---|---|
ticketId | Long | 工单id |
slaName | String | SLA名称 |
slaId | Long | SLA的id |
content | String | 工单内容 |
title | String | 工单标题 |
priority | Long | 工单优先级 2-低;5-一般;8-紧急;10-非常紧急 |
name | String | SLA目标节点名称 |
responseTime | String | 服务目标响应时间;例如n分钟,n小时,n天;只有在系统设置目标里才有这个字段返回;第三方服务目标不会有这个字段 |
{
"ticketId":123,
"slaName":"sla名称",
"slaId":123,
"content":"工单内容",
"title":"工单标题",
"priority":5,
"name":"首次响应",
"responseTime":"2分钟"
}
- 响应字段说明: (触发器对响应结果不关心,只负责触发;如果要返回结果,可以参考如下格式返回)
参数 | 类型 | 参数说明 |
---|---|---|
code | Long | 响应码 200-代表成功;其他-代表失败 |
message | String | 响应信息 |
result | Boolean | 响应结果 true-满足条件;false-不满足条件 |
{
"code":200,
"message":"success",
"result":true
}
# 工单自定义字段同步
# 基本用法
第一步:配置支持同步的字段
登录七鱼客服系统超级管理员账号,在 应用 -> 工单系统 -> 工单字段同步,配置字段同步任务。
第二步:字段同步的使用
编辑设置过的字段,触发字段同步功能。
同步地址: 第三方应该提供一个 http或https 格式的 url 作为事件接收的地址,如: http://xxxx或https://xxxx。 请求的Content-Type:application/json;charset=utf-8
为了方便做完整性校验,七鱼请求该 url 时,会在参数中增加 checksum 参数,其具体计算和校验规则 参考 通用说明-数据校验 (opens new window)
接收参数: 七鱼会以【POST】方式推送数据,且所有数据在请求体内,因此你需要看以下关于 数据的说明。
参数名称 | 类型 | 说明 |
---|---|---|
fieldId | Long | 自定义字段ID |
fieldName | String | 自定义字段名称 |
fieldType | String | 字段值类型(TEXT:文本;DATEBOX:时间选择器;CHECKBOX:多选框;CASCADE:级联选择框) |
fieldValue | String | 当前触发字段值 |
请求示例: 当任务触发字段只有一个时:
{
"worksheet":{
"fieldId":1,//自定义字段ID
"fieldName":"触发字段",//自定义字段名称
"fieldType":"TEXT",//字段值类型:文本内容(包括单选)
"fieldValue":"fieldValue"//自定义字段当前值
}
}
或
{
"worksheet":{
"fieldId":1,
"fieldName":"触发字段",
"fieldType":"DATEBOX",//字段值类型:时间选择器
"fieldValue":"1606287144574"
}
}
或
{
"worksheet":{
"fieldId":1,
"fieldName":"触发字段",
"fieldType":"CHECKBOX",//字段值类型:多选框
"fieldValue":"选项1;选项2"
}
}
或
{
"worksheet":{
"fieldId":1,
"fieldName":"触发字段",
"fieldType":"CASCADE",//字段值类型:级联选择框
"fieldValue":"{\\"id\\":1030847,\\"path\\":\\"1111/222/333\\",\\"idpath\\":[1030845,1030846,1030847]}"
}
}
当任务中配置有多个触发字段时,每当触发字段内容被修改,就会将所有的触发条件进行参数拼接,并进行任务触发。fieldValue可能为空。 请求参数格式如下:
{
"worksheet": [{
"fieldName": "触发字段2",
"fieldType": "TEXT",
"fieldValue": "",
"fieldId": 48104
}, {
"fieldName": "触发字段1",
"fieldType": "TEXT",
"fieldValue": "触发内容1",
"fieldId": 46235
}]
}
返回值示例:
{
"code":200,
"result":[{
"fieldId":2,
"fieldName":"fieldName1",//字段名称
"fieldValue":"fieldValue1"//字段值
},
{
"fieldId":3,
"fieldName":"多选内容",
"fieldValue":"选项1;选项2"
}]
}
响应码为200表示请求成功,fieldId或fieldName至少返回其中一项,优先根据fieldId匹配字段。
# 获取工单分类
POST 请求为:
POST https://qiyukf.com/openapi/category/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"type":2
}
接口参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
type | 是 | 分类类型,2:工单分类(暂不支持其他分类类型) |
响应
{
"code": 200,
"message": [
{
"id": 12345,
"parentId": 0,
"name": "母婴",
"rank": 2
}
]
}
响应码为200时,message即为分类列表。 message为参数说明:
参数 | 参数说明 |
---|---|
id | 分类ID |
parentId | 父类ID,0表示无父分类 |
name | 分类名 |
rank | 同级分类的排序权值 |