在线客服访客端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	字符串	是	用户的昵称
platform	字符串	是	来源： pc：pc网页 wap：wap网页 sdk: 移动端 weixin：微信 wxmini：微信小程序 weibo：微博
timestamp	字符串	是	当前消息Unix时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

c、接口返回

成功创建会话返回

{
   errcode: 0,
   errmsg: “ok”
}

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
content	字符串	是	消息内容（多媒体消息为文件的url）
contentList	数组	否	消息列表类型时使用
contentList[i].msgType	字符串	是	消息列表中每条消息的消息类型
contentList[i].content	字符串	是	消息列表中每条消息的内容
contentList[i].timestamp	数字	是	消息列表中每条消息的时间Uinx时间戳
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	字符串	是	当前消息Unix时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
msgId	字符串	是	消息Id	用于消息重发和去重

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	字符串	是	当前消息Unix时间戳	加解密参数
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	字符串	是	当前消息Unix时间戳	加解密参数
nonce	字符串	是	随机数
msg_signature	字符串	是	签名
message	字符串	是	留言	留言的所有信息都包括在这个字段里
phone	字符串	否	电话	访客留言的电话
email	字符串	否	邮箱	访客留言的邮箱
urlTitle	字符串	否	页面来源渠道：im在线（默认）	可配置访客来源页面的来源头 和来源页面地址，如果需要配置则 两个参数都需要传，只传一个无法配置； 如果不配置会有默认参数， 此时点击来源超链接，会刷新云客服界面。
fromUrl	字符串	否	来源页面地址

c、接口返回

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

五、对接方应提供的接口

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	字符串	否	富文本类型消息的摘要
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	当前没有正在进行中的会话 要发送消息得创建一个会话
20001	invalid msgType	非法的msgType
20002	invalid msg data	非法的消息
20003	not found appraise config	评价配置不存在