← 返回

JavaScript 网站插件

关于美洽 2016 JavaScript 网站插件,以及通过链接直接打开的单页美洽对话窗口的接口说明。

手动初始化

在加载了美洽网站插件的前提下,你可以在自己的 JavaScript 中通过调用 _MEIQIA('init') 来实现手动初始化。

使用方法如下:

  1. 在美洽的嵌入代码后加入 _MEIQIA('manualInit'); ,这个设置将会阻止美洽插件代码在下载完毕后自动执行初始化操作。
  2. 当你需要初始化美洽插件的时候,在 JavaScript 代码中调用 _MEIQIA('init') 即可。

注意:

示例:

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 在这里开启手动模式(必须紧跟美洽的嵌入代码)
    _MEIQIA('manualInit');
</script>
<!-- 这是你自己的 JavaScript 代码 -->
<script>
    // 你可以自己的代码中选择合适的时机来调用手动初始化
    _MEIQIA('init');
</script>

<!-- 在实际使用时你可能会面临很复杂的场景,但是沿着这个套路发挥吧。May force
 be with you -->

不使用美洽的聊天按钮

有时候,也许你不想要显示美洽自带的聊天按钮,那么你可以使用 _MEIQIA('withoutBtn');

注意:

示例:

<!-- 这是美洽的嵌入代码 -->
<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 在这里开启无按钮模式(常规情况下,需要紧跟在美洽嵌入代码之后)
    _MEIQIA('withoutBtn');
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 withoutBtn
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('withoutBtn');
    _MEIQIA('init');
</script>

初始化成功时的回调

有时候,也许你需要在美洽网站插件加载成功后执行一些事件,那么可以使用 _MEIQIA('allSet', callback)

注意:

示例:

<!-- 这是你的代码 -->
<script type='text/javascript'>
    function yourFunction() {
        // 你可以根据自己的需求编写相应的代码
        console.log('美洽网站插件初始化完毕。');
    }
</script>
<!-- 这是美洽的嵌入代码 -->
<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 初始化成功时的回调
    _MEIQIA('allSet', yourFunction);
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 allSet
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('allSet', yourFunction);
    _MEIQIA('init');
</script>

如果你想在初始化成功时获知客服的在线状态,那么可以为你编写的 callback 函数添加一个参数,美洽插件在调用它时,会返回当前的客服状态。

示例:

<!-- 我直接扩展上边例子中写的 yourFunction -->
<script type='text/javascript'>
    /**
     * [yourFunction]
     * @param {boolean} servability [true: 有客服在线, false: 无客服在线]
     */
    function yourFunction(servability) {
        // 你可以根据自己的需求编写相应的代码
        console.log('美洽网站插件初始化完毕。');

        if (servability) {
            console.log('有客服在线');
        } else {
            console.log('无客服在线');
        }
    }
</script>

强制对话

如果你想让美洽加载成功后直接打开聊天窗口可以如下设置:

示例:

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 初始化成功后调用美洽 showPanel
    _MEIQIA('allSet', function(){
      _MEIQIA('showPanel');
    });
</script>

会话开始时的回调

示例:
html
<!-- 这是你的代码 -->
<script type='text/javascript'>
function handleStart() {
console.log('会话开始回调')
}
</script>

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    //会话开始时的回调
    _MEIQIA('startConversation',handleStart)
</script>

会话结束时的回调

示例:
html
<!-- 这是你的代码 -->
<script type='text/javascript'>
function handleEnd() {
console.log('会话开始回调')
}
</script>

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    //会话结束时的回调
    _MEIQIA('endConversation',handleEnd)
</script>

英文版

示例:

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    //如果需要英文版,可用如下配置
    _MEIQIA('language','en')
</script>

错误:
/standalone.html?_=t&eid=我是企业ID&language=EN
```

打开聊天窗

在某些需求下,你可能希望在自己编写的代码中掌控美洽聊天窗。

在美洽网站插件初始化成功的前提下,调用 _MEIQIA('showPanel') 就可以打开美洽聊天窗。

注意:

示例:

<!-- 你可以直接在 HTML 元素中绑定 showPanel -->
<a href="javascript:void(0)" onclick="_MEIQIA('showPanel')">联系客服</a>

<!-- 当然也可以在 Javascript 中调用 -->
<script>
    _MEIQIA('showPanel');
</script>

如果你想要在调用聊天窗时指定客服或客服组,只需要添加相应的参数即可。

注意:

示例:

<!-- HTML -->
<a href="javascript:void(0)" onclick="_MEIQIA('showPanel', {agentToken:
 '客服智子的 Token'})">联系客服-智子</a>

<!-- Javascript -->
<script>
    // 指定客服
    _MEIQIA('showPanel', {
        agentToken: '客服智子的 Token'
    });

    // 指定客服组
    _MEIQIA('showPanel', {
        groupToken: '客服组的 Token'
    });

    // 如果你同时传递了 agentToken 和 groupToken
    // 那么 groupToken 将被忽略
    _MEIQIA('showPanel', {
        agentToken: '客服智子的 Token', // 只有我会起作用
        groupToken: '客服组的 Token' // 我被抛弃了
    });
</script>

隐藏聊天窗

在美洽网站插件初始化成功的前提下,调用 _MEIQIA('hidePanel') 就可以隐藏美洽聊天窗。

示例:

<!-- HTML -->
<button onclick="_MEIQIA('hidePanel')">隐藏窗口</button>

<!-- Javascript -->
<script>
    _MEIQIA('hidePanel');
</script>

通过配置指定分配客服或客服组

某些情况下,你可能希望直接以配置的形式来指定要分配的客服或客服组,那么你可以使用 _MEIQIA('assign', {})

assign 配置对美洽自带按钮和「打开聊天窗」接口都生效,但是当「打开聊天窗」接口本身携带了客服信息时,就会忽略 assign 的配置。

注意:

示例:

<script>
    // 指定客服
    _MEIQIA('assign', {
        agentToken: '客服智子的 Token'
    });

    // 指定多个客服
    _MEIQIA('assign', {
        agentToken: 'Token1,Token2,Token3'
    });

    // 指定客服组
    _MEIQIA('assign', {
        groupToken: '客服组的 Token'
    });

    // 如果你同时传递了 agentToken 和 groupToken
    // 那么 groupToken 将被忽略
    _MEIQIA('assign', {
        agentToken: '客服智子的 Token', // 只有我会起作用
        groupToken: '客服组的 Token' // 我被抛弃了
    });
</script>

传递顾客信息

在美洽工作台中,你可以手动为对话中的顾客添加个人信息,而通过 _MEIQIA('metadata', {}) 接口,可以将这个工作自动化。

美洽默认的顾客个人信息包括:

address // 地址
age // 年龄
comment // 备注
email // 邮箱
gender // 性别
name // 名字
qq // QQ
tel // 电话
weibo // 微博
weixin // 微信

注意:

示例:

<!-- 这是你的代码 -->
<script type='text/javascript'>
    /**
     * [在顾客访问你的网站期间,当他触发了某些特定事件时,你可以即时的调整顾客信息]
     * [假设 doSomething 是你用来处理某个特定事件的函数]
     */
    function doSomething () {
        // 传递顾客信息
        _MEIQIA('metadata', {
            action: '触发了 doSomething'
        });
    }
</script>
<!-- 这是美洽的嵌入代码 -->
<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 传递顾客信息
    _MEIQIA('metadata', {
        name: '智子', // 美洽默认字段
        address: '半人马座阿尔法星', // 美洽默认字段
        aaa: 'bla bla bla', // 自定义字段
        xyz: 'lalala' // 自定义字段
    });
</script>

在美洽工作台中,上方传入的数据将以如下形式分类呈现:

获取未读消息

美洽官方的聊天按钮可以显示未读消息的数量,以及提供最近一条未读消息的预览。

如果你设置了无按钮模式,这两个数据也就无法被呈现了。但是通过 _MEIQIA('getUnreadMsg', callback); 接口,你可以从 callback 的参数中得到这些数据,用自己的方式在显示它们。

注意:

示例:

<div>
    <div>我的数据来自未读消息接口</div>
    <div>未读消息数量: <b id="unreadNum">0</b></div>
    <div>最后一条未读消息的内容:<b id="unreadMsg"></b></div>
</div>

<!-- 这是一个简单的处理未读消息的示例 -->
<script>
    /**
     * [处理未读消息]
     * @param  {[string, object]} msg [string: 'hasBeenRead',
 object: 未读消息数据]
     */
    function yourFunction(msg) {
        var text = '',
            num = 0;
        if (msg === 'hasBeenRead') { // 消息已被阅读
            num = 0;
        } else if (typeof(msg) === 'object') {
            var unreadNum = document.getElementById('unreadNum').innerHTML,
                lastMsg = msg[msg.length - 1];
            num = isNaN(+unreadNum) ? msg.length : +unreadNum + msg.length;
            // content_type 是消息的类型:
            // text(文字)、photo(图片)、file(文件)
            // content 是消息的内容
            if (lastMsg.content_type === 'text') {
                // 文字消息中可能会存在表情图片,由于路径问题
                // 将文字消息中的图片处理为文字'[表情]'
                text = lastMsg.content.replace(
                    /<img [^>]*src=['"]([^'"]+)[^>]*>/gi, '[表情]'
                );
            } else if (lastMsg.content_type === 'photo') {
                text = '[图片]';
            } else if (lastMsg.content_type === 'file') {
                text = '[文件]';
            } else {
                text = '[新消息]';
            }
        }
        // 未读消息数量
        document.getElementById('unreadNum').innerHTML = num;
        // 最后一条消息的内容
        document.getElementById('unreadMsg').innerHTML = text;
    }
</script>

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 获取未读消息
    _MEIQIA('getUnreadMsg', yourFunction);
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 getUnreadMsg
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('getUnreadMsg', yourFunction);
    _MEIQIA('init');
</script>

获取邀请事件

如果你不想使用美洽提供的邀请弹窗,那么可以用 _MEIQIA('getInviting', callback); 来获取邀请事件,然后编写自己喜欢的弹窗。

注意:

示例:

<!-- 这是一个简单的处理邀请事件的示例 -->
<script>
    /**
     * [处理邀请事件]
     * @param  {string} agentToken [发出邀请的客服的 token]
     */
    function yourFunction(agentToken) {
        // 你可以在这里面调用你自己编写的邀请窗口
        // 当顾客接受邀请时,你只需要使用下面的方法,即可成功响应邀请

        //「打开聊天窗」接口
        _MEIQIA('showPanel', {
            agentToken: agentToken
        });
    }
</script>

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 获取邀请事件
    _MEIQIA('getInviting', yourFunction);
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 getInviting
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('getInviting', yourFunction);
    _MEIQIA('init');
</script>

拒绝邀请

当你使用「获取邀请事件」接口时,可以用 _MEIQIA('rejectInvitation') 在自己编写的弹窗中触发美洽的拒绝邀请事件。

注意:

示例:

<script>
    /**
     * [你自己编写的拒绝邀请函数]
     */
    function yourFunction() {
        // 你可以先执行自己的逻辑代码
        // 在适当的时机调用一下美洽的拒绝邀请接口即可
        _MEIQIA('rejectInvitation');
    }
</script>

获取聊天窗口可见性

如果你想在美洽聊天窗口显示或隐藏时处理一些自己的事件,那么可以使用
_MEIQIA('getPanelVisibility', callback)` 来获取聊天窗口可见性。

比如你编写了自己的聊天按钮,想在美洽聊天窗口显示时隐藏聊天按钮(反之亦然),那么这个接口可以帮助你实现需求。

注意:

示例:

<!-- 你需要根据实际情况编写你自己的处理函数 -->
<script>
    /**
     * [根据聊天窗口的可见状态执行相应的事件]
     * @param  {string} visibility [聊天窗口的可见状态,visible || invisible]
     */
    function yourFunction(visibility) {
        if (visibility === 'visible') {
            console.log('聊天窗口处于显示状态');
        } else {
            console.log('聊天窗口处于隐藏状态');
        }
    }
</script>

<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 获取聊天窗口可见性
    _MEIQIA('getPanelVisibility', yourFunction);
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时
    // 就可以在自己的逻辑中选择合适的时机调用 getPanelVisibility
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('getPanelVisibility', yourFunction);
    _MEIQIA('init');
</script>

设置当指定客服不可服务时如何处理

当你指定的客服不在线或无法服务时,可以通过在美洽嵌入代码之后设置 _MEIQIA('fallback', 1); 来指定不同的处理方式。

fallback 接受的参数为数字类型,目前有 1、2、3

1 // 不转接(进入留言也面)
2 // 转接到客服所属于的组
3 // 转接到全企业(这是美洽默认的处理方式)

注意:

示例:

<!-- 这是美洽的嵌入代码 -->
<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 设置 fallback
    _MEIQIA('fallback', 1);
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 fallback
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('fallback', 1);
    _MEIQIA('init');
</script>

同步顾客身份

如果你的产品有多种形式(网页、APP),且都使用了美洽,那么可以使用 _MEIQIA('clientId', '顾客的唯一标识') 来同步顾客的身份(包括顾客信息、聊天记录等)。

「顾客的唯一标识」来自你自己的用户系统。

注意:

示例:

<!-- 这是美洽的嵌入代码 -->
<script type='text/javascript'>
    (function(m, ei, q, i, a, j, s) {
        m[i] = m[i] || function() {
            (m[i].a = m[i].a || []).push(arguments)
        };
        j = ei.createElement(q),
            s = ei.getElementsByTagName(q)[0];
        j.async = true;
        j.charset = 'UTF-8';
        j.src = 'https://static.meiqia.com/dist/meiqia.js?_=t';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');

    // 设置 clientId
    _MEIQIA('clientId', '顾客的唯一标识');
</script>
<script type='text/javascript'>
    // 当你使用了「手动初始化」时,就可以在自己的逻辑中选择合适的时机调用 clientId
    // 只要是在美洽初始化之前,就可以被正确执行
    _MEIQIA('clientId', '顾客的唯一标识');
    _MEIQIA('init');
</script>

「聊天链接」传递顾客信息

你可以通过给链接添加 metadata 参数来传递顾客的信息到美洽工作台。

如果你传递了默认信息以外的数据,它在美洽工作台中将以「自定义信息」的方式被呈现出来。

美洽默认的顾客个人信息包括:

address, // 地址
age, // 年龄
comment, // 备注
email, // 邮箱
gender, // 性别
name, // 名字
qq, // QQ
tel, // 电话
weibo, // 微博
weixin // 微信

示例:

注意: metadata 中,key 和 value 都要添加双引号

/standalone.html?_=t&eid=我是企业ID&metadata=
{"name":"老王","qq":"123456","age":"11","gender":"男"}

注意:如果你要在 metadata 中添加带有 & 或者 = 的数据,那么你应该先对它们进行转义

&  %26
=  %3D

正确:
/standalone.html?_=t&eid=我是企业ID&metadata={"name":"老王","qq":"123456",
"age":"11","gender":"男","网址":"http://meiqia.com?a%3D1%26b%3D2"}

错误:
/standalone.html?_=t&eid=我是企业ID&metadata={"name":"老王","qq":"123456",
"age":"11","gender":"男","网址":"http://meiqia.com?a=1&b=1"}

「聊天链接」指定多个客服

/standalone.html?_=t&eid=我是企业ID&fallback=1&agentid=token1,token2,token3

「聊天链接」设置当指定客服不可服务时如何处理

当你指定的客服不在线或无法服务时,可以通过在链接中增加 fallback 参数来指定不同的处理方式。

fallback 接受的参数为数字类型,目前有 1、2、3

1 // 不转接(进入留言页面)
2 // 转接到客服所属于的组
3 // 转接到全企业(这是美洽默认的处理方式)

示例:

/standalone.html?_=t&eid=我是企业ID&fallback=1

「聊天链接」同步顾客身份

如果你的产品有多种形式(网页、APP),且都使用了美洽,那么可以通过在链接中添加 clientid 参数来传递顾客的唯一标识,从而同步顾客的身份(包括顾客信息、聊天记录等)。

「顾客的唯一标识」来自你自己的用户系统。

示例:

/standalone.html?_=t&eid=我是企业ID&clientid=我是顾客唯一标识