消息转发说明文档V1.3

1 消息相关描述

这几类消息都是以会话消息为基准,其他消息通过会话cid来关联.消息的发送的顺序一般是,先是用户消息,然后聊天消息,再是会话消息(会话结束才发),最后是评价消息.用户信息有修改消息会重复发一次.消息每次批量发50条,如果无数据则按照时间1秒发一次.

2 会话消息

2.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。

2.2 测试调用地址

无

2.3 入参

会话的Json格式如下表所示：

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid	M	会话id	String
source	M	用户来源	Int	0-pc,1-微信，2-sdk，3-微博，4-移动网站，9-企业微信，10-微信小程序
startTime	O	开始时间	String
partnerId	O	合作方用户id	String
endTime	M	结束时间	String
conversationDuration	M	会话时间	String	单位秒
staffEmail	O	客服Email	String
staffName	O	客服姓名	String
chatWithRobotMsgCount	M	咨询机器人消息数	Int
robotReplyMsgCount	M	机器人回复数	Int
chatWithStaffMsgCount	M	咨询人工消息数	Int
staffReplyMsgCount	M	人工回复数	Int
is2Human	M	是否转人工	Boolean
is2HumanSucc	M	转人工是否成功	Boolean
queueTime	M	排队时间	Int
ip	O	IP	String
area	O	区域	String
os	O	操作系统	String	1=Windows XP，2=Windows 7，3=Windows 8，4=Windows Vista，5=Windows 其他，6=Linux，7=macOS，8=Android，9=iOS，11=Windows 2000，12=Windows 10 ，其他=其他
visitorId	M	用户Id	String
sessionQueueState	M	排队状态	Int	1，未排队接通2，排队接通3，排队离开
lastGroupId	O	最后接待客服组Id	String
lastGroupName	O	最后接待客服组名称	String

唯一主键：cid,各个表之间使用cid来关联,表示是同一个会话

2.4 入参举例

入参示例如下所示：

{
	   "type": "conversation",
	   "content": [
	       {
	           "companyId": "5cc2c708202d4defaf72d4bcac362a55",
	           "cid": "86937e82ae244ad59aeefe41af731079",
	           "source": 2,
	           "startTime": 1468826506677,
	           "EndTime": 1468827002400,
	           "conversationDuration": 495723,
	           "staffEmail": "",
	           "staffName": "robot",
	           "chatWithRobotMsgCount": 3,
	           "robotReplyMsgCount": 20,
	           "chatWithStaffMsgCount": 0,
	           "staffReplyMsgCount": 0,
	           "is2Human": 1,
	           "is2HumanSucc": 1,
	           "queueTime": -1,
	           "ip": "60.18.150.38",
	           "area": "辽宁",
	           "os": "8",
	           "visitorId": "837213545777846"
	       }
	   ]
}

2.5 出参

成功返回空字符串,报错返回错误信息.

3 聊天消息

3.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。

3.2 测试调用地址

无

3.3 入参

聊天消息Json格式如下表所示

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid	M	会话Id	String
timems	M	时间	Long	毫秒
time	M	时间	String
senderName	M	发送人	String
receiverName	M	接收人	String
senderType	M	发送类型	Int	0 访客，1 机器人，2客服
receiverType	M	接收类型	Int	0 访客，1 机器人，2客服
msg	M	消息	String

唯一主键：cid+time+senderName机器人和人工可分别评价

3.4 入参举例

入参示例如下所示：

{

   "type": "msg",
   "content": [
       {
           "companyId": "5cc2c708202d4defaf72d4bcac362a55",
           "cid": "44c603626e2e4c82a5a49619a8aaa397",
           "time": "2016-07-18 15:30:16",
           "senderName": "冯建武",
           "receiverName": null,
           "msg": "到还款日，延期3天怎么算"
       }
  ]
}

3.5 出参

成功返回空字符串,报错返回错误信息.

4 评价信息

4.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。

4.2 测试调用地址

无

4.3 入参

聊天消息Json格式如下表所示：

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid	M	会话Id	String
staffId	O	客服Id	String
source	M	用户来源	String	0-pc,1-微信，2-sdk，3-微博，4-移动网站，9-企业微信，10-微信小程序
adminName	M	评价对象	String	可能是客服或者机器人
isRobot	M	是否机器人	Boolean
remark	O	备注	String
tag	O	评价标签	String
score	M	评分	int
visitorId	M	访客Id	String
datetime	M	时间	Long

唯一主键：cid+isRobot 机器人和人工可分别评价

4.4 入参举例

入参示例如下所示：

{
	   "type": "evaluation",
	   "content": [
	       {
	           "companyId": "5cc2c708202d4defaf72d4bcac362a55",
	           "staffId": "9517",
	           "source": 0,
	           "adminName": null,
	           "isRobot": true,
	           "remark": "审核没通过",
	           "tag": "答非所问,问题不能回答",
	           "score": 0,
	           "visitorId": "97b31cba87e04dcdafe0ebb60248ecf4",
	           "datetime": 1468340203266,
	           "cid": "9ae05bc279544b68895cd86b12e418e0"
	       }
	   ]
}

4.5 出参

成功返回空字符串,报错返回错误信息.

5 用户访客信息

5.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。

5.2 测试调用地址

无

5.3 入参

用户Json格式如下表所示：

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
userId	M	用户Id	String
cid	M	会话Id	String
telphone	O	电话	String
email	O	email	String
qq	O	qq	String
partnerId	O	在本公司系统中该用户的id	String
userName	M	姓名	String
params	O	动态参数josn格式,	String	对接时传过来的
remark	O	备注	String

唯一主键：userId

5.4 入参举例

入参示例如下所示：

{
	   "type": "user",
	   "content": [
	       {
	           "companyId": "5cc2c708202d4defaf72d4bcac362a55",
	           "userId": "837213545777846",
	           "cid": "86937e82ae244ad59aeefe41af731079",
	           "telphone": "13545777846",
	           "email": "506003007@qq.com",
	           "qq": "",
	           "partnerId": "13545777846",
	           "userName": "孙盼",
	           "remark": "",
	           "params": {
	               "a": "动态参数"
	           }
	       }
	   ]
}

5.5 出参

成功返回空字符串,报错返回错误信息.

6 转接等系统信息

6.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。

6.2 测试调用地址

无

6.3 测试调用地址

无

6.4 入参

与机器人建立会话 type=4 sender是用户

{"cid":"75029a0997cd412bbe403e727c961f69","companyId":"7ce3cd52355e4f359cf44017b051d1e8","sender":"f731fa6f1ca8a8d8a09ff90bffb56321","senderName":"北京用户","ts":"2017-05-27 00:01:50","type":4}

开始转人工 type=6 sender是用户

{"cid":"d09cbb9dfc0c4d059757b226d6aef801","companyId":"045769553fb744c6a8cb57bb676b3261","sender":"4193c96879c442898bf1ff4010c90cbe","senderName":"北京用户","ts":"2017-05-27 01:28:53","type":6}

转人工排队开始 type=7 sender是用户

{"cid":"6757a500c82e4c5c874ec9242c07322a","companyId":"e42bd9b6fc23472b93f44a5c5fa720ff","sender":"e42bd9b6fc23472b93f44a5c5fa720ff13835700152","senderName":"北京用户","ts":"2017-05-27 08:06:18","type":7}

客服主动邀请客服（不管客服是否是忙碌状态）type=21 sender是客服

{"cid":"19c417aabe4c44b6b1a49868b664bcf8","companyId":"b96b3e57c0814d9d987bd21efc7c5934","senderEmail":"309867471@qq.com","receiver":"6cdd081e5c95d38d4b9870b9e2e79c9b","receiverName":"北京用户","sender":"dbbf139219204b14bfe5d47ceafbd980","senderName":"丹丹","ts":"2017-05-27 09:03:13","type":21}

与人工建立会话 type=8 sender是用户，receiver是客服

{"cid":"252025b1fdbc4f629023378be497883f","companyId":"7923","receiverEmail":"xieyusong@bianfeng.com","receiver":"9518","receiverName":"客服2","sender":"5b93f5a0a6f04b0dbd219e3228ab2a65","senderName":"北京用户","ts":"2017-03-28 00:41:05","type":8}

客服sender把userId转接客服receiver type=9 （不管客服是否是忙碌状态，都是成功的）

{"cid":"77a49f6f90334b1abb2158b76c1b7b13","companyId":"a3820569819f44649d4e6367a21d2f19","receiver":"662a20a1a57d4db79b70d7721c00d9b3","receiverName":"必要客服6042","receiverEmail":"432432@qq.com"，"sender":"6ac0a00ddb794b5f8e69e6a38b95be58","senderEmail":"534577@qq.com","senderName":"6104","ts":"2017-03-28 00:00:23","userId":"a3820569819f44649d4e6367a21d2f193059308","userName":"北京用户","type":9}

6.5 入参举例

入参示例如下所示：

{
   "type": "systemMsg",
   "content": [
       {
           "cid": "75029a0997cd412bbe403e727c961f69",
           "companyId": "7ce3cd52355e4f359cf44017b051d1e8",
           "sender": "f731fa6f1ca8a8d8a09ff90bffb56321",
           "senderName": "北京用户",
           "ts": "2017-05-27 00:01:50",
           "type": 4
       },
       {
           "cid": "d09cbb9dfc0c4d059757b226d6aef801",
           "companyId": "045769553fb744c6a8cb57bb676b3261",
           "sender": "4193c96879c442898bf1ff4010c90cbe",
           "senderName": "北京用户",
           "ts": "2017-05-27 01:28:53",
           "type": 6
       },
       {
           "cid": "6757a500c82e4c5c874ec9242c07322a",
           "companyId": "e42bd9b6fc23472b93f44a5c5fa720ff",
           "sender": "e42bd9b6fc23472b93f44a5c5fa720ff13835700152",
           "senderName": "北京用户",
           "ts": "2017-05-27 08:06:18",
           "type": 7
       },
       {
           "cid": "19c417aabe4c44b6b1a49868b664bcf8",
           "companyId": "b96b3e57c0814d9d987bd21efc7c5934",
           "senderEmail": "309867471@qq.com",
           "receiver": "6cdd081e5c95d38d4b9870b9e2e79c9b",
           "receiverName": "北京用户",
           "sender": "dbbf139219204b14bfe5d47ceafbd980",
           "senderName": "丹丹",
           "ts": "2017-05-27 09:03:13",
           "type": 21
       },
       {
           "cid": "252025b1fdbc4f629023378be497883f",
           "companyId": "7923",
           "receiverEmail": "xieyusong@bianfeng.com",
           "receiver": "9518",
           "receiverName": "客服2",
           "sender": "5b93f5a0a6f04b0dbd219e3228ab2a65",
           "senderName": "北京用户",
           "ts": "2017-03-28 00:41:05",
           "type": 8
       },
       {
           "cid": "77a49f6f90334b1abb2158b76c1b7b13",
           "companyId": "a3820569819f44649d4e6367a21d2f19",
           "receiver": "662a20a1a57d4db79b70d7721c00d9b3",
           "receiverName": "必要客服6042",
           "receiverEmail": "432432@qq.com",
           "sender": "6ac0a00ddb794b5f8e69e6a38b95be58",
           "senderEmail": "534577@qq.com",
           "senderName": "6104",
           "ts": "2017-03-28 00:00:23",
           "userId": "a3820569819f44649d4e6367a21d2f193059308",
           "userName": "北京用户",
           "type": 9
       }
   ]
}

7 客服信息(默认不转发)

7.1 接口要求

Post方法,接收智齿科技发送过来的Json格式消息,在客户的服务器上部署.例如https://xxxxxxx.xxxxxx.com/sobot/message,建议所有的消息使用同一个地址。此消息非实时消息,一小时推送一次.

7.2 测试调用地址

无

7.3 入参

用户Json格式如下表所示：

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
serviceId	M	客服Id	String
serviceName	M	真实姓名	String
serviceNick	O	昵称	String
serviceEmail	M	email	String

唯一主键：serviceId

7.4 入参举例

入参示例如下所示：

{
	   "type": "staff",
	   "content": [
	       {
	           "companyId": "5cc2c708202d4defaf72d4bcac362a55",
	           " serviceId": "837213545777846",
	           " serviceName": "86937e82ae244ad59aeefe41af731079",
	           " serviceNick": "13545777846",
	           " serviceEmail": "506003007@qq.com"
	       }
	   ]
}

7.5 出参

成功返回空字符串,报错返回错误信息.

8 浏览轨迹信息(默认不提供)

8.1 接口要求

此消息需要开启浏览轨迹,一般公司不需要。

8.2 测试调用地址

https://shimo.im/doc/wgeuPeXkaoUmBKQz

8.3 测试调用地址

无

8.4 入参

开放借口

唯一主键：cid ,表示一次访问和一次对话

属性	必选	名称	数据类型	说明
companyId	M	公司Id		适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
messageVisitorToStaff	O	用户发给客服消息数	Long
messageStaff	O	客服消息数	Long
jumpCount	O	跳出率(是否跳出)	Long	0未跳出，1跳出
landpageUrl	O	首次访问页面的URL	String
searchSource	O	客户来源	Int
lastStaffName	O	最后接待客服名称	String
lastGroupId	O	最后接待客服组	String
convLaunchUrl	O	对话页面url	String
chatStartTime	O	会话建立时间	Long
convEndDateTime		会话结束时间	Long
visitStartTime		页面访问时间	Long
sessionHumanDuration		会话接待时长	Long
keyword		搜索词	String
totalTimesHuman		人工是否参评	Int	totalTimesHuman>0表示已经参评
solvedHuman		人工解决问题	Int	solvedHuman>0表示已解决
solvedRobot		机器人解决问题	Int	solvedRobot>0表示已解决
totalScore		星级	Int
sessionAccepQueueDuration		排队接通时长	Long
sessionLeaveInQueueDuration		排队离开时长	Long
visitDuration		浏览时长	Long
Pv	M	访问页面就计一次	Long
uid	M	咨询客户id	String
cid	M	会话id	String	主键
areaCode	O	地域	String
Source		咨询渠道	Int	0-pc,1-微信，2-sdk，3-微博，4-移动网站，9-企业微信，10-微信小程序
engineType		搜索引擎	Int	1百度自然搜索, 2 百度付费搜索 3 360搜索 4 Sougou 5 神马 6 必应7 google 8其他搜索引擎
landpageUrlOrignal		首次访问页面的原始URL	String
convLaunchUrlOrignal		对话页面原始	String
firstUrlDateTime		首次着陆页时间	Long

8.5 入参举例

入参示例如下所示：

{"areaCode":"杭州","chatStartTime":1504746523055,"cid":"29cbb8d3ba0d4f30a9e1852663d34225","convEndDateTime":1504747173480,"convLaunchUrl":"http://www.koolearn.com/class/kaoyan2/","firstUrlDateTime":1504743424237,"jumpCount":1,"landpageUrl":"http://www.koolearn.com/class/kaoyan2/","lastGroupId":"b525a4e23e9c48ed9e42cdfc9b9f3f8b","lastStaffName":"张昊","messageStaff":1,"messageVisitorToStaff":"1","pv":2,"searchSource":3,"sessionAccepQueueDuration":0,"sessionHumanDuration":272618,"sessionLeaveInQueueDuration":0,"source":0,"totalScore":5,"totalTimesHuman":1,"uid":"abfbbc0552064b79991ad55635907888","visitDuration":3115671,"visitStartTime":1504743424237}

9 接口定义

数据具体是用post方法在body中发送出去,注意收到数据后先做缓存,另外一个线程(或者进程)来负责入库,否则会影响发送数据的速度.

10 转发策略

http 设置10秒超时,每次转发20条消息,如果到1秒也会转发一次,没消息不转发.如果转发失败,重试一次,重试失败则丢掉.如果发现丢消息严重的情况联系技术把某段时间的消息重发.

11 存储设计注意事项

注意每个消息说明时都有一个主键,主要用来判重,因为有重试机制,消息可能会被发多次,设计表示注意设置unique index(或者类似的判断唯一标准)