關于美洽 2016 JavaScript 網站插件，以及通過鏈接直接打開的單頁美洽對話窗口的接口說明。 [toc] ### 手動初始化 在加載了美洽網站插件的前提下，你可以在自己的 JavaScript 中通過調用?`_MEIQIA('init')`?來實現手動初始化。 使用方法如下： 1. 在美洽的嵌入代碼后加入?`_MEIQIA('manualInit');`?，這個設置將會阻止美洽插件代碼在下載完畢后自動執行初始化操作。 2. 當你需要初始化美洽插件的時候，在 JavaScript 代碼中調用?`_MEIQIA('init')`?即可。 注意： * `_MEIQIA('manualInit');`?必須緊跟在美洽的嵌入代碼后面。 * 沒有設置?`_MEIQIA('manualInit');`?，是無法使用?`_MEIQIA('init');`?的。 * 如果你在美洽的代碼還沒有下載完畢的情況下調用了?`_MEIQIA('init')`，它會等到美洽代碼下載完畢時才被響應。 示例： 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 在這里開啟手動模式（必須緊跟美洽的嵌入代碼） _MEIQIA('manualInit'); // 你可以自己的代碼中選擇合適的時機來調用手動初始化 _MEIQIA('init'); <!-- 在實際使用時你可能會面臨很復雜的場景，但是沿著這個套路發揮吧。May force be with you --> ### 不使用美洽的聊天按鈕 有時候，也許你不想要顯示美洽自帶的聊天按鈕，那么你可以使用?`_MEIQIA('withoutBtn');`。 注意: * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 示例： 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 在這里開啟無按鈕模式（常規情況下，需要緊跟在美洽嵌入代碼之后） _MEIQIA('withoutBtn'); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 withoutBtn // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('withoutBtn'); _MEIQIA('init'); ### 初始化成功時的回調 有時候，也許你需要在美洽網站插件加載成功后執行一些事件，那么可以使用?`_MEIQIA('allSet', callback)`。 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 示例： type='text/javascript'> function yourFunction() { // 你可以根據自己的需求編寫相應的代碼 console.log('美洽網站插件初始化完畢。'); } 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 初始化成功時的回調 _MEIQIA('allSet', yourFunction); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 allSet // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('allSet', yourFunction); _MEIQIA('init'); 如果你想在初始化成功時獲知客服的在線狀態，那么可以為你編寫的 callback 函數添加一個參數，美洽插件在調用它時，會返回當前的客服狀態。 示例： type='text/javascript'> /** * [yourFunction] * @param {boolean} servability [true: 有客服在線, false: 無客服在線] */ function yourFunction(servability) { // 你可以根據自己的需求編寫相應的代碼 console.log('美洽網站插件初始化完畢。'); if (servability) { console.log('有客服在線'); } else { console.log('無客服在線'); } } ### 強制對話 如果你想讓美洽加載成功后直接打開聊天窗口可以如下設置： 示例： 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 = '//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'); }); ### 會話開始時的回調 示例： `html <!-- 這是你的代碼 --> <script type='text/javascript'> function handleStart() { console.log('會話開始回調') } </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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); //會話開始時的回調 _MEIQIA('startConversation',handleStart) ### 會話結束時的回調 示例： `html <!-- 這是你的代碼 --> <script type='text/javascript'> function handleEnd() { console.log('會話開始回調') } </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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); //會話結束時的回調 _MEIQIA('endConversation',handleEnd) ### 英文版 示例： 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); //如果需要英文版，可用如下配置 _MEIQIA('language','en') * 如果您用的是聊天鏈接的方式，那么英文版您可以這樣: ```html 正確： /standalone.html?_=t&eid=我是企業ID&language=en 錯誤： /standalone.html?_=t&eid=我是企業ID&language=EN ``` ### 打開聊天窗 在某些需求下，你可能希望在自己編寫的代碼中掌控美洽聊天窗。 在美洽網站插件初始化成功的前提下，調用?`_MEIQIA('showPanel')`?就可以打開美洽聊天窗。 注意： * 如果你在美洽插件還沒有初始化成功的情況下調用了本接口，它將無法被正確執行。 * 如果你想要在美洽插件加載完畢后立即調用聊天窗，那么可以組合「初始化成功時的回調」接口來實現。 示例： href="javascript:void(0)" onclick="_MEIQIA('showPanel')">聯系客服 _MEIQIA('showPanel'); 如果你想要在調用聊天窗時指定客服或客服組，只需要添加相應的參數即可。 注意： * 你可以從美洽工作臺「設置」中的「ID 查詢」處獲取客服或客服組的 Token。 示例： href="javascript:void(0)" onclick="_MEIQIA('showPanel', {agentToken: '客服智子的 Token'})">聯系客服-智子 // 指定客服 _MEIQIA('showPanel', { agentToken: '客服智子的 Token' }); // 指定客服組 _MEIQIA('showPanel', { groupToken: '客服組的 Token' }); // 如果你同時傳遞了 agentToken 和 groupToken // 那么 groupToken 將被忽略 _MEIQIA('showPanel', { agentToken: '客服智子的 Token', // 只有我會起作用 groupToken: '客服組的 Token' // 我被拋棄了 }); ### 隱藏聊天窗 在美洽網站插件初始化成功的前提下，調用?`_MEIQIA('hidePanel')`?就可以隱藏美洽聊天窗。 示例： onclick="_MEIQIA('hidePanel')">隱藏窗口 _MEIQIA('hidePanel'); ### 通過配置指定分配客服或客服組 某些情況下，你可能希望直接以配置的形式來指定要分配的客服或客服組，那么你可以使用?`_MEIQIA('assign', {})`。 assign 配置對美洽自帶按鈕和「打開聊天窗」接口都生效，但是當「打開聊天窗」接口本身攜帶了客服信息時，就會忽略 assign 的配置。 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但盡量在建立對話之前使用。 示例： // 指定客服 _MEIQIA('assign', { agentToken: '客服智子的 Token' }); // 指定多個客服 _MEIQIA('assign', { agentToken: 'Token1,Token2,Token3' }); // 指定客服組 _MEIQIA('assign', { groupToken: '客服組的 Token' }); // 如果你同時傳遞了 agentToken 和 groupToken // 那么 groupToken 將被忽略 _MEIQIA('assign', { agentToken: '客服智子的 Token', // 只有我會起作用 groupToken: '客服組的 Token' // 我被拋棄了 }); ### 傳遞顧客信息 在美洽工作臺中，你可以手動為對話中的顧客添加個人信息，而通過?`_MEIQIA('metadata', {})`?接口，可以將這個工作自動化。 美洽默認的顧客個人信息包括： address // 地址 age // 年齡 comment // 備注 email // 郵箱 gender // 性別 name // 名字 qq // QQ tel // 電話 weibo // 微博 weixin // 微信 注意： * 如果你在美洽的代碼還沒有下載完畢的情況下調用了本接口，它會等到美洽代碼下載完畢后才被執行。 示例： type='text/javascript'> /** * [在顧客訪問你的網站期間，當他觸發了某些特定事件時，你可以即時的調整顧客信息] * [假設 doSomething 是你用來處理某個特定事件的函數] */ function doSomething () { // 傳遞顧客信息 _MEIQIA('metadata', { action: '觸發了 doSomething' }); } 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 = '//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' // 自定義字段 }); 在美洽工作臺中，上方傳入的數據將以如下形式分類呈現： * 個人信息: * 姓名: 智子 * 地址: 半人馬座阿爾法星 * 自定義信息: * aaa: bla bla bla * xyz: lalala * action: 觸發了 doSomething ### 獲取未讀消息 美洽官方的聊天按鈕可以顯示未讀消息的數量，以及提供最近一條未讀消息的預覽。 如果你設置了無按鈕模式，這兩個數據也就無法被呈現了。但是通過?`_MEIQIA('getUnreadMsg', callback);`?接口，你可以從?`callback`?的參數中得到這些數據，用自己的方式在顯示它們。 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 * 由于存儲未讀消息的依賴于瀏覽器的 localStorage，所以在 IE8 以下的瀏覽器中，是無法獲取未讀消息的。 示例： 我的數據來自未讀消息接口 未讀消息數量: id="unreadNum">0 最后一條未讀消息的內容: id="unreadMsg"> /** * [處理未讀消息] * @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( /]*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; } 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 獲取未讀消息 _MEIQIA('getUnreadMsg', yourFunction); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 getUnreadMsg // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('getUnreadMsg', yourFunction); _MEIQIA('init'); ### 獲取邀請事件 如果你不想使用美洽提供的邀請彈窗，那么可以用?`_MEIQIA('getInviting', callback);`?來獲取邀請事件，然后編寫自己喜歡的彈窗。 注意： * 當你使用了本接口后，美洽提供的邀請彈窗將不再出現。 * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 * 想要在自己編寫的邀請彈窗中「接受邀請」，可以使用「打開聊天窗」接口。 * 如果你看過美洽工作臺的「對話邀請」設置，應該知道美洽自帶的邀請彈窗擁有「手動邀請」和「自動邀請」。本接口只針對客服手動發出的邀請進行推送。 示例： /** * [處理邀請事件] * @param {string} agentToken [發出邀請的客服的 token] */ function yourFunction(agentToken) { // 你可以在這里面調用你自己編寫的邀請窗口 // 當顧客接受邀請時，你只需要使用下面的方法，即可成功響應邀請 //「打開聊天窗」接口 _MEIQIA('showPanel', { agentToken: agentToken }); } 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 獲取邀請事件 _MEIQIA('getInviting', yourFunction); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 getInviting // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('getInviting', yourFunction); _MEIQIA('init'); ### 拒絕邀請 當你使用「獲取邀請事件」接口時，可以用?`_MEIQIA('rejectInvitation')`?在自己編寫的彈窗中觸發美洽的拒絕邀請事件。 注意: * 只有在使用了「獲取邀請事件」接口時，本接口才有效。 示例： /** * [你自己編寫的拒絕邀請函數] */ function yourFunction() { // 你可以先執行自己的邏輯代碼 // 在適當的時機調用一下美洽的拒絕邀請接口即可 _MEIQIA('rejectInvitation'); } ### 獲取聊天窗口可見性 如果你想在美洽聊天窗口顯示或隱藏時處理一些自己的事件，那么可以使用 `_MEIQIA('getPanelVisibility', callback)` 來獲取聊天窗口可見性。 比如你編寫了自己的聊天按鈕，想在美洽聊天窗口顯示時隱藏聊天按鈕（反之亦然），那么這個接口可以幫助你實現需求。 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 示例： /** * [根據聊天窗口的可見狀態執行相應的事件] * @param {string} visibility [聊天窗口的可見狀態，visible || invisible] */ function yourFunction(visibility) { if (visibility === 'visible') { console.log('聊天窗口處于顯示狀態'); } else { console.log('聊天窗口處于隱藏狀態'); } } 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 獲取聊天窗口可見性 _MEIQIA('getPanelVisibility', yourFunction); type='text/javascript'> // 當你使用了「手動初始化」時 // 就可以在自己的邏輯中選擇合適的時機調用 getPanelVisibility // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('getPanelVisibility', yourFunction); _MEIQIA('init'); ### 設置當指定客服不可服務時如何處理 當你指定的客服不在線或無法服務時，可以通過在美洽嵌入代碼之后設置?`_MEIQIA('fallback', 1);`?來指定不同的處理方式。 fallback 接受的參數為數字類型，目前有 1、2、3 1 // 不轉接（進入留言也面） 2 // 轉接到客服所屬于的組 3 // 轉接到全企業（這是美洽默認的處理方式） 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 示例： 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 設置 fallback _MEIQIA('fallback', 1); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 fallback // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('fallback', 1); _MEIQIA('init'); ### 同步顧客身份 如果你的產品有多種形式（網頁、APP），且都使用了美洽，那么可以使用?`_MEIQIA('clientId', '顧客的唯一標識')`?來同步顧客的身份（包括顧客信息、聊天記錄等）。 「顧客的唯一標識」來自你自己的用戶系統。 注意： * 本接口不一定要緊跟在美洽的嵌入代碼后面，但必須在美洽插件初始化之前使用。 示例： 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 = '//static.meiqia.com/dist/meiqia.js?_=t'; s.parentNode.insertBefore(j, s); })(window, document, 'script', '_MEIQIA'); _MEIQIA('entId', '我是企業ID'); // 設置 clientId _MEIQIA('clientId', '顧客的唯一標識'); type='text/javascript'> // 當你使用了「手動初始化」時，就可以在自己的邏輯中選擇合適的時機調用 clientId // 只要是在美洽初始化之前，就可以被正確執行 _MEIQIA('clientId', '顧客的唯一標識'); _MEIQIA('init'); ### 聊天鏈接 你可以通過給鏈接添加 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=我是顧客唯一標識 參考官網： https://meiqia.com/docs/meiqia-js-sdk