JS API接入说明

一洽对外提供JS API功能，网站接入时可以注入 echat.js 按需求使用 比如网站自定义的按钮使用 js 方法打开对话、监听对话状态、设置未读消息等

1、页内打开对话

调用方法：ECHAT.customMiniChat(customObj)

customObj 参数格式 为JSON对象
示例：ECHAT.customMiniChat({'echatTag':'order'})

描述：打开一个页内对话窗口，在当前网页中建立一个 iframe 打开对话。
 

pc网页端效果图

手机网页端效果图

 

2、弹窗打开对话

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

pc网页端效果图

 

3、新窗口打开对话

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

pc网页端效果图

 

4、刷新访客的会员身份

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

参数介绍：

属性名	类型	必须	描述	encode
metaData	String	是	当前登录会员的 metaData 信息，详细请查看 会员信息	否
myData	String	否	自定义参数	否

 

5、获取对话窗口地址

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

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

http://es.echatsoft.com/visitor/pc/chat.html?companyId=1&encryptVID=MlpBrdy+fs8d7XyLvYZF9g==&chatVisitorId=24092361&enterUrl=http://www.echatsoft.com/&enterTitle=一洽客服Echat|专业的电商行业在线客服系统软件和解决方案提供商&firstUrl=http://www.echatsoft.com/&firstTitle=一洽客服Echat|专业的电商行业在线客服系统软件和解决方案提供商&referrer=https://www.baidu.com/link?url=4mToafSCGt-JnuEkpTsHDFxaWjY5XSACzLIjJ18ykDN43f_tuVplNBHiDhp9dopU&wd=&eqid=a595df79000032d50000000559228aac&fromHost=http://www.echatsoft.com&dataHost=http://e.echatsoft.com

 

6、获取访客Id

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

 

7、设置页面标题

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

 

8、页内对话窗口最小化-最大化

页内对话窗口最小化

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

页内对话窗口最大化

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

 

9、结束对话

调用方法：ECHAT.closeMiniChat(closeParam)
描述：如果您使用页内的对话窗口进行对话，需要手动关闭对话可调用此方法，
closeParam 传入格式为 json
directClose = 1 则直接结束对话（跳过弹窗确认,执行点击确认的操作）
不传 closeParam 默认需要弹窗确认,执行点击确认关闭对话的操作
示例：ECHAT.closeMiniChat({'directClose':1})

 

10、设置手机窗口半屏展示

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

 

11、获取内页窗口的打开状态

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

 

12、获取对话状态

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

 

13、获取对话客服信息

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

 

14、获取访客的未读消息数

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

 

15、设置PC内页窗口大小以及位置

用法：引入js时进行设置
设置参数名称：pcMiniWinParam
设置参数值：json对象

key	类型	解释
left	int	左边距 不设置则使用样式配置。不为0 则会显示在左侧 优先级高于 right
right	int	右边距 不设置则使用样式配置 不为0 则会显示在右侧
bottom	int	底边距 不设置则使用样式配置
min	boolean	是否显示最小化按钮 不设置则使用样式配置
max	boolean	是否显示最大化按钮 不设置则使用样式配置
close	boolean	是否显示关闭按钮 不设置则使用样式配置
width	int	窗口宽度 不设置则使用样式配置
height	int	窗口高度 不设置则使用样式配置

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);

 

16、发送文本消息

调用方法：ECHAT.sendTextMsg(text)
描述：调用此方法可以实现开发者发送文本消息到对话中

 

17、发送卡片消息

调用方法：ECHAT.pushVisitorEvent(visEvt)
描述：如果访客在对话的过程中需要将指定的订单或者商品以图文卡片信息推送给客服，可以使用此方法

 

18、监听对话事件

echatjs加载完成后可注册事件接收，实现自定义对话的部分高级效果
1.在自定义图标上显示当前页面未读取的新消息数量
注意：如果会员对话，需要在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: #{companyId}});_echat('initParam', {metaData : #{companyId}}); //会员对话，需要js中传入metaData,确保监听到对应会员数据(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) {//一洽新消息数量}});
</script>