MAX 发布消息整合

使用发布消息进行 IFrame 整合

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

在任何一种情况下（联系人面板或自定义工作区），嵌入的“子”网页均可通过发布消息订阅“父”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) - 如果为空，则意味着没有联系人 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.')

}