1. 首页
  2. 开发指南
  3. JavaScript 网页插件

JavaScript 网页插件

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

手动初始化

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

使用方法如下:

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

注意:

  • _MEIQIA('manualInit'); 必须紧跟在美洽的嵌入代码后面。
  • 没有设置 _MEIQIA('manualInit'); ,是无法使用 _MEIQIA('init'); 的。
  • 如果你在美洽的代码还没有下载完毕的情况下调用了 _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';
        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';
        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';
        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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    // 初始化成功后调用美洽 showPanel
    _MEIQIA('allSet', function(){
      _MEIQIA('showPanel');
    });
</script>

会话开始时的回调

示例:

<!-- 这是你的代码 -->
<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //会话开始时的回调
    _MEIQIA('startConversation',handleStart)
</script>

会话结束时的回调

示例:

<!-- 这是你的代码 -->
<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //会话结束时的回调
    _MEIQIA('endConversation',handleEnd)
</script>

智能引导展示的回调

示例:

<!-- 这是你的代码 -->
<script type='text/javascript'>
    function showGuide() {
        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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //智能引导展开
    _MEIQIA('showSmartGuide',showGuide)
</script>

智能引导消失的回调

示例:

<!-- 这是你的代码 -->
<script type='text/javascript'>
    function closeGuide() {
        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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //智能引导消失
    _MEIQIA('closeSmartGuide',closeGuide)
</script>

获取关闭 Widget 事件

顾客点击 Widget 的关闭按钮时,您可以获取到该点击事件。

示例:

<!-- 这是你的代码 -->
<script type='text/javascript'>
    function handleBeforeCloseWindow() {
        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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //点击关闭按钮后的回调
    _MEIQIA('beforeCloseWindow', handleBeforeCloseWindow);
</script>

多语言

我们目前支持以下语言:

  • zh-CN: 简体中文
  • tw: 繁体中文
  • en: 英语
  • id: 印尼语
  • ms: 马来语
  • th: 泰语
  • vi: 越南语
  • ja: 日语
  • pt: 葡萄牙语
  • hi: 印地语
  • es: 西班牙语
  • ko: 韩语
  • ru: 俄语
  • my: 缅甸语
  • km: 柬埔寨语
  • fil: 菲律宾语
  • fr: 法语
  • lo: 老挝语
  • nl: 荷兰语
  • de: 德语
  • ar: 阿拉伯语
  • bn: 孟加拉语
  • tr: 土耳其语
  • fa: 波斯语
  • it: 意大利语
  • pl: 波兰语
  • zu: 祖鲁语

请直接使用语言代码进行设置,可以参考下面示例👇

Widget 英语版示例:

<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //如果需要英文版,可用如下配置
    _MEIQIA('language','en')
</script>

聊天链接英语版示例:

/standalone.html?eid=我是企业ID&language=en

跟随浏览器语言

您可以在网页插件 / 聊天链接中携带 languageLocal 参数来控制他们初始化时是否跟随顾客的浏览器语言。

Widget 启用跟随示例:

<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    //如果需要英文版,可用如下配置
    _MEIQIA('language','en');
    //启用跟随浏览器语言,可用如下配置
    _MEIQIA('languageLocal','true')
</script>

聊天链接启用跟随示例:

/standalone.html?eid=我是企业ID&language=en&languageLocal=true

当您启用了跟随,美洽会按以下优先级判断网页插件 / 聊天链接的语言:

  1. 优先浏览器语言,当浏览器语言不在美洽支持的语言范围内时,往下判断;
  2. 然后是渠道指定的语言,当他们不指定语言或者指定的语言代码不合法时,往下判断;
  3. 最后是渠道默认语言,默认语言是简体中文。

打开聊天窗

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

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

注意:

  • 如果你在美洽插件还没有初始化成功的情况下调用了本接口,它将无法被正确执行。
  • 如果你想要在美洽插件加载完毕后立即调用聊天窗,那么可以组合「初始化成功时的回调」接口来实现。

示例:

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

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

注意:

  • 你可以从美洽工作台「设置」中的「ID 查询」处获取客服或客服组的 Token。

示例:

<!-- 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'
    });
    // 指定多个客服组
    _MEIQIA('assign', {
        groupToken: 'Token1,Token2,Token3'
    });
    // 如果你同时传递了 agentToken 和 groupToken
    // 那么 groupToken 将被忽略
    _MEIQIA('assign', {
        agentToken: '客服智子的 Token', // 只有我会起作用
        groupToken: '客服组的 Token' // 我被抛弃了
    });
</script>

传递顾客信息

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

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

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

注意:

  • 如果你在美洽的代码还没有下载完毕的情况下调用了本接口,它会等到美洽代码下载完毕后才被执行。

示例:

<!-- 这是你的代码 -->
<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    // 传递顾客信息
    _MEIQIA('metadata', {
        name: '智子', // 美洽默认字段
        address: '半人马座阿尔法星', // 美洽默认字段
        aaa: 'bla bla bla', // 自定义字段
        xyz: 'lalala' // 自定义字段
    });
</script>

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

  • 个人信息:
  • 姓名: 智子
  • 地址: 半人马座阿尔法星
  • 自定义信息:
  • aaa: bla bla bla
  • xyz: lalala
  • action: 触发了 doSomething

添加顾客自定义事件信息

如果你的产品有多种形式(网页、APP),且都使用了美洽,那么可以使用 _MEIQIA('trackEvent', '事件名称','事件详细数据') 来记录顾客的自定义事件信息。

注意:

  • 事件名称为长度6到32的字符串
  • 事件详细数据只支持key 和 value,key 和 value 均为字符串

示例:

<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    // 在这里添加自定义事件,使用请取消注释并修改以下内容
    // _MEIQIA('trackEvent','添加购物车',{'金额':'180元','数量':'2'});
</script>

追踪自定义聊天按钮点击事件

有时访客点击了您网站上某个特定的聊天按钮,但是出于某些原因可能并没有主动发起对话。此时您可以通过追踪这个特定聊天按钮的点击事件来判断客户的访问意图。通过调用 _MEIQIA(' showPanel', {greeting: "消息内容"}) 方法来通知客服人员,客服就可以根据消息内容来做出判断,从而更好地和客户主动展开对话,进而提高您的访客转化率。

示例:

<ul>
    <li onClick="_MEIQIA('showPanel', {greeting: '咨询A套餐'})">A 套餐</li>
    <li onClick="_MEIQIA('showPanel', {greeting: '咨询B套餐'})">B 套餐</li>
    <li onClick="_MEIQIA('showPanel', {greeting: '咨询C套餐'})">C 套餐</li>
</ul>

注意:此用法适用于自定义聊天按钮场景,仅在对话创建前生效。若开启了强制对话或者无消息访客过滤均会导致此方法无效

获取未读消息

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

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

注意:

  • 本接口不一定要紧跟在美洽的嵌入代码后面,但必须在美洽插件初始化之前使用。
  • 由于存储未读消息的依赖于浏览器的 localStorage,所以在 IE8 以下的浏览器中,是无法获取未读消息的。

示例:

<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';
        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';
        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';
        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';
        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', '顾客的唯一标识') 来同步顾客的身份(包括顾客信息、聊天记录等)。

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

注意:

  • 顾客唯一标识为长度6到32的字符串,是由你来生成的,请保证每个顾客拥有独一无二的字符串,否则会出现多个客户串消息的情况!
  • 本接口不一定要紧跟在美洽的嵌入代码后面,但必须在美洽插件初始化之前使用。

示例:

<!-- 这是美洽的嵌入代码 -->
<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';
        s.parentNode.insertBefore(j, s);
    })(window, document, 'script', '_MEIQIA');
    _MEIQIA('entId', '我是企业ID');
    // 设置 clientId,使用请取消注释并使用自己系统的顾客ID
    // _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?eid=我是企业ID&metadata=
{"name":"老王","qq":"123456","age":"11","gender":"男"}

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

&  %26
=  %3D

正确:

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

错误:

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

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

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

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

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

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

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

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

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

示例:

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

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

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

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

顾客唯一标识是由你来生成的,请保证每个顾客拥有独一无二的字符串,否则会出现多个客户串消息的情况!

示例:

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

展开对话窗口(创建对话/排队/留言)回调接口

点击聊天按钮展开聊天窗时调用(必须处于有对话,或排队,或留言的状态之一)。

参数说明

  • type 参数共 3 个值,queue(排队),ticket(工单),conv(对话);
  • convId 参数只有在 type 参数值为 conv 时才有值,当 type 参数值不为 conv 时 convId 的值为空字符串。

特殊情况

  • 访客消息过滤开启时,访客输入第一条消息前不会调用;输入第一条后,会调用一次,后面每次点击聊天按钮展开聊天时调用一次;
  • 机器人开启时,建立与机器人的对话也会正常调用;转人工时,如果进入排队或留言,后面每次点击聊天按钮展开聊天窗时会以相应的 type 调用;如果有机器人接待,同时有可能进入排队,这种情况按照排队处理
<script>
_MEIQIA('convClickCallback', clickCallback);
function clickCallback(type, convId) {
 console.log(type);
 if (type === 'conv') {
   console.log(convId);
 }
}
</script>

商品卡片

网页插件发送商品卡片

企业希望看到用户发起对话时正在浏览的商品信息,以便客服更好的进行客户服务,那么企业可以通过以下方式实现:

<div>
    <button onclick="sendCardMsg()">发送商品卡片</button>
</div>
<script>
  function sendCardMsg() {
    _MEIQIA('product', {
      picUrl: 'https://xxx/xxx.jpg',
      title: '美洽 - 客服系统',
      description: '支持PC端/移动端/微信/APP/微博...等全渠道对话接入,稳定快速,无需下载部署,注册即用',
      productUrl: 'https://xxx/xxx.html',
      salesCount: 111,
      success: data => {
        console.log(data, 'data');
      },
      error: error => {
        console.log(error, 'error');
      }
    });
  }
</script>

工作台插件(iframe)发送商品卡片

如果你已经配置美洽「自定义iframe」,同时希望嵌入在 iframe 中的页面能够直接发送商品卡片给客户(ex:比如嵌入的页面是企业商品库,客服可以直接在该页面发送商品卡片),那么通过以下方式实现:

<div>
    <button onclick="sendCardMsg()">发送商品卡片</button>
</div>
<script>
  function sendCardMsg() {
    window.parent.postMessage({
      type: 'sendProductCard',
      content: {
        picUrl: 'https://xxx/xxx.jpg',
        title: '美洽 - 客服系统',
        description: '支持PC端/移动端/微信/APP/微博...等全渠道对话接入,稳定快速,无需下载部署,注册即用',
        productUrl: 'https://xxx/xxx.html',
        salesCount: 111,
      }
    }, '*');
  }
</script>

商品卡片消息的字段规则:

字段是否必传验证规则描述
picUrl字符串且长度小于等于2000建议商品配图尺寸:242*184,或同等比例
title字符串且长度小于等于100商品标题
description字符串且长度小于等于500商品介绍
productUrl字符串且长度小于等于2000商品 URL
salesCount正整数且不超过15位商品销量数目

加密传递顾客信息

你可以通过给链接添加 encryptedMetadata 参数来传递顾客

传递顾客信息数据的时候,需要开发者先加密后,再通过 encryptedMetadata 字段来传递

示例:

1.准备待传递数据(待传递数据是一个 JSON 对象):
{"name":"value"}

2.加密数据(参考下面的加密算法,该示例中,密码 和 偏移量为:2bab953cb29e7a1e3be20ab97d5c675b),得到加密数据:
cd0caf04a1c6ff63d7951cd5e2016167066c6032e2fd2c8ae543a02d6145e897

3.在链接中添加 encryptedMetadata 参数来传递
/standalone.html?eid=我是企业ID&encryptedMetadata=cd0caf04a1c6ff63d7951cd5e2016167066c6032e2fd2c8ae543a02d6145e897

4.在插件中使用
function setEncryptedmetadata () {
  _MEIQIA('encryptedMetadata', 'cd0caf04a1c6ff63d7951cd5e2016167066c6032e2fd2c8ae543a02d6145e897');
}

加密算法

AES 加密模式:CBC

填充模式:PKCS7Padding

数据块:128

密码:(约定为企业 ID)

偏移量:(约定为企业 ID)

输出:Hex

字符集:UTF-8

企业 ID 在 工作台 - 设置 - 团队 - 团队管理 - ID 查询 中查看

在线加密测试:http://tool.chacuo.net/cryptaes

加密&解密参考:https://gist.github.com/ksxkq/00a21e18bcadb86512a023f95c4ecb13
Updated on 2024年3月7日

本文是否有帮助?

您可能想了解