七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
在线系统

在线系统事件对接

在线会话事件、消息推送、字段和响应约束。

请求分配客服

接口请求地址

POST [https://qiyukf.com/openapi/event/applyStaff?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/event/applyStaff?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

分配客服的逻辑

  1. 如果指定了客服 ID（staffId），则忽略 staffType 和 groupId 两个参数， 只会分配到该客服，如果这个客服不在线，则返回客服不在线，如果该客服已排满，则返回需要排队。如果当前用户已经有另外一个客服在服务，则会先关闭与前一个客服的会话。
  2. 如果指定了客服分组 ID（groupId), 则忽略 staffType 这个参数，只会分配到该分组内的客服，如果该分组内没有客服在线，则返回客服不在线，如果该分组内客服已排满，则返回需要排队。如果当前用户已经有另外一个分组内的客服在服务，则先回关闭与前一个客服的会话。
  3. 如果指定了客服类型（staffType），如果用户当前已经有客服在服务中，且 staffType 为 0 或者没有传 staffType，则直接返回该会话客服。否则，如果该参数为 0 或者没有传递，则会返回机器人会话，如果该参数为1，且robotShuntSwitch参数为1，则在申请人工客服之前先申请机器人客服，转人工后再申请人工客服，若robotShuntSwitch为0或不传则直接申请人工客服，在所有在线客服中分配一个空闲客服，如果没有客服在线，则返回客服不在线，如果所有客服都已经排满，则会返回需要排队。
  4. 如果指定了robotId，那么当需要生成机器人会话时，会进入到该robotId对应的机器人中。多机器人配置详见 机器人 -> 机器人列表
  5. 如果返回客服不在线，服务将自动进入留言模式，用户发送的消息将会保存在留言中，留言过程中，如果客服上线了，将自动转人工客服。
  6. 如果用户处于机器人服务状态，想要切换为人工服务，将staffType置为1重新调用一遍该接口即可，也可以带上指定的客服或客服分组参数。
  7. 如果用户处于有客服服务状态，想切换为其他客服，带上想要切换的客服或者客服分组，重新调用一遍该接口即可。

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
uid是开发者的应用里的用户 ID。
fromPage否用户发起咨询客服操作的页面 url，比如商品链接，订单页面等。
fromTitle否fromPage 页面的标题。
deviceType否用户设备类型信息。
productId否产品标识，可以是 Android 应用的包名，iOS 应用的 bundleid 等。
staffType否请求分配的客服类型，如果传0，表示机器人，传1表示人工。默认为机器人。
staffId否只请求该 ID 的客服，客服 ID 可在管理后台查看。
groupId否只请求该客服分组 ID 内的客服，分组 ID 可在管理后台查看。
robotShuntSwitch否申请人工客服之前是否先申请机器人开关，0代表关闭，1代表启用。
level否该访客这次会话的vip等级，从0到11
robotId否有多个机器人时，指定接入某一个机器人。

响应参数

参数参数说明
code错误码。200表示分配到客服，14005：没有客服在线，14006：需要排队，14010：没有客服在线，且留言功能已关闭。
message如果分配到客服，此字段是客服的欢迎语，如果没有分配到客服，则是错误提示信息。
count仅返回需要排队时该参数有效，表明排队队列中排在你前面你的人数。如果为0，则表示你排在队列最前面。
sessionId会话 ID，后续对会话评价时有用。仅返回分配到客服时该参数有效。
staffId客服 ID。
staffName客服名字。
staffType客服类型，0 表示机器人，1 表示人工会话。
staffIcon客服头像的 url。(注：主要给平台企业用)
evaluationModel满意度评价模型，在申请到人工客服时有值，后面根据该模型 value 值进行客服评价。
rich_text_greet如果设置富文本作为机器人或者人工的欢迎语，这个字段会带上原始的html格式富文本，原message中保留提取出来的纯文本。

示例

请求示例

{
    "uid": "user1",
    "fromPage": "www.163.com",
    "fromTitle": "Netease",
    "fromIp": "220.220.2.1",
    "deviceType": "Android#xiaomi#5.0",
    "productId": "Android package name",
    "staffType": 1,
    "staffId": 0,
    "groupId": 0,
    "robotShuntSwitch":0,
    "level":0,
    "robotId":22
}

返回示例

{
  "code": 200,
  "staffId": 1234,
  "message": "哈哈",
  "count":0,
  "sessionId": 62927,
  "staffName": "lantian",
  "staffType": 0,
  "staffIcon": "[https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D](https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D)",
  "evaluationModel": {
      "title": "模型一",
      "note": "二级评价模型",
      "type": 2,
      "list": [
          {
             "name": "满意",
             "value": 100
          },
          {
             "name": "不满意",
             "value": 1
          }
      ]
  }
}

接收会话开始通知

当客服主动发起和客户进入时，或者由其他会话转接时，开发者服务器会收到此通知。目前只有人工会话会收到通知，机器人会话开始不会发送通知。此事件通知仅在OpenApi渠道下的会话生效。

开发者服务器收到的POST请求如下

POST [https://QIYU_MSG_URL?eventType=SESSION_START&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://QIYU_MSG_URL?eventType=SESSION_START&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求内容示例

{
  "code": 200,
  "staffId": 1234,
  "message": "哈哈",
  "sessionId": 62927,
  "staffName": "lantian",
  "staffType": 0,
  "staffIcon": "[https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D](https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D)",
  "uid": "user1",
  "evaluationModel": {
        "title": "模型一",
        "note": "二级评价模型",
        "type": 2,
        "list": [
            {
               "name": "满意",
               "value": 100
            },
            {
               "name": "不满意",
               "value": 1
            }
        ]
    },
  "transferFrom": 62917
}

响应参数中各个 key 意义与分配客服的响应参数相同，其中不同的一个参数意义如下：

参数参数说明
transferFrom如果会话是被转接过来的，会有该字段，值为发起转接的那次会话的ID。

接收七鱼消息

当客服（人工或者机器人）回复消息后，七鱼平台会把消息推送给开发者。推送地址是开发者在七鱼管理后台“系统 > 扩展与集成 > 开发者 ID”处填写的消息与事件接收 URL。

接口请求地址

POST https://QIYU_MSG_URL?eventType=MSG&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业 appKey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time)，三个参数拼接后进行 SHA1 哈希计算，转化成小写 16 进制字符串

Body

参数参数说明
timeStamp消息时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
staffId发送该消息的客服 ID
staffName发送该消息的客服名字

示例

请求示例

{
  "uid": "user1",
  "content": "2222",
  "staffId": 143,
  "timeStamp": 1463216914316,
  "staffName": "lantian",
  "msgId": "8ca1c9fb30c40aa6cc390844e2756fac",
  "msgType": "TEXT"
}

接收会话结束通知

会话结束后，开发者服务器会收到此通知。此事件通知仅在OpenApi渠道下的会话生效。

开发者服务器收到的POST请求如下

POST [https://QIYU_MSG_URL?eventType=SESSION_END&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://QIYU_MSG_URL?eventType=SESSION_END&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求内容示例

{
   "code": 200,
  "staffId": 1234,
  "message": "哈哈",
  "sessionId": 62927,
  "staffName": "lantian",
  "staffType": 0,
  "staffIcon": "[https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D](https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D)",
  "uid": "user1",
  "closeReason":0,
  "transferTo":62928
}

响应参数中各个 key 意义与分配客服的响应参数相同，另外两个不同的key值意义如下：

参数参数说明
closeReason会话关闭原因：0-客服关闭；1-访客离开页面失效关闭；2-访客离开超时关闭；3-访客申请其他客服关闭；4-网络差客服掉线关闭；5-客服转接关闭；6-管理员接管关闭；7-访客主动关闭；8-系统关闭，静默超时关闭；9-系统关闭，静默转接关闭；10-访客未说话；11-访客排队超时清队列；12-访客放弃排队；13-客服离线清队列；14-访客未选择分流入口；16-系统关闭会话；17-访客超时未填写询前表单；18-智能场控关闭排队会话；19-拉黑关闭会话；其他-机器人转人工；47-访客申请子企业客服关闭；49-访客申请主企业客服关闭。

接收客服主动邀评通知

为了提高用户参评率，七鱼为客服增加了主动邀请用户评价会话的入口。此事件通知仅在OpenApi渠道下的会话生效。对于使用消息接口的企业，此处相应的增加了一种事件类型通知，通知事件类型为：EVA_INVITATION。 客服主动邀评后，

开发者服务器会收到如下POST请求：

POST [https://QIYU_MSG_URL?eventType=EVA_INVITATION&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://QIYU_MSG_URL?eventType=EVA_INVITATION&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求内容示例

{
  "sessionId": 62927,
  "staffId": 1234,
  "staffName": "lantian",
  "staffType": 0,
  "staffIcon": "[https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D](https://ysf.nosdn.127.net/29C25737ABC2524667D223A90FEF156D)",
  "uid": "user1"
}

响应参数中各个 key 意义与分配客服的响应参数相同。

接收用户进入排队通知

如果用户通过在机器人会话中直接发送rg请求人工客服转到排队，或者直接发送消息，也可能会触发进入人工，导致排队。通过处理这个通知，应用服务器可以更准确的知道用户当前的服务状态。 注意，如果是通过申请客服接口进入排队，不会触发这个通知。此事件通知仅在OpenApi渠道下的会话生效。

触发后，开发者服务器会收到如下POST请求：

POST [https://QIYU_MSG_URL?eventType=USER_JOIN_QUEUE&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://QIYU_MSG_URL?eventType=USER_JOIN_QUEUE&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

开发者收到的请求内容与申请客服返回排队状态时一致：

 {
     "code": 14006,
     "message": "排队欢迎语",
     "count":1,
     "robotInQueue":1
 }

其中，如果有 robotInQueue 这个参数，表示可以在排队时同时与机器人聊天。

接收用户离开排队通知

在用户离开排队，包括超时退出，主动退出时，开发者服务器会收到该通知。此事件通知仅在OpenApi渠道下的会话生效。

开发者服务器收到的POST请求示例如下：

POST [https://QIYU_MSG_URL?eventType=QUEUE_TIMEOUT&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://QIYU_MSG_URL?eventType=QUEUE_TIMEOUT&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求内容示例

{
    "uid":"user1"
}

客服组排队情况查询

该接口提供开放能力，企业可以根据客服组id查询该客服组是否有客服在线和是否需要排队。

请求接口地址

POST [https://qiyukf.com/openapi/chat/queue/group/query?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463216914&checksum=e72be4487b6fc03e0f914fc11e4053d771598d93](https://qiyukf.com/openapi/chat/queue/group/query?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463216914&checksum=e72be4487b6fc03e0f914fc11e4053d771598d93)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
groupId是只请求该客服分组 ID 内的客服，分组 ID 可在管理后台查看。

响应参数

参数数据类型参数说明
codeInteger错误码。200表示查询成功，14004表示客服组参数不正确或者客服组不存在。
messageString错误提示信息，当code错误码不为200时返回错误提示。
staffInfo.idLong客服id。
staffInfo.realnameString客服姓名。
staffInfo.maxServeCountInteger客服最大接待量。
staffInfo.servingCountInteger客服当前接待量。

示例

请求示例

{
    "groupId": 624001
}

返回示例

{
    "code":200,
    "message":"",
    "staffInfo":[
        {
            "id":12712411,
            "realname":"李莉莉",
            "maxServeCount":20,
            "servingCount":10
        },
        {
            "id":12712612,
            "realname":"张磊",
            "maxServeCount":15,
            "servingCount":13
        }
    ]
}

更新用户资料

使用该接口可以更新用户的详细资料，并展示在客服会话界面的右上侧「用户资料」tab页看到。具体的数据格式定义可参见轻量CRM对接参数说明。

接口请求地址

POST [https://qiyukf.com/openapi/event/updateUInfo?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/event/updateUInfo?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
uid是开发者的应用里的用户 ID。
userinfo是用户资料描述，必须是一个 json 数组。

响应参数

参数参数说明
code错误码。200表示设置成功。

示例

请求示例

{
    "uid": "user1",
    "userinfo":
    [
        {"key":"real_name", "value":"土豪"},
        {"key":"mobile_phone", "hidden":true, "value":"13800000000"},
        {"key":"email", "value":"13800000000@163.com"},
        {"index":0, "key":"account", "label":"账号", "value":"zhangsan" , "href":"[http://example.domain/user/zhangsan](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"}
    ]
}

返回示例

{
  "code": 200
}

获取评价设置

该接口由七鱼提供给第三方调用，用于第三方自己实现满意度评价功能并与七鱼系统进行对接的方式。满意度评价选项配置在七鱼管理后台设置，第三方可以通过该接口拉取该配置，并自己实现用户信息评价功能。评价完成之后，第三方调用下面用户评价接口将评价结果同步给七鱼系统。

接口请求地址

POST [https://qiyukf.com/openapi/evaluation/setting/get?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/evaluation/setting/get?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数参数类型参数说明
fromTypeString访客终端类型：iOS,android,WEB,wx[公众号],wx_ma[小程序],wb[微博]

响应参数

参数数据类型参数说明
codeInteger错误码。200表示设置成功。
messageString错误提示信息
dataJson满意度配置信息
data.messageInviteString满意度邀评文案
data.titleString评价模型名称
data.noteString评价模型备注
data.typeInt评价模型类别
data.listList满意度评价选项
data.list.tagListList评价选项对应可选择的标签
data.list.tagRequiredList标签是否必选
data.list.commentRequiredList备注是否必填

示例

请求示例

{
    "fromType": "iOS"
}

返回示例

{
	"list": [{
		"name": "非常不满意",
		"tagList": [],
		"value": 1
	}, {
		"name": "不满意",
		"tagList": [],
		"value": 25
	}, {
		"name": "一般",
		"tagList": [],
		"value": 50
	}, {
		"name": "满意",
		"tagList": [],
		"value": 75
	}, {
		"name": "非常满意",
		"tagList": ["幽默","热情"],
		"value": 100
	}],
	"messageInvite": "感谢您的咨询，请对 ${客服名} 的服务做出评价",
	"note": "五级评价模式",
	"title": "模式三",
	"type": 5
}

评价客服

该接口允许用户对当前评价当前客服服务的满意度，满意度评价模型数据 evaluationModel 在请求分配客服接口中返回。根据 evaluationModel 中的 list 数组显示满意度评价项，name 为评价项名称，value 为对应评价值，用户选择某评价项时，将对应 value 值作为下面接口参数 evaluation 的参数值。

接口请求地址

POST [https://qiyukf.com/openapi/event/evaluate?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/event/evaluate?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
uid是开发者的应用里的用户 ID。
sessionId是待评价的会话 ID。该会话 ID 可由分配客服的接口拿到。
evaluation是评价值来自请求分配客服接口响应参数中 evaluationModel 中的 value 值。
evaluation_resolved否用户上报问题解决状态，可以为空。0-未选择，1-已解决，2-未解决。
remarks否评价备注信息，可以为空
tagList否评价时给客服打的标签信息

响应参数

参数参数说明
code错误码。200表示评价成功。

示例

请求示例

{
    "uid":"user1",
    "sessionId":62927,
    "evaluation":100,
    "evaluation_resolved": 1,
    "remarks":"你的服务非常棒",
    "tagList":["幽默","热情"]
}

返回示例

{
  "code": 200
}

查询排队状态

接口请求地址

POST [https://qiyukf.com/openapi/event/queryQueueStatus?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/event/queryQueueStatus?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
uid是开发者的应用里的用户 ID。

响应参数

参数参数说明
code错误码。200表示查询成功，14007表示用户不存在或者没有申请连接客服。
count排队队列中排在该用户前面的人数。-1表示已经有客服在接待了。

示例

请求示例

{
    "uid":"user1"
}

响应示例

{
  "code": 200,
  "count": -1
}

主动退出排队

如果一个用户已经在排队中，他可以选择主动退出排队，以便继续和机器人会话。通过提示用户自己退出排队，也可以减轻客服的压力。

接起请求地址

POST [https://qiyukf.com/openapi/event/quitQueue?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64](https://qiyukf.com/openapi/event/quitQueue?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64)
Content-Type:application/json;charset=utf-8

请求参数

Query

参数数据类型是否必须参数说明
appKeyString是企业appkey
timeInteger是当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksumString是SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)

Body

参数是否必须参数说明
uid是开发者的应用里的用户 ID。

响应参数

参数参数说明
code错误码。200表示退出成功，14007表示用户不存在或者没有申请连接客服。

示例

请求示例

{
    "uid":"user1"
}

返回示例

{
  "code": 200
}

会话结束推送会话数据

开发者服务器收到的POST请求示例如下：

POST https://QIYU_MSG_URL?eventType=DATA_ONLINE_SESSION_END&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "alarmTimes":1, // 此会话智能监控报警次数
    "category":"xx/xx", // 会话分类信息
    "closeReason":2, // 会话关闭原因，参照[接收会话结束通知]中的closeReason
    "endTime":3, // 会话结束时间
    "evaluationType":4, // 评价模型
    "evaluation":2, // evaluationType:(evaluation)=>  2:(100满意1不满意);  3(100满意50一般1不满意); 5(100非常满意75满意50一般25不满意1非常不满意) 否则未评价
    "evaluationRemark":"xx", // 评价内容
    "staffInvitedEvaluateTime":"14014679100973", // 客服邀评时间戳 返回-1则为不存在该时间值
    "userJoinEvaluateTime":"14014679100973", // 访客参评时间戳 返回-1则为不存在该时间值
    "userResolvedStatus":1, // 用户标记的解决状态，0=未选择 1=已解决 2=未解决
    "foreignId":"fs", // 由企业提供
    "fromGroupId":999,  // 会话来自分流组ID
    "fromGroup":"2",  // 会话来自分流组名称
    "fromIp":"as",    // 访客来源ip
    "fromPage":"ff",  // 来源页
    "fromStaff":"3",  // 来自哪个客服名
    "fromTitle":"aaa",// 来源页标题
    "fromType":"ios", // 来源类型 web/ios/android/wx(微信)/wx_ma(微信小程序)/wb(微博)/open(开放接口)
    "id":1, // 会话id
    "inQueueTime":4, // 排队时间
    "interaction":0, // 0=客服正常会话  1=机器人会话
    "relatedId":4,   // 被关联的会话id
    "relatedType":2, // 关联会话类型 0=无关联  1=从机器人转接过来 2=机器人会话转接人工 3=历史会话发起 4=客服间转接 5=被接管
    "staffFirstReplyTime":14014679100973, // 客服首次响应的时间戳
    "sType":"会话类型", // 0：正常会话.1(2)：离线留言，3：排队超时
    "staffId":4,  // 客服id
    "staffName":"f", // 客服名字 或为"机器人"
    "startTime":2,   // 会话开始时间
    "stickDuration":43, // 置顶时长
    "userId":43,  // userId
    "remarks":"会话备注",  // 会话备注
    "customFiled": [{\"fieldId\":\"自定义的id\",\"fieldName\":\"自定义名称\",\"fieldValue\":\"自定义实际值\"}],  // 在线服务记录字段
    "status":0,  // 客服标记的解决状态
    "vipLevel":2, // vip 层级 0=非VIP用户
    "visitRange":5, // 与上一次来访的时间差 <=0则忽略
    "transferRgType": "主动转人工", // 转人工类型：主动转人工、关键词转人工、回复引导转人工、拦截词转人工、连续未知转人工、差评转人工、情绪识别转人工、图片转人工
    "roundNumber": 10 ,// 对话回合数
    "clientFirstMessageTime": 14014679100973, //访客首条消息时间
    "avgRespDuration": 11212121, //客服平均响应时长
    "isValid": 1, //是否是有效会话,1为有效会话，0为无效会话
    "humanTransferSessionId": 1212121,//转接来源的会话ID,0代表无转接会话
    "transferFromStaffName": "f",//转接来源分流客服名称
    "transferFromGroup": "g",//转接来源分流客服组名称
    "transferRemarks":"remark",//转接来源备注
    "staffMessageCount": 1,//客服消息数
    "userMessageCount": 2, //用户消息数
    "transferType": "静默转接",//转接类型 静默转接或人工转接
    "overflowFrom": "客服组11",//溢出来源,
    "isStaffInvited": "0",//是否邀请评价 0-没有邀评，1-客服主动邀评，2-系统自动邀评(注意：该字段已废弃，请使用字段isEvaluationInvited)
    "treatedTime": 0, //留言处理时间,若会话不是留言则返回0
    "fromHumanTransfer": 0, //是否来自客服转接  0：非转接会话；1：客服转接过来的会话
    "firstReplyCost": 112233, //客服首次响应时长(访客首条消息与客服首次回复消息的时间间隔)
    "categoryDetail": "xx/xx",//会话咨询分类明细
    "isEvaluationInvited": 0, //是否邀请评价 0-没有邀评，1-客服主动邀评，2-系统自动邀评
    "beginer": 0, //会话发起方  1：访客，2：客服
    "ender": 0, //会话中止方  1：访客，2：客服，3：系统
    "originPlatform": "直接访问", //来源渠道
    "searchKey": "keyword", //关键词
    "landPage": "page", //着陆页url
    "satisfyMsgCount": 1, //好评消息数
    "unsatisfyMsgCount": 0, //差评消息数
    "satisfactionTags": ["评价标签1","评价标签2"] //访客评价时选择的标签
}

其中自定义字段如果是级联类型的，其fieldValue格式如：

{
  "path": "1级/1.1级",  // 每一级的完整名称
  "idpath": [1555974, 1555977], // 每一级对应的ID
  "id": 1555977 //级联自定义字段ID
}

接收会话变更信息通知

支持修改后实时推的字段：会话分类信息、评价结果、评价内容、会话备注、在线服务记录字段、会话状态。 开发者服务器收到的POST请求示例如下：

POST https://QIYU_MSG_URL?eventType=DATA_ONLINE_SESSION_CHANGE&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "sessionId":1, // 会话ID
    "sessionType": "未分类", // 会话咨询分类
    "sessionTypePath": "一级分类/二级分类/三级分类", // 会话咨询分类，包含详细分类路径，最多包含五级
    "status":1, // 解决状态，0：未解决、1：已解决、2：解决中
    "evaluation":1, // 评价结果
    "evaluation_remarks": "评价备注", // "评价备注"
    "userResolvedStatus": 1, //用户标注问题是否已经解决，0：未解决，1：已解决
    "remarks": "备注", // 会话备注
    "customField": "fieldKey:fieldValue;" // 在线服务字段内容
}

其中自定义字段如果是级联类型的，其fieldValue格式如：

{
  "path": "1级/1.1级",  // 每一级的完整名称
  "idpath": [1555974, 1555977], // 每一级对应的ID
  "id": 1555977 //级联自定义字段ID
}

接收会话质检事件通知

开发者服务器收到的POST请求示例如下：

POST https://QIYU_MSG_URL?eventType=DATA_SESSION_QUALITY&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "category":"a/b/c", // 分类
    "evaluationType":4, // 评价模型
    "evaluation":2, // evaluationType:(evaluation)=>  2:(100满意1不满意);  3(100满意50一般1不满意); 5(100非常满意75满意50一般25不满意1非常不满意) 否则未评价
    "evaluationRemark":"xx", // 评价内容
    "forbiddenItems":[ // 禁忌项
        {
            "isDone":1, // 是否发生 1=发生 else 未发生
            "name":"禁忌项名称"
        }
    ],
    "foreignId":"fs", // 由企业提供
    "fromGroup":"2",  // 会话来自分流组名称
    "id":2, // 会话id
    "inspectTime":12, // 质检时间
    "inspector":"质检员", // 质检人
    "qualityComment":"asas", // 质检备注
    "score":21, // 质检分数
    "scoreItems":[ // 指标项及评分
        {
            "max":5.2,
            "name":"质检项名称",
            "value":1.1
        }
    ],
    "staffId":123, // 被质检的客服
    "staffName":"被质检客服名字",
    "startTime":32, // 会话开始时间
    "type":3, // 1：在线；2：呼叫
    "userId":12 // 访客id
}

接收客服撤回消息通知

开发者服务器收到的POST请求示例如下：

POST https://QIYU_MSG_URL?eventType=STAFF_WITHDRAW&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求参数

Body

参数数据类型参数说明
timeStampLong消息发送时间
uidString开发者的应用里的用户 ID。
msgTypeString消息类型，目前支持TEXT,PICTURE,RICHTEXT三种
staffNameString客服姓名。
msgIdString消息ID
sessionIdLong会话ID
staffIdLong客服id
contentString消息内容。文本消息是文本内容，图片和语音消息则是描述的 json， 该字段长度限制最大为 4000 个字符。
content.urlString图片，语音消息的文件 url。请保证该 url 不会存在跨域访问问题。<br />如果不能跨域访问，请使用下面的文件上传接口将文件上传到七鱼服务器，然后使用返回的 url。
content.nameString图片名称
content.sizeInteger文件大小，单位为 byte。
content.md5String文件内容的 MD5。
content.wInteger图片消息中图片的宽度，正确传递该值可以提升客服的浏览体验。
content.hInteger图片消息中图片的高度，正确传递该值可以提升客服的浏览体验。
content.extString图片格式，为图片后缀名
content.contentString富文本内容，详细规范请咨询技术支持
content.cmdInteger目前固定为65

响应空字符串代表接收成功。其他情况默认为推送不成功。会重试三次。

示例

请求示例

{
    "timeStamp": 1710229860734,
    "uid": "fid20240305001",
    "msgType": "TEXT",
    "staffName": "",
    "msgId": "12112390#f9953f2ff9496a67aed72d0ae5050759",
    "sessionId": 1210111,
    "staffId": 59916,
    "content": "您好，请问有什么可以帮您的？"
}

这篇文档有帮助吗？

消息类型说明

在线系统消息推送与消息接口中 msgType 对应的消息体结构。

商品和订单查询详细说明

七鱼调用企业商品、订单查询接口时的请求、签名、分页和响应结构。

目录

请求分配客服
接口请求地址
分配客服的逻辑
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
接收会话开始通知
请求内容示例
接收七鱼消息
接口请求地址
请求参数
Query
Body
示例
请求示例
接收会话结束通知
请求内容示例
接收客服主动邀评通知
请求内容示例
接收用户进入排队通知
接收用户离开排队通知
请求内容示例
客服组排队情况查询
请求接口地址
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
更新用户资料
接口请求地址
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
获取评价设置
接口请求地址
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
评价客服
接口请求地址
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
查询排队状态
接口请求地址
请求参数
Query
Body
响应参数
示例
请求示例
响应示例
主动退出排队
接起请求地址
请求参数
Query
Body
响应参数
示例
请求示例
返回示例
会话结束推送会话数据
接收会话变更信息通知
接收会话质检事件通知
接收客服撤回消息通知
请求参数
Body
示例
请求示例