MAX 发布消息整合

使用发布消息进行 IFrame 整合

为促进基于桌面的高级集成,MAX (My Agent eXperience) 坐席客户端支持通过自定义嵌入网页进行事件订阅。MAX 能够使用联系人面板(与关联的联系人一起打开和关闭)或自定义工作区(始终打开和可用,与单个联系人无关)来嵌入 (IFrame) 网页。联系人面板的一个常见用例是特定于客户的 CRM 网页,作为呼叫的屏幕弹出被打开(然后在呼叫完成时关闭)。自定义工作区的一个常见用例是与联系人或客户交互没有直接关联的知识库页面或其他站点。

在任何一种情况下(联系人面板或自定义工作区),嵌入的“子”网页均可通过发布消息订阅“父”MAX 窗口接收到的系统事件。MAX 定期从 ACD 平台接收信息,其中包含有关坐席状态或个人联系人的详细信息。通过订阅此类事件,IFramed 网页可实现定制的逻辑来响应 MAX 中的行为。例如,当坐席的状态从有空变为工作中以及从工作中变为没空时,自定义嵌入的网页可能会根据业务规则选择响应。或者,当接收到新呼叫时,网页将收到新呼叫的通知,并做出相应的响应。有关更多信息,请在以下网站参阅其他文档:https://developer.niceincontact.com/APIhttps://developer.niceincontact.com/Documentation/AgentSessionEventshttps://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:这是一个必需的字符串。区分大小写。There are two valid entries:
    Entry ValueResult
    "RegisterForClientEvents"This is how MAX knows that you are looking to set up a client event subscription.
    "UnregisterFromClientEvents"This will disconnect your window reference from MAX and end the client event sending. 如果您想更改订阅类型或 contactId,就需要在重新注册之前调用它。

    Not doing this and using the same window with a new registration in the contactPanel will cause bugs.

    "ContactCardData"This is how MAX knows it's getting the customer name and image of the phone contact.
  • subscriptionTypes:这是一个必需的字符串数组。它不区分大小写,因为数组中的所有内容都将被规范化为小写。数组中的值可以添加。每个选项指定可您将接收的一种消息类型。There are a few possible valid entries:
    Entry ValueResult
    "all"This will return everything.
    "agent"This will return anything that doesn't have a contact ID.
    "contact"This will return events limited either by the contact ID requested or the contact ID for the associated panel if the IFrame is connected to a skill or contact.
    "contacts"This will return all events that have a contact ID. If you are in a contact panel and want additional information with the panel's contact, add this field.
    "sessioninfo"This will return an agent's session token. If you are looking to make agent session specific API calls, register for this event.

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

space space if (events.hasOwnProperty(eventIndex)){

spacespacespaceevent = events[eventIndex];

space space }

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) - 如果为空,则意味着没有联系人 ID 与订阅相关。这是客户查看他们的“联系人”订阅是否有效的一种方法。

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.')

}