在线客服访客端API接口

本接口的使用需要接口使用方有研发能力，本接口实现的业务场景是：针对访客消息，您这边有自己的业务逻辑（如有自己的机器人），只有需要使用人工在线客服的时候才接入到我们客服系统。实现原理：七陌提供一个接收在线客服消息的地址，当有访客消息需要客服人员处理时，您调用七陌方提供的接口发起请求，把信息推送给客服。当客服回复消息后，七陌会把对应的消息再推送给您，从而实现会话交流的能力。

一、在云客服平台配置相关信息

1、在云客服平台配置相关信息拿到accessId和token。

a、配置

b、获取accessId和token

二、消息鉴权

1、鉴权方式

a、签名计算

dev_msg_signature = sha1(sortAndJoin(token, timestamp, nonce, userId))。sortAndJoin的含义是把参数按照字母字典排序，然后从小到大拼接成一个字符串。

b、签名比较

比较dev_msg_signature和msg_signature是否相等，相等则表示验证通过。

2、签名计算示例

a、NodeJs

var crypto = require('crypto');
var token = '${token}';
var timestamp = '${timestamp}';
var nonce = '${nonce}';
var userId = '${userId}';//获取满意度评价时，用accessId作为userId进行签名
var shasum = crypto.createHash('sha1');
var arr = [token, timestamp, nonce, userId].sort();
shasum.update(arr.join(''));
var msg_signature = shasum.digest('hex');

b、java示例

三、消息重发机制

除有特殊说明的接口外，云客服与第三方的接口均应在5s内返回响应结果，5s内未响应的，可使用相同的msgId重复发送，最多三次。

四、云客服提供的接口

1、新建会话【该接口不在5s内返回的接口中】

a、接口信息

字段	含义
接口路径	https://im-api.7moor.com/visitor/session
提交方式	POST
Content-Type	application/json
字符集编码	utf-8

注意：如果查询出来的请求域名{HOST}是https://openapis.7moor.com，则接口访问地址域名需要将https://im-api.7moor.com替换为https://ykf-im-api.7moor.com。

b、消息体详情

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
userId	字符串	是	用户id
nickName	字符串	是	用户的昵称
agentId	字符串	否	指定座席工号，需要为系统内已存在且未停用的座席工号
followDefaultSkillGroup	布尔	否	是否跟随默认技能组配置，该参数仅在指定座席工号无法分配会话时生效； 若为true，系统将在指定座席工号无法分配会话时按照接入号中配置的技能组 创建会话并分配。若为false则不跟随该配置
platform	字符串	是	来源： pc：pc网页 wap：wap网页 sdk: 移动端 weixin：微信 wxmini：微信小程序 weibo：微博
timestamp	字符串	是	当前消息时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

c、接口返回

成功创建会话返回

{
   "errcode": 0,
   "errmsg": “ok”,
   "queueLength": 1 //会话当前排队位置；一般是从1开始；
}

d、失败创建会话返回

{
  "errcode": 10016,
  "errmsg": "designated_online_seats_cannot_be_used"
}

2、访客消息

a、接口信息

字段	含义
接口路径	https://im-api.7moor.com/visitor/message
提交方式	POST
Content-Type	application/json
字符集编码	utf-8

注意：如果查询出来的请求域名{HOST}是https://openapis.7moor.com，则接口访问地址域名需要将https://im-api.7moor.com替换为https://ykf-im-api.7moor.com。

b、消息体详情

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
userId	字符串	是	用户id
platform	字符串	是	来源： pc：pc网页 wap：wap网页 sdk: 移动端 weixin：微信 wxmini：微信小程序 weibo：微博
msgType	字符串	是	消息类型： 文本：text 图片：image 文件：file 语音：voice（只支持mp3格式） 视频：video（只支持mp4格式） 消息列表：msgList 评价：appraise 订单卡片：newCardInfo
content	字符串	是	消息内容（多媒体消息为文件的url）
contentList	数组	否	消息列表类型时使用
contentList[i].msgType	字符串	是	消息列表中每条消息的消息类型
contentList[i].content	字符串	是	消息列表中每条消息的内容
contentList[i].timestamp	数字	是	消息列表中每条消息的时间Unix时间戳
contentList[i].type	字符串	是	消息列表中每条消息的类型 out: 发给访客 in: 访客发送
contentList[i].user	字符串	否	消息列表中每条消息的发送人 type为in时不需要 type为out时 系统：system 机器人：robot
contentList[i].showHtml	布尔	是	是否将消息内容按照HTML解析Boolean(字符串)
appraise	对象	否	msgType为appraise时使用
appraise.way	字符串	是	评价的方式 in: 访客主动评价 out: 座席请求评价
appraise.satisfaction	字符串	是	评价内容
appraise.appraiseKey	字符串	否	评价内容对应的key
appraise.label	字符串数组	否	评价标签数组
appraise.proposal	字符串	否	建议内容
timestamp	字符串	是	当前消息时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

当msgType为newCardInfo时，商品卡片字段传参内容如下

字段	数据类型	是否必填	描述
visible	boolean	是	商品信息卡片是否展示。值为true即可
actionText	string	是	按钮文案：（不超过6个字）
actionTextColor	string	否	按钮文案颜色
title	string	是	商品信息主标题
sub_title	string	否	商品信息副标题
img	string	否	商品信息图片logo
attr_one	object	否	color 配置内容颜色，content 属性内容商品信息的属性，例如：数量
attr_two	object	否	color 配置内容颜色，content 属性内容商品信息的属性，例如：发货状态
price	string	否	商品价格
other_title_one	string	否	商品信息的附加信息（卡片下方备注信息）
other_title_two	string	否	商品信息的附加信息（卡片下方备注信息）
other_title_three	string	否	商品信息的附加信息（卡片下方备注信息）
target	string	否	点击商品信息卡片时的跳转链接
tags	array	否	订单类消息展示的功能按钮，label为按钮的名称，focusIframe为定位到iframe的标识，与系统内tab页的名称匹配。 url为非必填，若没有focusIframe字段或没有匹配到对应的iframe，以新窗口方式打开配置的url链接。 showRange为按钮展示方，该字段不存在(兼容老客户)或者为all访客端座席端都展示，seats座席端展示，visitor访客端展示
showCardInfoMsg	string	是	此字段为向七陌发送卡片信息的标识，为1展示并接收此消息，为0则不接收此消息（此字段为必填项，没有七陌则不会接收）值为 1 即可

注意：访客的聊天窗口是由您自定义的，以上卡片呈现效果仅在坐席端生效，访客看到的订单卡片效果由您自定义实现

卡片传参示例：单条卡片数据

{
      "accessId": "e38e8340-a5a5-11f0-aace-21a8eeaxxxxx",
      "userId": "fenda_water11",
      "platform": "pc",
      "msgType": "newCardInfo",
      "timestamp": "123456789",
      "nonce": "567",
      "msg_signature": "e42b3203d751dd0dc2a35ac10f0ae7bd8d392cd6",
      "msgId": "111455",
      "content": "{\"visible\":true,\"actionText\":\"发送\",\"actionTextColor\":\"#fff\",\"title\":\"吊灯极品装饰全新上市，北欧风格\",\"sub_title\":\"使用世界前沿的人工智能技术,为用户甄选海量的高清美图,用更流畅、更快捷、更精准的搜索体验\",\"other_title_one\":\"吊灯极品装饰\",\"other_title_two\":\"吊灯极品装饰\",\"other_title_three\":\"吊灯极品装饰\",\"img\":\"https://www.7moor.com/wp-content/uploads/2017/03/publicT_03.png\",\"price\":\"￥200\",\"attr_one\":{\"color\":\"#000000\",\"content\":\"X1\"},\"attr_two\":{\"color\":\"#000000\",\"content\":\"已发货\"},\"target\":\"https://www.7moor.com\",\"time\":\"agent\",\"tags\":[{\"label\":\"按钮名称\",\"url\":\"www.7moor.com\",\"focusIframe\":\"iframe名称\",\"showRange\":\"visitor\"},{\"label\":\"按钮名称1\",\"url\":\"https://www.7moor.com\",\"focusIframe\":\"iframe名称1\",\"showRange\":\"visitor\"}],\"showCardInfoMsg\":1}"
}

卡片传参示例：多条卡片数据（通过msgList传递）

{
      "accessId": "e38e8340-a5a5-11f0-aace-21a8eeab4694",
      "userId": "fenda_water11",
      "platform": "pc",
      "msgType": "msgList",
      "timestamp": "123456789",
      "nonce": "567",
      "msg_signature": "e42b3203d751dd0dc2a35ac10f0ae7bd8d392cd6",
      "msgId": "111455",
      "content": "消息列表发送",
      "contentList": [
        {
          "msgType": "newCardInfo",
          "content": "{\"visible\":false,\"actionText\":\"发送\",\"actionTextColor\":\"#fff\",\"title\":\"1111吊灯极品装饰全新上市，北欧风格\",\"sub_title\":\"1111使用世界前沿的人工智能技术,为用户甄选海量的高清美图,用更流畅、更快捷、更精准的搜索体验\",\"other_title_one\":\"吊灯极品装饰\",\"other_title_two\":\"吊灯极品装饰\",\"other_title_three\":\"吊灯极品装饰\",\"img\":\"https://www.7moor.com/wp-content/uploads/2017/03/publicT_03.png\",\"price\":\"￥200\",\"attr_one\":{\"color\":\"#000000\",\"content\":\"X1\"},\"attr_two\":{\"color\":\"#000000\",\"content\":\"已发货\"},\"target\":\"https://www.7moor.com\",\"time\":\"agent\",\"tags\":[{\"label\":\"按钮名称\",\"url\":\"www.7moor.com\",\"focusIframe\":\"iframe名称\",\"showRange\":\"visitor\"},{\"label\":\"按钮名称1\",\"url\":\"https://www.7moor.com\",\"focusIframe\":\"iframe名称1\",\"showRange\":\"visitor\"}],\"showCardInfoMsg\":1}",
          "timestamp": "11111",
          "type": "in",
          "showHtml": false
        },
        {
          "msgType": "newCardInfo",
          "content": "{\"visible\":true,\"actionText\":\"发送\",\"actionTextColor\":\"#fff\",\"title\":\"2222吊灯极品装饰全新上市，北欧风格\",\"sub_title\":\"2222使用世界前沿的人工智能技术,为用户甄选海量的高清美图,用更流畅、更快捷、更精准的搜索体验\",\"other_title_one\":\"吊灯极品装饰\",\"other_title_two\":\"吊灯极品装饰\",\"other_title_three\":\"吊灯极品装饰\",\"img\":\"https://www.7moor.com/wp-content/uploads/2017/03/publicT_03.png\",\"price\":\"￥200\",\"attr_one\":{\"color\":\"#000000\",\"content\":\"X1\"},\"attr_two\":{\"color\":\"#000000\",\"content\":\"已发货\"},\"target\":\"https://www.7moor.com\",\"time\":\"agent\",\"tags\":[{\"label\":\"按钮名称\",\"url\":\"www.7moor.com\",\"focusIframe\":\"iframe名称\",\"showRange\":\"visitor\"},{\"label\":\"按钮名称1\",\"url\":\"https://www.7moor.com\",\"focusIframe\":\"iframe名称1\",\"showRange\":\"visitor\"}],\"showCardInfoMsg\":0}",
          "timestamp": "22222",
          "type": "in",
          "showHtml": false
        }
      ]
}

c、接口返回

成功收到消息后返回

{
    errcode: 0,
    errmsg: “ok”
}

3、获取满意度评价配置

a、接口信息

字段	含义
接口路径	https://im-api.7moor.com/visitor/appraise/accessId?timestamp=*&nonce=*&msg_signature=* 此处签名计算用accessId作为userId
提交方式	GET
Content-Type
字符集编码	utf-8

注意：如果查询出来的请求域名{HOST}是https://openapis.7moor.com，则接口访问地址域名需要将https://im-api.7moor.com替换为https://ykf-im-api.7moor.com。

b、消息体详情

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
timestamp	字符串	是	当前消息时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

c、接口返回

{
    errcode: 0,
    errmsg: "ok",
    data: [
        {
            index: 0",
            key: "37368950-1682-11e7-aeca-1b7457332eef",
            name: "好评",
            “reason”: [
                “标签1”,
                “标签2”
            ]
        },
        {
            index: “1”,
            key: “37368951-1682-11e7-aeca-1b7457332eef”,
            name: “差评”,
            “reason”: [
                “标签1”,
                “标签2”
                ]
        }
    ]
}

4、访客留言

a、接口信息

字段	含义
接口路径	https://im-api.7moor.com/visitor/leaveMsg
提交方式	POST
Content-Type	application/json
字符集编码	utf-8

注意：如果查询出来的请求域名{HOST}是https://openapis.7moor.com，则接口访问地址域名需要将https://im-api.7moor.com替换为https://ykf-im-api.7moor.com。

b、消息体详情

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
userId	字符串	是	用户id
token	字符串	否	消息签名token
platform	字符串	是	来源： pc：pc网页 wap：wap网页 sdk: 移动端
timestamp	字符串	是	当前消息时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
message	字符串	是	留言	留言的所有信息都包括在这个字段里
phone	字符串	否	电话	访客留言的电话
email	字符串	否	邮箱	访客留言的邮箱
urlTitle	字符串	否	页面来源渠道：im在线（默认）	可配置访客来源页面的来源头 和来源页面地址，如果需要配置则 两个参数都需要传，只传一个无法配置； 如果不配置会有默认参数， 此时点击来源超链接，会刷新云客服界面。
fromUrl	字符串	否	来源页面地址

c、接口返回

{
    "errcode": 0,
    "errmsg": "ok"
}

5、排队状态查询接口

用于客户查询该用户ID是否在排队状态

a、接口信息:

字段	含义
接口路径	https://im-api.7moor.com/visitor/session?timestamp=xxx11&userId=123123&nonce=123123&accessId=&msg_signature= 此处签名计算用accessId作为userId
提交方式	GET
Content-Type
字符集编码	utf-8

注意：如果查询出来的请求域名{HOST}是https://openapis.7moor.com，则接口访问地址域名需要将https://im-api.7moor.com替换为https://ykf-im-api.7moor.com。

b、消息体详情:

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
userId	字符串	是	用户id	消息参数
timestamp	字符串	否	当前消息时间戳	加解密参数
nonce	字符串	是	随机数	加解密参数
msg_signature	字符串	是	签名	加解密参数

c、接口返回(访客在排队时):

{
    "errcode":0,
    "errmsg":"ok",
    "data":{
        "createTime": "2024-06-20 17:11:23",
        "createTimeStamp": 1718874683610,
        "agentExten":"",
        "agentName":"",
        "agentImage":"",
        "queueLength":2
          }
}

c、接口返回(访客已转人工):

{
    "errcode":0,
    "errmsg":"ok",
    "data":{
        "createTime": "2024-06-20 17:11:23",
        "createTimeStamp": 1718874683610,
        "agentExten":"7999",
        "agentName":"7999客服",
        "agentImage":"https://cc-common-cos.7moor.com/N00000003731/icon/2022-11-30_18:56:46/1669805806611/47ade0fa-c2af-43d0-a0e0-79601ae2e096",
        "queueLength":-1 //-1，则表示正在被接待
          }
}

五、对接方应提供的接口

1. 接收消息接口

a、接口信息

字段	含义
接口路径	在云客服中配置
提交方式	POST
Content-Type	application/json
字符集编码	utf-8

b、消息体详情

参数名称	参数类型	是否必须	参数描述	参数作用
accessId	字符串	是	接入号id	消息参数
userId	字符串	是	用户id
msgType	字符串	是	消息类型 座席领取：claim 文本：text 图片：image 文件：file 语音：voice 视频：video 富文本: richText 评价：appraise 结束会话：finish
content	字符串	是	消息内容（多媒体消息为文件的url）
richTextTitle	字符串	否	富文本类型消息的标题
richTextPicUrl	字符串	否	富文本类型消息的缩略图
richTextDescription	字符串	否	富文本类型消息的摘要
richTextUrl	字符串	否	富文本类型消息的跳转链接
agentId	字符串	是	发送消息的座席id，系统发送的消息该字段值为system
agentExten	字符串	否	发送消息的座席工号
agentName	字符串	否	发送消息的座席名称
agentImage	字符串	否	发送消息的座席头像地址
timestamp	整型	是	当前消息Unix时间戳	加解密参数
nonce	字符串	是	随机数
signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

c、接口返回

success

六、错误码列表

errcode	errmsg	说明
0	ok	请求成功
10000	server error	服务异常
10001	content-type must be application/json	错误的content-type
10002	message body is empty/td>	request body为空
10003	accessId is required	缺少accessId参数
10004	userId is required	缺少userId参数
10005	repeat msgId	重复的消息id
10006	accessId not found	错误的accessId
10007	invalid signature	签名验证失败
10008	userId not found	错误的userId
10009	chat session exists	已存在会话
10010	config not found	接入配置不存在
10011	skill group not found	技能组不存在
10012	online agent not found	无在线坐席
10013	chat session not found	当前没有正在进行中的会话 要发送消息得创建一个会话
10015	Seat ID is empty and follows default skill group configuration as\' No \	座席工号为空且跟随默认技能组配置为false
10016	designated_online_seats_cannot_be_used	坐席（坐席不在线或不空闲）和技能组不可用
20001	invalid msgType	非法的msgType
20002	invalid msg data	非法的消息
20003	not found appraise config	评价配置不存在