自定义渠道接入

前言

开发者接收消息分为两种情况，一种是客服或机器人回复给访客的消息，另一种是一洽服务器主动推送给开发者的消息。(示例数据是以明文的模式来供开发者参考)
接受一洽推送消息的标准字段为：

参数	参数类型	描述
mediaId	string	渠道的mediaId，在配置界面查看
cipherContent	string	plainContent加密后的内容
plainContent	string	明文内容，json格式

具体消息内容在 cipherContent还是plainContent，需要根据公司api配置出的安全模式决定。

注意：每次收到post请求后需要返回一洽 success 没有返回一洽会判断为未收到而重新发送

消息定义

1. 基础参数

所有消息都可包含基础参数，部分必传，部分非必传

参数	参数类型	描述
mediaId	string	渠道的mediaId，在配置界面查看
userId	string	访客ID，每个渠道下访客身份的唯一标识ID
userType	number	访客是否是会员 0:不是 1:是 如果访客为会员访客，那么此访客在所有渠道包括web、sdk渠道来访时一洽会识别为一个访客
visitorId	string	访客完整ID，访客在一洽的唯一标识
msgType	string	标识消息类型，每个消息有对应的固定msgType

2. 对话消息

注意，对于对话结束后的评价操作，一洽提供了一个图文消息（可在样式中配置）供访客点击，会跳转到对话评价页面进行对话评价。

2.1 文本消息

对象	参数	参数类型	描述
	msgType	string	text
text	content	string	文本内容，支持html最大长度限制：10000
	translation	string	译文

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "text",
		"text": {
			"content": "你好"
		},
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.2 图片消息

对象	参数	参数类型	描述
	msgType	string	image
image	picUrl	string	图片地址 最大长度限制：1024
	thumbUrl	string	图片缩略图地址 最大长度限制：1024

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"image": {
			"picUrl": "http://qnfile.echatsoft.com/6b301ca5-0515-4e66-83ec-32986c78944e",
			"thumbUrl": "http://qnfile.echatsoft.com/6b301ca5-0515-4e66-83ec-32986c78944e?imageView2/0/w/200/h/150"
		},
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "image",
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.3 语音消息

对象	参数	参数类型	描述
	msgType	string	voice
voice
	format	string	语音格式(mp3,amr)
	fileUrl	string	语音文件地址，最大长度限制：1024
	fileSize	number	文件大小(KB)
	duration	number	播放时长(毫秒)

接收消息示例：

{
"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"voice": {
		"format":"mp3",
        "fileUrl":"http://www.echatsoft.com/product.mp3",
        "fileSize":1024,
        "duration":6
		},
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "voice",
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.4 视频消息

对象	参数	参数类型	描述
	msgType	string	video
video	fileUrl	string	文件地址 最大长度显示：1024
	fileSize	number	文件大小(KB)
	fileName	string	文件名
	thumbUrl	string	视频缩略图url

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "video",
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"video": {
			"fileName": "2.mp4",
			"fileSize": 1147866,
			"fileUrl": "http://qnfile.echatsoft.com/1010b806-3b84-4344-ae4f-038760166e53"
		},
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.5 文件消息

对象	参数	参数类型	描述
	msgType	string	file
file	fileUrl	string	文件地址 最大长度显示：1024
	fileSize	number	文件大小(KB)
	fileName	string	文件名

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"file": {
			"fileName": "test.txt",
			"fileSize": 13828,
			"fileUrl": "http://qnfile.echatsoft.com/3339c3a8-5463-480d-b910-6c5d9fc780f3"
		},
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "file",
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.6 图文消息

对象	参数	参数类型	描述
	msgType	string	news
news	eventId	string	图文消息的ID，可自定义前缀或者其他格式来通知业务系统图文消息的消息类型：比如：prod-123 ,order-123等
	title	string	图文消息的标题，如：新款风衣
	content	string	图文消息的描述，只支持div span style属性，如：产品的价格，优化信息等
	imageUrl	string	图文消息的图片地址
	url	string	图文消息打开的url
	memo	string	图文消息的描述，如：产品评价等

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "news",
		"news": {
			"content": "<div style=\"color:#666;line-height:20px\">原价：<span style=\"text-decoration:line-through\">?414.99</span></div><div style=\"color:#666;line-height:20px\">促销：<span style=\"color:red\">?211.64</span></div><div style=\"color:#666;line-height:20px\">运费：<span style=\"color:#ccc\">卖家承担运费</span></div>",
			"eventId": "cook1005",
			"imageUrl": "http://pbow058q9.bkt.clouddn.com//e8//e8c60e6c9f619bd4/d4/94c20a4c2725995e.jpg",
			"memo": "评价（299）",
			"title": "2016秋冬新品复古欧式感大花苞袖宽松毛衣"
		},
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.7 地理位置消息

对象	参数	参数类型	描述
	msgType	string	location
location	locationX	string	维度
	locationY	string	经度
	scale	number	地图缩放大小
	label	string	地理位置信息 最大长度限制：100

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "location",
		"location": {
		"locationX":"30.535400",
        "locationY":"30.535400",
        "scale":"15",
        "label":"成都市武侯区天府三街新希望国际A座一洽客服研发中心"
		},
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.8 推送URL消息

对象	参数	参数类型	描述
	msgType	string	pushUrl
pushUrl	url	string	url
	content	string	文本内容

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "pushUrl",
		"pushUrl": {
			"content": "test",
			"url": "https://oa.rainbowred.com/index.html"
		},
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

2.9 列表消息

对象	参数	参数类型	描述
	msgType	string	listMsg
msgs		list	消息列表

接收消息示例：

{
    "mediaId":"EvmP3VQAPaIUa9SkYRv",
    "plainContent":{
        "mediaId":"EvmP3VQAPaIUa9SkYRv",
        "msgType":"listMsg",
        "msgs":[
            "{\"msgType\":\"text\",\"text\":{\"content\":\"祝您生活愉快，再见！\"}}",
            "{\"desc\":\"亲，对客服刚刚的服务还满意吗？快去给TA一个评价吧！点此评价哦~\",\"imageUrl\":\"http://chats.rainbowred.com/res/static/banner.png\",\"msgType\":\"evaluate\",\"title\":\"满意度评价\",\"url\":\"http://hospitals.loren.net/visitor/customer/evaluate/ChatEval.html?content=EcBrIlhvwLiQC%2FgY2yiP2RyhSra2t0ecH5cTtKLk8aiKBn%2BJFvkaOc1ESRpmCLB5%2FO0Isin1y%2FNIvEmPpcDQ%2BV4%2B85TcAszkiTAeKwnfQ4Tx68ljF95DvnRMqsS2AvJqHY8JRvBo67k%2FE6pEV4DRh9Dxpxq%2FFOT%2FBhAUqhJMGWjplSgVgzY0jmA3vo05gcl5%2F94MUsu5gPLq3898Tx7CPXpNumPzkiPS\"}"
        ],
        "userId":"2956171584499891",
        "userType":0,
        "visitorId":"custom2956171584499891"
    }
}

             

3 机器人回复消息

普通的机器人回复消息（比如提示语），会以文本消息的格式推送给开发者，此处主要是一些复杂消息。这些消息一洽都默认提供了content字段以供开发者直接使用，开发者也可以根据消息字段自行根据实际情况进行组装。

3.0 常用问题和欢迎语

对象	参数	参数类型	描述
	msgType	string	robotSimilarMatch
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	robotStyleId	number	机器人id
	robotName	string	机器人昵称
	content	string	开发者可以直接使用
	hint	string	精准匹配提示语
suggestions		list	相关问题列表
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	question	string	问题

接收消息示例：

{
	"content": "宝宝，我来了！请详细描述你要求助的问题，让我更好的帮助你哦！\n您是否遇到以下问题：\n[1] 配送时间\n[2] 怎么还没送到\n[3] 没收到货就显示签收了",
	"hint": "宝宝，我来了！请详细描述你要求助的问题，让我更好的帮助你哦！\n您是否遇到以下问题：",
	"mediaId": "SgmrqLefbIR8vLnS6CL",
	"msgType": "robotSimilarMatch",
	"suggestions": [{
		"knowledgeType": 1,
		"question": "配送时间"
	}, {
		"knowledgeType": 1,
		"question": "怎么还没送到"
	}, {
		"knowledgeType": 1,
		"question": "没收到货就显示签收了"
	}],
	"userId": "13666150888",
	"userType": 1,
	"visitorId": "webvip13666150888"
}
             

3.1 完全匹配

对象	参数	参数类型	描述
	msgType	string	robotAbsoluteMatch
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	robotStyleId	number	机器人id
	robotName	string	机器人昵称
	content	string	开发者可以直接使用
	feedBackHint	string	反馈提示语
	solvedFeedBack	string	已解决提示语
	unSolvedFeedBack	string	未解决提示语
	question	string	问题
	answer	string	答案
	guideHint	string	引导问题提示语
	relateHint	string	相关问题提示语
relateKnowledges		list	相关问题列表
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	question	string	问题

接收消息示例：

{
	"answer": "
包裹投递失败有以下两种情况：
1、快递未联系派送直接操作拒收包裹，请您联系客服核实具体情况的哦！
2、如果快递员多次无法联系上您导致无法配送，包裹将被返回，订单会显示“投递失败”状态哟，表示您的包裹已经在返回仓库的途中，我们将会在收到包裹的3天内办理退款哒。
",
	"answerMedia": 0,
	"content": "
包裹投递失败有以下两种情况：
1、快递未联系派送直接操作拒收包裹，请您联系客服核实具体情况的哦！
2、如果快递员多次无法联系上您导致无法配送，包裹将被返回，订单会显示“投递失败”状态哟，表示您的包裹已经在返回仓库的途中，我们将会在收到包裹的3天内办理退款哒。
\n\n您可能还想问：\n[1] 怎么还没送到\n[2] 没收到货就显示签收了\n[3] 包裹到哪了0\n\n以上内容是否对您有帮助？\n是\n否",
	"feedBackHint": "以上内容是否对您有帮助？",
	"knowledgeType": 1,
	"mediaId": "SgmrqLefbIR8vLnS6CL",
	"msgType": "robotAbsoluteMatch",
	"question": "为什么显示投递失败",
	"relateHint": "您可能还想问：",
	"relateKnowledges": [{
		"knowledgeType": 1,
		"question": "怎么还没送到"
	}, {
		"knowledgeType": 1,
		"question": "没收到货就显示签收了"
	}, {
		"knowledgeType": 1,
		"question": "包裹到哪了"
	}],
	"solvedFeedBack": "是",
	"unSolvedFeedBack": "否",
	"userId": "13666150888",
	"userType": 1,
	"visitorId": "webvip13666150888"
}
             

3.2 精准匹配

对象	参数	参数类型	描述
	msgType	string	robotAccurateMatch
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	robotStyleId	number	机器人id
	robotName	string	机器人昵称
	content	string	开发者可以直接使用
	feedBackHint	string	反馈提示语
	solvedFeedBack	string	已解决提示语
	unSolvedFeedBack	string	未解决提示语
	hint	string	精准匹配提示语
	question	string	问题
	answer	string	答案
	guideHint	string	引导问题提示语
	relateHint	string	相关问题提示语
relateKnowledges		list	相关问题列表
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	question	string	问题

接收消息示例：

{
	"answer": "
包裹投递失败有以下两种情况：
1、快递未联系派送直接操作拒收包裹，请您联系客服核实具体情况的哦！
2、如果快递员多次无法联系上您导致无法配送，包裹将被返回，订单会显示“投递失败”状态哟，表示您的包裹已经在返回仓库的途中，我们将会在收到包裹的3天内办理退款哒。
",
	"answerMedia": 0,
	"content": "
包裹投递失败有以下两种情况：
1、快递未联系派送直接操作拒收包裹，请您联系客服核实具体情况的哦！
2、如果快递员多次无法联系上您导致无法配送，包裹将被返回，订单会显示“投递失败”状态哟，表示您的包裹已经在返回仓库的途中，我们将会在收到包裹的3天内办理退款哒。
\n\n您可能还想问：\n[1] 怎么还没送到\n[2] 没收到货就显示签收了\n[3] 包裹到哪了0\n\n以上内容是否对您有帮助？\n是\n否",
	"feedBackHint": "以上内容是否对您有帮助？",
	"knowledgeType": 1,
	"mediaId": "SgmrqLefbIR8vLnS6CL",
	"msgType": "robotAccurateMatch",
	"question": "为什么显示投递失败",
	"relateHint": "您可能还想问：",
	"relateKnowledges": [{
		"knowledgeType": 1,
		"question": "怎么还没送到"
	}, {
		"knowledgeType": 1,
		"question": "没收到货就显示签收了"
	}, {
		"knowledgeType": 1,
		"question": "包裹到哪了"
	}],
	"solvedFeedBack": "是",
	"unSolvedFeedBack": "否",
	"userId": "13666150888",
	"userType": 1,
	"visitorId": "webvip13666150888"
}
             

3.3 相似匹配

对象	参数	参数类型	描述
	msgType	string	robotSimilarMatch
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	robotStyleId	number	机器人id
	robotName	string	机器人昵称
	content	string	开发者可以直接使用
	hint	string	精准匹配提示语
suggestions		list	相关问题列表
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	question	string	问题

接收消息示例：

{
	"content": "我猜您关心的问题是：\n[1] 为什么显示投递失败\n[2] 没收到货就显示签收了\n[3] 网站出现支付异常\n[4] 支付成功却显示未支付\n[5] 商品的价格为什么会变动",
	"hint": "我猜您关心的问题是：",
	"mediaId": "SgmrqLefbIR8vLnS6CL",
	"msgType": "robotSimilarMatch",
	"suggestions": [{
		"knowledgeType": 1,
		"question": "为什么显示投递失败"
	}, {
		"knowledgeType": 1,
		"question": "没收到货就显示签收了"
	}, {
		"knowledgeType": 1,
		"question": "网站出现支付异常"
	}, {
		"knowledgeType": 1,
		"question": "支付成功却显示未支付"
	}, {
		"knowledgeType": 1,
		"question": "商品的价格为什么会变动"
	}],
	"userId": "13666150888",
	"userType": 1,
	"visitorId": "webvip13666150888"
}
             

3.4 二级反馈

对象	参数	参数类型	描述
	msgType	string	robotFeedBackSubItem
	knowledgeType	number	知识类型，1=一般问题，2=引导问题
	robotStyleId	number	机器人id
	robotName	string	机器人昵称
	content	string	开发者可以直接使用
items		list	反馈项配置
	content	string	文本显示内容
	key	string	触发关键字

接收消息示例：

{
	"content": "a.aa\nb.bb",
	"items": [{
		"content": "aa",
		"key": "a"
	}, {
		"content": "bb",
		"key": "b"
	}],
	"mediaId": "EvmP3VQAPaIUa9SkYRv",
	"msgType": "robotFeedBackSubItem",
	"userId": "2956171584499891",
	"userType": 0,
	"visitorId": "custom2956171584499891"
}
             

4 一洽推送给开发者的消息

此类消息主要是一些状态消息，比如对话开始、对话结束等。

4.1 对话开始消息

参数	参数类型	描述
msgType	String	chatStarted
talkId	number	对话id
staffId	number	客服id，可能为-1，比如排队、机器人
startTime	number	对话开始时间

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"chatType": 1,
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "chatStarted",
		"staffId": 1556,
		"startTime": 1576224281474,
		"talkId": 4290650,
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

4.2 对话结束消息

参数	参数类型	描述
talkId	number	对话id
staffIds	number	客服id(转接的情况)
endReason	number	对话结束类型，客服结束、访客结束、超时结束
endTime	number	对话结束时间

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"endReason": 2,
		"endTime": 1576226847105,
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "chatEnded",
		"staffIds": [1556],
		"talkId": 4290650,
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

4.3 对话转接消息

参数	参数类型	描述
msgType	String	chatTransferred
talkId	number	对话id
fromStaffId	number	发起转接客服id
fromStaffName	number	接受转接客服id
toStaffId	number	接受转接客服id
toStaffName	string	接受转接客服姓名
transferTime	number	转接时间
content	string	转接备注

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
		"fromStaffId": 1556,
		"fromStaffName": "胡仲舜",
		"mediaId": "X9fxCTkxtu4pHngMw35",
		"msgType": "chatTransferred",
		"talkId": 4290846,
		"toStaffId": 5199,
		"toStaffName": "李荣",
		"transferTime": 1576227176006,
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1,
		"visitorId": "webvipoUb374g34wa34Wlp-0Wov6SJCmmg"
	}
}
             

4.4 对话评价消息

参数	参数类型	描述
msgType	String	chatEvaluated
title	String	评价消息的图文title
desc	String	评价消息的图文描述
imageUrl	string	评价内容
url	number	评价等级

接收消息示例：

{
	"mediaId": "X9fxCTkxtu4pHngMw35",
	"plainContent": {
        "msgType":"evaluate",
		"title":"满意度评价",
		"desc":""亲，对客服刚刚的服务还满意吗？快去给TA一个评价吧！点此评价哦~"",
		"imageUrl":"https://www.echatsoft.com/res/static/banner.png",
		"url":"http://www.echatsoft.com/visitor/customer/evaluate/ChatEval.html?content=EcBrIlhvwLiQC%2FgY2yiP2U2rpFioKHxPhAnDBhsp4k0UxX5m5JoxsCCWoSgv0f%2BoKDCTh6jExO9T%0AxX1QEd2aZDNbABPx0E2MprOfId8Ou37GmX7X%2Fi9c9se3yje5NrSJ0tvlg9NeBP%2BMMF1QFjXycQPU%0AhgDXPcQrEjKZ1%2BZl8VrGm1kt2eFoIOmVKBWDNjSOYDe%2BjTmByXnQzXGvEIQKuYqrcr9VtlnH9I77%0AW6UBEdE%3D",
		"userId": "oUb374g34wa34Wlp-0Wov6SJCmmg",
		"userType": 1
	}
}