在线客服访客端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 | 字符串 | 是 | 当前消息时间戳 | 加解密参数 |
| nonce | 字符串 | 是 | 随机数 | |
| msg_signature | 字符串 | 是 | 签名 | |
| msgId | 字符串 | 是 | 消息Id | 用于消息重发和去重 |
c、接口返回
成功创建会话返回
{
"errcode": 0,
"errmsg": “ok”,
"queueLength": 1 //会话当前排队位置；一般是从1开始；
}
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 | 数字 | 是 | 消息列表中每条消息的时间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 | 用于消息重发和去重 |
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 | 字符串 | 否 | 电话 | 访客留言的电话 |
| 字符串 | 否 | 邮箱 | 访客留言的邮箱 | |
| 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 | 当前没有正在进行中的会话 要发送消息得创建一个会话 |
| 20001 | invalid msgType | 非法的msgType |
| 20002 | invalid msg data | 非法的消息 |
| 20003 | not found appraise config | 评价配置不存在 |
