18000

一洽客服系统访客端API

目录

1. 使用场景

2. 新窗口打开对话

3. window.open打开对话窗口

4. 页内打开对话窗口

5. 刷新访客的会员身份

6. 发送图文消息

7. 获取对话窗口地址

8. 获取访客的ID

9. 设置页面标题

10. 页内对话窗口最小化

11. 内页对话窗口最大化

12. 结束对话

13. 监听访客事件

14. 设置手机窗口半屏展示

15. 获取内页窗口的打开状态

16. 获取对话状态

17. 获取对话客服信息

18. 获取访客的未读消息数

19. 设置PC内页窗口大小以及位置

20. 获取上传文件凭证

1.使用场景

在加载有echat.js的页面才能调用js sdk提供的API。您可以根据自己的业务需要来选择使用API完成特定的业务逻辑，比如：需要手动控制打开对话窗口的参数和图标的位置

2.window.open打开对话窗口

调用方法：ECHAT.customNewWinChat(customObj)
描述：使用window.open打开一个对话窗口，应用于PC站点，手机站点不建议使用此方法，因为手机端没有弹出窗口的概念，使用后会在新窗口打开对话。
效果图：
PC：

参数介绍：
customObj为json对象，json各属性描述如下：

注：以下所有参数均支持在echat.js加载时通过initParam设置，以及直接传参给对话窗口链接。详见下方的示例。

chatWindowParam 各属性描述：

visEvt图文消各属性描述

图文消息效果图示如下：

打开效果：

示例一(通过echat.js初始化对话窗口参数)：

示例代码：

    var _echatServer = ['v.rainbowred.com'];
    window._echat = window._echat || function () {
        (_echat.q = _echat.q || []).push(arguments)
    };
    _echat.l = +new Date;
    _echat('initParam', {companyId: 12191});

    var chatParamObj = {};
    var pageVisEvt = {
        eventId: "prod-12617",
        title: "这是一条来自api文档的测试图文消息",
        content: "原价：¥100.00",
        imageUrl: "http://saastest.innourl.com/images/ADIDAS/201707/thumb_img/10124_thumb_G_1499411207663.jpg"
    };
    chatParamObj.visEvt = pageVisEvt;
    chatParamObj.echatTag = "商品测试";
    chatParamObj.lan = "zh";
    var chatWindowParam = { maxWidth: 900, maxHeight: 600, bgColor: "#000000" ,bgImage:"http://qnfile.echatsoft.com/a2abc059-1cce-4358-b091-b3292d769aca",bgRepeat:1,name:"echatChatWindow",width:1000,height:700};
    chatParamObj.chatWindowParam = chatWindowParam;
    _echat('initParam', chatParamObj);
    (function () {
        var echat = document.createElement('script');
        echat.type = 'text/javascript';
        echat.async = true;
        echat.id = 'echatmodulejs';
        echat.setAttribute('charset', 'UTF-8');
        echat.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'www.echatsoft.com/visitor/echat.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(echat, s);
    })();

示例二(通过方法调用打开)：

    var chatParamObj = {};
    var pageVisEvt = {
        eventId: "prod-12617",
        title: "这是一条来自api文档的测试图文消息",
        content: "原价：¥100.00",
        imageUrl: "http://saastest.innourl.com/images/ADIDAS/201707/thumb_img/10124_thumb_G_1499411207663.jpg"
    };
    chatParamObj.visEvt = pageVisEvt;
    chatParamObj.echatTag = "商品测试";
    chatParamObj.lan = "zh";
    var chatWindowParam = { maxWidth: 900, maxHeight: 600, bgColor: "#000000" ,bgImage:"http://qnfile.echatsoft.com/a2abc059-1cce-4358-b091-b3292d769aca",bgRepeat:1,name:"echatChatWindow",width:1000,height:700};
    chatParamObj.chatWindowParam = chatWindowParam;
    ECHAT.customNewWinChat(chatParamObj);

示例三(通过追加对话地址参数打开。不需要echat.js时使用此方法)：

var chatLink = 'https://www.echatsoft.com/visitor/pc/chat.html?companyId=12191';
var pageVisEvt = {
        eventId: "prod-12617",
        title: "这是一条来自api文档的测试图文消息",
        content: "原价：¥100.00",
        imageUrl: "http://saastest.innourl.com/images/ADIDAS/201707/thumb_img/10124_thumb_G_1499411207663.jpg"
    };
var chatWindowParam = { maxWidth: 900, maxHeight: 600, bgColor: "#000000" ,bgImage:"http://qnfile.echatsoft.com/a2abc059-1cce-4358-b091-b3292d769aca",bgRepeat:1,name:"echatChatWindow",width:1000,height:700};
chatLink += '&echatTag='+encodeURIComponent('商品咨询');
chatLink += '&lan='+encodeURIComponent('zh');
chatLink += '&visEvt='+encodeURIComponent(JSON.stringify(pageVisEvt));
chatLink += '&chatWindowParam='+encodeURIComponent(JSON.stringify(chatWindowParam));
window.open(chatLink);

3.新窗口打开对话

调用方法：ECHAT.customOpenChat(customObj)
描述：新页面打开对话窗口，此方法多应用在PC站点中，调用此方法后会在新标签页打开一个一洽对话，不建议在手机端使用此方法，因为新窗口打开后返回上一页会销毁当前的对话窗口。
效果图：
PC：

参数介绍：
请参见页新窗口对话窗口的参数描述。

4.页内打开对话窗口

调用方法：ECHAT.customMiniChat(customObj)
描述：打开一个页内对话窗口，在当前网页中建立一个iframe打开对话。
效果图：
PC：

手机：

参数介绍：
请参见页新窗口对话窗口的参数描述。

5.刷新访客的会员身份

调用方法：ECHAT.refreshVisitorMetaData(metaData,myData)
描述：如果当前访客在已经对话的过程中进行了登录，那么可以使用此方法刷新访客的会员身份

参数介绍：

6.发送图文消息

方法1：ECHAT.pushVisitorEvent(visEvt)
方法2：对话窗口直接传参:visEvt,参数值为图文消息的json字符串
描述：如果访客在对话的过程中需要选择了某个需要制定的订单或者商品可以试用此方法以图文消息的形式发送给客服,visEvt为json对象。

参数介绍请参考打开页内对话窗口中的图文消息参数描述

7.获取对话窗口地址

调用方法：ECHAT.getChatPageUrl()
描述：如果使用了自定义图标自定义方法通过对话窗口打开链接打开对话窗口，可通过此方法获取echat默认的打开窗口地址，然后根据自己需要追加不同的参数，使用一洽提供的默认对话窗口地址可自动追加对话的打开页面地址、来源信息到对话窗口地址中，同时会将访客的身份追加到参数中，在访客浏览器不支持cookie时保证浏览访客和对话访客的身份一致。

例如通过百度搜索一洽客服进入一洽的官网，获取到的对话窗口地址如下：

http://es.echatsoft.com/visitor/pc/chat.html?companyId=1&encryptVID=MlpBrdy%2Bfs8d7XyLvYZF9g%3D%3D&chatVisitorId=24092361&enterUrl=http%3A%2F%2Fwww.echatsoft.com%2F&enterTitle=一洽客服Echat%7C专业的电商行业在线客服系统软件和解决方案提供商&firstUrl=http%3A%2F%2Fwww.echatsoft.com%2F&firstTitle=一洽客服Echat%7C专业的电商行业在线客服系统软件和解决方案提供商&referrer=https%3A%2F%2Fwww.baidu.com%2Flink%3Furl%3D4mToafSCGt-JnuEkpTsHDFxaWjY5XSACzLIjJ18ykDN43f_tuVplNBHiDhp9dopU%26wd%3D%26eqid%3Da595df79000032d50000000559228aac&fromHost=http://www.echatsoft.com&dataHost=http%3A%2F%2Fe.echatsoft.com

8.获取访客的ID

调用方法：ECHAT.getEchatVisitorId()
描述：获取当前访客在一洽的身份ID，如果需要结合对话业务的数据和页面操作的其他数据做深入的分析，可以通过此id将对话的业务数据和自己业务系统的数据做对应。

9.设置页面标题

调用方法：ECHAT.setPageTitle(title)
描述：一洽在获取到新消息时会变化对话所在页面的title来提示访客有新消息，如果当前页面的title会动态变化，那么一洽不会实时获取页面的title，需要在页面title变化后通知一洽。
比如对话时页面的title为:订单详细信息 此时新消息提示会将标题设置为 “订单详情信息” “您有新消息” 两者之间切换。
如果由于某种业务操作，页面的标题在对话过程中设置为了“我的订单” 那么一洽不会使用此标题切换，需要开发者手动通知一洽变更后的标题。

10.页内对话窗口最小化

调用方法：ECHAT.hideMiniChat()
描述：如果您使用页内的对话窗口进行对话，需要手动将一洽的对话窗口最小化可调用此方法。

11.内页对话窗口最大化

调用方法：ECHAT.maxMiniChat()
描述：如果您使用页内的对话窗口进行对话，需要手动将一洽的对话窗口最大化弹出，仅在PC端有效。

12.结束对话

调用方法：ECHAT.closeMiniChat()
描述：如果您使用页内的对话窗口进行对话，需要手动关闭对话可调用此方法，调用此方法后如果对话结束需要评价，则会停留在对话评价页面，评价完成后对话窗口隐藏。

13.监听访客事件

echatjs加载完成后可注册事件接收，实现自定义访客接入的部分高级效果
如：
1.在自定义图标上显示当前页面未读取的新消息数量
2.获取到新消息的内容，可自定义提示效果
3.获取到对话业务的相关数据提交到自己已有的数据分析 如：google analytics

注册监听事件必须在echat.js加载完成

示例：

<script type="text/javascript">
    var _echatServer = ['e.echatsoft.com'];
    window._echat=window._echat||function(){(_echat.q=_echat.q||[]).push(arguments)};_echat.l=+new Date;
    _echat('initParam', { companyId: 1});
    (function () {
        var echat = document.createElement('script');
        echat.type = 'text/javascript';
        echat.async = true;
        echat.id = 'echatmodulejs';
        echat.setAttribute('charset','UTF-8');
        echat.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'es.echatsoft.com/visitor/echat.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(echat, s);
    })();
_echat('on',{
        ready: function () {
            //一洽配置加载完成
        },
        newMsg: function (num) {
            //一洽新消息数量
        },
        newEvent: function (data) {
            //一洽事件消息
        }
    });
</script>

13.1监听新消息数量
注册：newMsg:function(num){}
描述：num为当前页面在对话过程中客服或者是系统发送给访客的新消息数量，可在自定义图标位置显示角标
13.2监听一洽访客事件
注册：newEvent: function (event) {}
描述：如果使用页内窗口对话，可通过时间接收，接收到所有的对话事件。如果您是通过新窗口打开了对话那么对话事件中的新消息和评价事件则收不到。
参数描述：event为json对象 属性描述如下：

下面是每一类事件的详细介绍

eventCategory == 'echat' 分类的事件列表：

visitorSendMsg-文本消息：

{
    "msgType":"text",
    "textContent":"文本消息内容"
}

visitorSendMsg-文件消息：

{
    "msgType":"file",
    "fileName":"在线客服解决方案.pdf",
    "fileUrl":"https://www.echatsoft.com/file/a.pdf",
    "fileType":0,
    "fileSize":5210000
}

visitorSendMsg-图片消息：

{
    "msgType":"image",
    "smallImg":"https://www.echatsoft.com/visitormsg/smallImg.png",
    "bigImg":"https://www.echatsoft.com/visitormsg/bigImg.png",
    "sourceImg":"https://www.echatsoft.com/visitormsg/sourceImg.png"
}

visitorSendMsg-提交表单：

{
    "msgType":"formData",
    "formName":"在线客服需求收集表",
    "formId":2345
}

visitorSendMsg-json字段解释

访客基础浏览信息json字段解释

示例：

{
    "city":"成都市",
    "country":"中国",
    "firstUrl":"https://www.echatsoft.com/",
    "keyword":"一洽客服系统",
    "province":"四川省",
    "referrer":"https://www.baidu.com/link?url=OJ_GV4co3VzFIsx3LMbh7M1std23sPTEC0DYtUKWUGtuKol3M38YtqbdqSuZBtkG&wd=&eqid=f4ca1bee0004c8e4000000065f10124c",
    "keywordType":2,
    "searcher":"baidu"
}

平台客户新消息json字段解释：
示例：

{
    "chatUrl":"https://ps.echatsoft.com/visitor/mobile/chat.html?companyId=500029&platformSign=3rfef3ffsfsdwerwjljl",
    "companyId":"500029",
    "companyLogo":"http://pffile.echatsoft.com/group1/M00/00/00/wKgcPFzae_uAA112AAAZUUyrnC0829.png",
    "companyName":"Nike旗舰店",
    "msgContent":"[图片]",
    "msgId":"123321",
    "unreadMsgCount":5
}

页面状态json字段解释：

示例：

{
    "act":100,
    "eventAction":"echatPageStatus",
    "eventLabel":{
        "event":7,
        "eventValue":{
            "companyId":1,
            "companyName":"一洽客服系统"
        }
    },
    "eventCategory":"echat"
}

eventCategory == 'analytics' 分类的事件列表：
此部分事件推送为了方便用户将对话的数据提交给google analytics，如果您也需要将对话的时间提交给google analtyics的话那么请将https://es.echatsoft.com/visitor/echatDataPlugin.js 通echat.js一同加入到您的网站上，一洽会自动识别ga账号并向ga提交对话相关的数据。注：此部分只有在您使用内页对话窗口是才会统计到可靠的数据。
一洽向google提交的eventCategory为：Echat LiveChat

14.设置手机窗口半屏展示

用法：ECHAT.setMobilePageTop(top)
描述：如果希望手机在打开内页窗口时，不覆盖整个屏幕，可使用此方法设置手机内页窗口打开时距离顶部的距离，单位PX。
例如:
ECHAT.setMobilePageTop(150);

15.获取内页窗口的打开状态

用法：ECHAT.getMiniStatus()
描述：通过此方法可判断当前内页窗口是打开状态还是关闭状态，可自定义主动弹开对话窗口的规则。
返回值：
close:内页窗口关闭状态
open:内页窗口打开状态

16.获取对话状态

用法：ECHAT.getChatStatus()
描述：通过此方法可获取当前访客的对话状态。
返回值：
0:不存下对话或者留言
1:请求对话中
2:对话中
3:对话窗口数量过多
4:对话已结束

17.获取对话客服信息

用法：ECHAT.getChatStaffInfo()
描述：通过此方法可获取当前访客正在对话的客服信息。
返回值：
如果正在与客服对话则返回对话客服的信息（json）
staffId:客服ID
staffNickName:客服的对外昵称
staffPhone:客服的对外电话
staffHead:客服的对外头像
staffInfo:客服的对外信息介绍
如果没有对话的客服则返回空

18.获取访客的未读消息数

用法：ECHAT.getUnReadMsgCount()
描述：未读消息数量包括对话开始前客服回复访客的留言数量、给发送发送的推送消息数量、以及对话过程中产生的新的未读对话消息数量
返回值：>=0 的整数

19.设置PC内页窗口大小以及位置

用法：
引入js时进行设置（推荐）
ECHAT.customMiniChat调用时指定（不推荐）
描述：
设置参数名称：pcMiniWinParam
设置参数值：json对象

示例：

    var _echatServer = ['e.echatsoft.com'];
    window._echat=window._echat||function(){(_echat.q=_echat.q||[]).push(arguments)};_echat.l=+new Date;
    _echat('initParam', { companyId: 1});
    var pcMiniWinParam = {};
    pcMiniWinParam.left = 20;
    pcMiniWinParam.bottom = 20;
    pcMiniWinParam.min = true;
    pcMiniWinParam.max = true;
    pcMiniWinParam.close = false;
    pcMiniWinParam.width = 320;
    pcMiniWinParam.height = 450;
    _echat('initParam', { pcMiniWinParam:pcMiniWinParam});
    (function () {
        var echat = document.createElement('script');
        echat.type = 'text/javascript';
        echat.async = true;
        echat.id = 'echatmodulejs';
        echat.setAttribute('charset','UTF-8');
        echat.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'es.echatsoft.com/visitor/echat.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(echat, s);

20.获取上传文件凭证

用法：ECHAT.getFileUploadInfo()
描述：需要在一洽的对话窗口外上传文件给客服时，使用此方法获取上传文件的详细然后对其进行上传，上传后可直接传给客服。
上传凭证信息以及详细使用说明请见上传文件接口：