概要

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

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

api配置

接口调用说明

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 路由标签,注册对话会根据此参数进行路由
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
    }
}