自定义渠道接入

前言

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

参数 参数类型 描述
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
	}
}