自定义渠道接入

概要

在开发者需要操作对话状态以及需要将渠道消息发送给客服时，调用一洽提供给开发者的消息接收接口来将事件和消息发送给一洽服务器。接口调用只支持post方式。
获取一洽提供给当前渠道的消息接收地址：
示例地址：https://eapi.echatsoft.com/message/custom/send/media123

接口调用说明

http请求方式: POST
https://eapi.echatsoft.com/csm/service/123422/media123?access_token=${ACCESS_TOKEN}

post内容为事件消息和普通消息的json格式字符串。
接口调用成功后，一洽会在请求响应包中返回本次请求的结果。

参数	参数类型	描述
errorCode	string	错误码
errorMsg	string	错误描述
successful	boolean	请求是否成功

注：部分事件消息除了接口请求是否成功外，还需要回执对应的数据，这部分数据以result参数给出（比如获取访客排队信息）

消息定义

1. 基础参数

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

参数	参数类型	描述	是否必传
userId	string	访客ID，每个渠道下访客身份的唯一标识ID	是
userType	number	访客是否是会员 0:不是 1:是如果访客为会员访客，那么此访客在所有渠道包括web、sdk渠道来访时一洽会识别为一个访客	是
msgType	string	标识消息类型，每个消息有对应的固定msgType	是
userName	string	访客名称，如需更新访客的详细信息，请使用更新访客信息事件消息	否
echatTag	string	路由标签，注册对话会根据此参数进行路由	是
acdStaffId	int	指派接待客服的ID(使用指定客服，scdStaffId 和 acdType都需必传)	否
acdType	int	分配优先级，0-优先，1-指派优先：客服在路由分配的组中，则优先分配给该名客服（在线/忙碌），不计接待能力。若客服「不在组中」或「在组中且离线（离开/隐身）」，则按照现有规则ACD分配规则指派：只能由该客服进行服务。若客服「不在路由分配的组中」或「在组中且离线（离开/隐身）」，对话接待则进入下一个接待方式，留言/工单则直接按全部分组分配给该名客服	否
photo	string	访客头像	是
routeId	number	路由ID，直接指定路由，如果路由存在则会忽略echatTag参数	否
chatPolicy	string	本地请求对话的策略，设定可以接入的会话类型。此值为一个2进制字符串。"111" "101" 从右往左每一位代表会话类型为：人工对话（001）、机器对话（010）、留言（100）、一句话留言（000），默认值为"111"，1代表支持接入 0代表不支持接入。其中一句留言表示不论此时公司或访客处于何种状态，都会创建一个留言并且马上结束，如果携带了文本、图片等消息，则会作为留言内容(一句话留言没有欢迎语和结束语)	是

注：下面消息示例均不包含基础参数

2. 对话消息

对话消息在发送时，如果当前访客不存在会话（机器人对话、人工对话、留言会话），一洽会自动创建会话，然后将结果异步发送给开发者，开发者在收到会话状态消息后建议开发者保存访客的会话状态，在会话中时可以不再发送echatTag，routeId等信息
如果自定义渠道访客对话都是访客的消息触发的，则可直接发送消息给一洽。
如果自定义渠道访客对话时通过访客打开页面或者点击菜单等其他事件触发的，则可直接给一洽发送注册对话消息使其进入到会话状态。

2.1 文本消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"text",
    "text":{
        "content":"您好，请问一洽客服系统支持自定义渠道吗？。"
    }
}

2.2 图片消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"image",
    "image":{
        "picUrl":"https://www.echatsoft.com/wp-content/images/logo.png",
        "thumbUrl":"https://www.echatsoft.com/wp-content/images/logo.png"
    }
}

2.3 语音消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"voice",
    "voice":{
        "format":"mp3",
        "fileUrl":"http://www.echatsoft.com/product.mp3",
        "fileSize":1024,
        "duration":6
    }
}

2.4 视频消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"video",
    "video":{
        "fileUrl":"http://www.echatsoft.com/fileUrl",
        "fileSize":1024,
        "fileName":"测试文件.rar",
        "thumbUrl":"http://www.echatsoft.com/thumbUrl"
    }
}

2.5 文件消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"file",
    "file":{
        "fileUrl":"http://www.xxx.com/fileUrl",
        "fileName":"文件",
        "fileSize":1024
    }
}

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	图文消息的描述，如：产品评价等	否

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"news",
    "news":{
        "eventId":"eventId",
        "content":"在这里填写图文消息的内容在这里填写图文消息的内容在这里填写图文消息的内容",
        "imageUrl":"http://tfile.rainbowred.com/group1/M00/00/12/rBAKCFkifSKAa7stAAAQFFe-9nU432.jpg",
        "title":"这里是标题",
        "url":"http('http://m.echatsoft.com','inner')",
        "memo":"这里是备注"
    }
}

2.7 地理位置消息

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

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"location",
    "location":{
        "locationX":"30.535400",
        "locationY":"30.535400",
        "scale":"15",
        "label":"成都市武侯区天府三街新希望国际A座一洽客服研发中心"
    }
}

3. 事件消息

会话内容消息外的其他消息，比如注册对话、更新crm信息、结束对话、评价对话等，事件触发后执行结果会通过psot的方式推送给开发者的消息接收的url中。此部分消息收到后一洽会在response中通知开发者是否已经正常受理此事件，部分可能包含result数据（会在消息定义处说明）。

3.1 注册对话

如访客未发送任何消息需要触发对话开始，则发送此时间消息通知一洽主动建立对话，对话建立成功或者失败会异步返回给开发者对话开始或者接入失败消息。（通过post的方式post给开发者的消息接收url）

参数	参数类型	描述	是否必传
msgType	string	regChat	是

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "userName":"张三",
    "echatTag":"salesorder",
    "msgType":"regChat"
}

response回执示例：

{//成功

    "errorCode":"0",
    "successful":true
}

{//失败

    "errorCode":"403",
    "errorMsg":"visitor is chatting",
    "successful":false，
    "result":{
        "talkId":143243,
        "chatType":1,
        "startTime":1471122200000,
        "staffId":56
    }
}

3.2 结束对话

参数	参数类型	描述	是否必传
msgType	string	endChat	是
userId	string	用户id	是
userType	number	用户类型	是

请求消息示例：

{
"userId":"13666150888",
"userType":1,
"msgType":"endChat"
}

response回执示例：

{//成功

    "errorCode":"0",
    "successful":true
}

{//失败

    "errorCode":"231",
    "errorMsg":"talk is not exist",
    "successful":false
}

3.3 提交评价

对象	参数	参数类型	描述	是否必传
	msgType	string	commitEvaluate	是
	talkId	number	对话id	是
evaluate	mainItem	number	评价级别（1-5） 1:非常不满意 2：不满意 3：一般 4：满意 5：非常满意	是
	comment	string	评价内容最大长度限制：1024	否

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "msgType":"commitEvaluate",
    "evaluate":{
        "mainItem":5,
        "comment":"一洽客服系统真的很不错"
    }
}

response回执示例：

{//成功

    "errorCode":"0",
    "successful":true
}

{//失败

    "errorCode":"109",
    "errorMsg":"对话不存在",
    "successful":false
}

3.4 获取客户信息

参数	参数类型	描述	是否必传
msgType	string	getCrmInfo	是
userId	string	用户id	是
userType	number	用户类型	是

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "msgType":"getCrmInfo",
}

response回执示例：

{  
    "errorCode":"0",
    "successful":true
    "result":{
        "crm":{
            "name":"张三新",
            "phone":"13666150888",
            "c1":"vip客户"
        }
    }
}

3.5 更新客户信息

如果需要提交给客服除名字外更详细的客户信息，则在收到会话开始消息后（机器人对话、人工对话、留言对话），提交更新客户信息消息给一洽。

对象	参数	参数类型	描述	是否必传
crm	msgType	string	updateCrm	是
	grade	string	会员级别 >=0	否
	category	string	会员类别例如：金牌会员最长不超过50	否
	name	string	客户姓名例如：王宝强最长不超过50	否
	nickName	string	客户的昵称例如：宝宝最长不超过50	否
	gender	number	客户的性别，0-未知， 1-男， 2-女 >=0	否
	age	number	客户的年龄	否
	birthday	string	客户的生日例如：2015-08-01 格式yyyy-MM-dd	否
	maritalStatus	string	婚姻状况 1：未婚 2：已婚 0：未知 >=0	否
	phone	string	客户的联系电话最长不超过50	否
	qq	string	qq	否
	wechat	string	客户的微信最长不超过50	否
	email	string	客户的邮件地址最长不超过50	否
	nation	string	客户的国家最长不超过50	否
	province	string	客户的省份最长不超过50	否
	city	string	客户的城市最长不超过50	否
	address	string	客户地址最长不超过255	否
	photo	string	客户头像地址最长不超过255	否
	memo	string	客户备注信息最长不超过255	否
	c1-c20	string	客户自定义字段最长不超过255	否

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "msgType":"updateCrm",
    "crm":{
        "name":"张三新",
        "phone":"13666150888",
        "c1":"vip客户"
    }
}

3.6 获取排队信息

参数	参数类型	描述	是否必传
msgType	string	updateQueue	是
userId	string	用户id	是
userType	number	用户类型	是

请求消息示例：

{
    "userId":"13666150888",
    "userType":1,
    "msgType":"updateQueue"
}

response回执示例：

{
    "errorCode":"0",
    "successful":true,
    "result":{
        "talkId":13234,
        "position":12
    }
}

自定义渠道接入

概要

更多设置-开发API-自定义渠道接口-洽接收开发者消息的服务器地址

接口调用说明

消息定义

1. 基础参数

2. 对话消息

2.1 文本消息

2.2 图片消息

2.3 语音消息

2.4 视频消息

2.5 文件消息

2.6 图文消息

2.7 地理位置消息

3. 事件消息

3.1 注册对话

3.2 结束对话

3.3 提交评价

3.4 获取客户信息

3.5 更新客户信息

3.6 获取排队信息