MAX POST Message 整合

使用 POST Message 進行 IFrame 整合

為促進基於桌面的進階整合，MAX (My Agent eXperience) 客服專員用戶端支援透過自訂嵌入的網頁進行事件訂閱。MAX 能夠使用「聯絡人」面板（與關聯的聯絡人一同開啟和關閉）或自訂工作區（始終開啟且可用，與單個聯絡人無關）來嵌入 (IFrame) 網頁。「聯絡人」面板的一個常見用例是特定於客戶的 CRM 網頁在通話過程中以螢幕彈出畫面的形式開啟（並在通話結束是關閉）。自訂工作區的一個常見用例是與聯絡人或客戶互動沒有直接關聯的知識庫頁面或其他站點。

在任一種情況下（「聯絡人」面板或自訂工作區），嵌入的「子」網頁均可透過 POST 訊息訂閱由「上層」MAX 視窗接收的系統事件。MAX 經常從 ACD 平台接收資訊，其中包含有關客服專員狀態或個人聯絡人的詳細資訊。透過訂閱此類事件，IFramed 網頁可以實現回應 MAX 中行為的自訂邏輯。例如，當客服專員的狀態從可用變為工作中以及從工作中變為不可用，自訂嵌入式網頁可能基於業務規則選擇響應。或者，當收到新的呼叫時，網頁可以收到新呼叫的通知，並做出相應的響應。欲了解更多詳細資訊，請訪問 https://developer.niceincontact.com/API、https://developer.niceincontact.com/Documentation/AgentSessionEvents 和 https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage 查看其他文件。

資料物件變數

MAX 設定為在包含以下值的資料物件中接收來自客戶的發布訊息。所有屬性金鑰均區分大小寫。若有說明，值也區分大小寫。

  • contactCardData：此為包含客戶姓名及電話聯絡人圖像的資料物件。它有兩個金鑰，name 和 userImg。區分大小寫。
  • contactId：此為可選的 int.。若您知道聯絡人 ID，可於此處提供。若您沒有聯絡人 ID 且它已載入至聯絡人面板中，我們將查找關聯面板的聯絡人 ID。一般自定工作區沒有可透過這種方式查找的聯絡人 ID，因此，如果需要特定於聯絡人的條目，就需要提供聯絡人 ID。
  • issuer：此為可選字串。它作為傳送者的識別碼名稱，但它不一定是唯一的。此字串有助於記錄，以將內文新增至控制台日誌。在測試中，您可能會發現發布訊息偵聽器接收您傳送的註冊訊息。您可以使用此欄位來確定訊息是否來自於您。MAX 將傳送以「MAX」作為簽發者的響應事件。
  • messageType：此為必要字串。區分大小寫。它有兩個有效條目：
    條目值結果
    "RegisterForClientEvents"MAX 透過這種方式了解您要設定用戶端事件訂閱。
    "UnregisterFromClientEvents"這將斷開您的視窗引用與 MAX 的連線並結束用戶端事件傳送。若您要變更訂閱類型或 contactId，則需要在重新註冊之前呼叫它。

    若不這樣做，並在 contactPanel 中使用具有新註冊的相同視窗，則會導致錯誤。

    "ContactCardData"MAX 透過這種方式了解它正在獲取客戶名稱以及電話聯絡人的圖像。
  • subscriptionTypes：此為必要的字串陣列。它不區分大小寫，因為陳列中的所有內容都將標準化為小寫。陣列的值可以新增。每個選項都指定了您將接收的訊息的類型。以下是幾個可能的有效條目：
    條目值結果
    "all"這將返回所有內容。
    "agent"這將返回任何沒有聯絡人 ID 的事件。
    "contact”若 IFrame 連接至技能或聯絡人，這將返回受所請求聯絡人 ID 或關聯面板的聯絡人 ID 限制的事件。
    "contacts”這將返回所有具有 ID 的事件。若您正在聯絡人面板中，且需要此面板聯絡人的額外資訊，請新增此欄位。
    “sessioninfo"這將返回客服專員的工作階段權標。若您希望進行特定於客服專員工作階段的 API 調用，可註冊此事件。

為 subscriptionTypes 使用空陣列將導致出錯。

當 MAX 收到訂閱以及確認訊息時，我們將傳送所請求訂閱類型的當前狀態，以幫助適當地設定工作區。此類事件將在開始時得到保證。

條目值 當前狀態
"all" 將返回當前 AgentState 以及 MAX 範圍內的所有當前聯絡人。
"agent" 將返回當前 AgentState。這不包括客服專員的工作階段權標。
"contact" 若聯絡人存在於 MAX 範圍內，則將返回當前聯絡人狀態。
"contacts" 將返回存在於 MAX 範圍內的所有當前聯絡人。

很有可能註冊有時會在初始化時收到比基本 AgentState 和聯絡人更多的事件。這些事件可能包括 AgentLegEvent、AgentSessionStart 和 MchAgentSettingsChangeEvent。若您的訂閱請求在我們建立對此資料的本地引用之前收到，您將看到此類額外事件。在這種情況下，我們將儲存並傳遞透過 get-next-event 傳遞至 MAX 的所有事件，就像您在使用過程中通常收到的那樣。唯一的差異在於我們無法為基本初始化選出特定核心事件。同樣的篩選器將套用於您註冊的資料，因此不應該產生異常結果。

呼叫命令

若 MAX 處於接收給定命令的有效狀態，它將在應用程式中調用該動作。此類命令與用於聯絡人處理的主按鈕緊密對準。它們不會回傳訊息。

條目值

結果
AnswerEvent 和 RefuseEvent 當呼入呼叫顯示接受/拒絕對話框時發生。

HoldEvent、MuteEvent 和 MaskEvent

用作切換開關。例如，調用 Hold 一次，通話將處於保留狀態，再調用一次，通話恢復。
RecordEvent 一次性動作。例如，一旦 Record 被調用，就不能停止它。
HangupEvent 在沒有確認對話方塊的情況下，通話立即終止。

示例通話（僅需要 messageType）

opener.postMessage({ messageType: 'MuteEvent' }, '');*

實作示例

// 查找上層視窗 (MAX) 以註冊事件。

var opener = window.opener || window.parent;

// 設定您的訂閱

var subscriptionTypes = ['agent', 'contacts'];

 

// 開始聆聽回覆訊息。

var doSomething = function (events) {

spacevar event = null;

space var eventIndex = null;

space for(eventIndex in events){

spacespace if (events.hasOwnProperty(eventIndex)){

spacespacespaceevent = events[eventIndex];

spacespace }

space }

};

var listenForPostMessage = function (event) {

if (event.data && event.data.events && event.data.issuer === 'MAX') {

logToConsole('=== received a post message with [' + event.data.events.length + '] events ===');

doSomething(event.data.events);

}

};

// 新增 MAX 用戶端事件的監聽器。

window.addEventListener('message', listenForPostMessage);

// 傳送註冊資訊至 MAX

opener.postMessage({ contactId: contactId, issuer: 'MyTestSite', messageType: 'Register-ForClientEvents', subscriptionTypes: subscriptionTypes }, '*');

回覆物件

回覆物件

{

issuer:「MAX」

contactId: int (Nullable) - 作為持續性面板找到或傳入的聯絡人 ID。若沒有傳入或找到 contactId，則此值為 null。

events: [ object, object, object ... ] - 在這組與訂閱類型或聯絡人篩選器匹配的事件中返回的所有事件。

}

對「SessionInfo」訂閱的 Message Shape 的回覆

{

messageType: "SessionInfo"

sessionToken: "mysessiontoken=="

}

訂閱確認事件

若至少有一種 subscriptionType，則允許訂閱。若沒有有效 subscriptionTypes，則將記錄顯示無效類型的控制台警告。返回的事件集中的第一個事件將是訊息類型為 ClientEventSubscriptionAcknowledge 的事件。此事件具有以下架構：

{

contactId: (int) - 若為 null，則表示 contactId 與訂閱相關。這是讓客戶檢視其「聯絡人」訂閱是否有效的一種方式。

messageType: ClientEventSubscriptionAcknowledge - （字元）。這是其特定的確認事件訊息類型。

reason: "Success" | "Invalid Contact Id" | "Invalid Subscription Types" - 若它以錯誤狀態代碼的原因回應。為了不過於增加複雜性，這不會非常詳細。它僅會返回一個故障原因。我們首先檢查聯絡人 ID 的有效性（不是零，或者不是整數字串）。如果這失敗但還有無效的訂閱類型，則我們不會顯示子錯誤，直至他們在修復聯絡人 ID 後重試。這表示我們沒有保留對視窗的引用，因此訂閱失敗。

status: "OK” 或 "ERROR" - 若返回 Error，則我們沒有成功建立發布訊息訂閱連接。他們需要修復這些錯誤然後重試。

}

在某些情況下，不會傳送訂閱確認。若相同的視窗請求第二個訂閱，如果沒有首先移除現有訂閱，將不會傳送回應，也不會識別其他訂閱。我們將列印一則控制台警告，其結構如下：

{

console.warn('Error processing Client Even Subscription.Issuer: [' + subscriberObject.data.issuer + '] has already subscribed.')

}