在线客服访客端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网页
app: 移动端
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网页
app: 移动端
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”
                ]
        }
    ]
}

五、对接方应提供的接口

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 字符串 随机数
msg_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 评价配置不存在