自定义坐席助手集成资源

此页面上的资源提供了您在规划和实施自定义坐席助手与CXone集成时所需的信息。

支持的坐席助手应用程序

MAX目前是唯一支持的与自定义坐席助手集成共同使用的坐席应用程序。

音频流媒体

音频数据包被编码为 G711 µlaw 8 位 8000 kHz 原始音频。这与所有 CXone 电话音频的格式相同。

当您在 坐席协助中心 中配置自定义坐席助手集成时，您可以选择要发送到坐席助手应用程序的音频。您可以从联系人、坐席或两者发送音频。

在每个流开始时，CXone 会向自定义坐席助手端点应用程序发送一条初始消息。初始消息包含 streamPerspective 参数，该参数指示音频流是坐席还是联系人：

• "streamPerspective": "RX"：坐席电话传输的音频：坐席正在讲话。
• "streamPerspective": "TX"：坐席听到的音频：联系人说话，或者多人交谈（如果交互处于多人模式）。
• "streamPerspective": "MIX"：包含坐席和联系人音频流。

单个 websocket 连接仅包含一个角度的音频。通常，这是 TX 或 RX，提供立体声分离。可以将两者混合在一个单声道流中。如果交互发生在多人模式下，则接收到的音频取决于配置的流视角。如果视角为 TX，则会收到除坐席之外的所有参与者的音频。

如果连接断开或出现其他问题（例如丢失数据包），自定义坐席助手端点会尝试恢复与 websocket 的连接。它期望新的身份验证握手与收到的初始握手相同。

如果联系被搁置，则 websocket 连接将关闭。当交互恢复时，将启动新的 websocket 连接。它期望握手与初始的握手相同。

授权

您可以在自定义坐席助手集成中使用授权。您的集成可能需要对坐席隧道和坐席助手应用程序上的请求进行身份验证。

坐席隧道授权

如果您希望坐席隧道在请求通过时需要授权，则需要在设计中包含此要求。您可以使用任何类型的授权，例如标头或基于动态令牌的授权。您必须构建坐席隧道才能使用您选择的授权方法。

您还需要配置Studio脚本来管理授权：

• 对于基于标头的授权，脚本必须在其发送的请求中包含标头。
• 对于基于令牌的授权，脚本需要请求令牌，将其存储在缓存中，并管理令牌过期。当令牌过期时，脚本必须请求新令牌（如果需要）。使用 REST API Studio 操作 与身份验证服务器通信。

如果您使用动态授权，则还需要设置授权服务器（如果您还没有可用的授权服务器）。当脚本请求令牌时，授权服务器会提供令牌。

坐席助手应用程序的授权

如果您的坐席助手提供程序需要对所有请求进行授权，您可以在 坐席协助中心 中的自定义坐席助手端点应用中进行配置。

要将授权与自定义集成结合使用，您需要：

• 生成授权标头以在自定义坐席助手集成脚本中使用。有关所有适用的配置，请参阅坐席助手提供程序的文档。
• 添加需要的标头至坐席协助中心中的自定义坐席助手端点应用程序。如果您将坐席助手应用程序与文本和语音交互一起使用，则每种交互类型都需要单独的标头。有关如何生成标头的信息，请参阅坐席助手提供程序的文档。

您不需要在脚本中配置任何内容。自定义坐席助手端点应用程序负责将标头传递给坐席助手应用程序。

CXone 平台配置的要求

无需在 CXone 平台中进行配置更改即可设置自定义坐席助手集成。您可以修改现有脚本以包含新的坐席助手应用程序。但是，可能需要进行一些配置，具体取决于您的组织使用新应用程序的方式。您可能需要：

• 为 语音 或 ACD 聊天 创建新的渠道 联系人与坐席或机器人交互的一种方式。通道可以是语音、电子邮件、聊天、社交媒体等。。
• 为 ACD 聊天创建新的聊天配置文件。
• 创建一项或多项 ACD 技能并将其分配给您想要自定义坐席的坐席助手应用程序。
• 为新渠道创建联络点。
• 修改现有联络点 呼入联系人用来发起交互的入口点，如电话号码或电子邮件地址。以启动新脚本。在您的自定义坐席助手集成经过全面测试并准备投入生产之前，请勿进行此更改。

序列图

序列图显示了自定义坐席的各个部分如何协助集成交互以及这些交互发生的顺序。它们显示了交互的时间线，从左上角开始，然后在页面上来回移动。

序列图是规划自定义集成的重要组成部分。您可以使用它们来绘制 CXone、坐席协助中心、坐席隧道、您的坐席助手应用程序。它们还可能有助于确定您的 Studio 脚本必须遵循的流程。

Studio脚本要求和指南

使用以下示例作为创建脚本的基础，将坐席助手应用程序集成到 CXone 中。呼入和呼出交互需要单独的脚本。下图显示了呼入脚本的基本操作：

此图显示了呼出脚本的基本操作：

在这两个脚本中，脚本参数有效负载 Snippet 都是可选的。仅当需要将参数传递给坐席助手应用程序时才需要包含它。

要完成脚本，您必须：

• 连接每个操作中所述。
• 根据需要添加其他操作、配置和脚本逻辑，以便脚本在您的环境中按照规定运行。

• 确保可选脚本参数有效负载 Snippet 操作包含将发送给坐席助手提供程序的自定义有效负载 JSON。

• 确保 Agent Assist 操作中的 scriptParams 属性设定为 {customPayloadJSON}。仅当您在自定义有效负载中包含可选的 Snippet 操作时才需要它。
• 将 Custom Agent Assist Endpoints 配置应用程序分配给 Agent Assist 操作。
• 使用 Snippet 操作 向脚本添加初始化代码片段。您可以这样做来自定义您的坐席助手应用程序。
• 重新配置操作连接器，以确保正确的联系流并纠正任何潜在错误。
• 完成任何额外的脚本编写并测试该脚本。

如果您需要有关在 Studio 中进行脚本编写的帮助，请联系您的 CXone 客户代表，参阅联机帮助的脚本编写指南部分，或者访问 NICE CXone 社区网站。

脚本参数有效负载片段

此代码段通过 Agent Assist action操作定义传递给坐席助手应用程序的数据。将此代码添加至您脚本中的 Snippet action操作中：

DYNAMIC customParam
customParam.param1 = "{value1}"
customParam.param2 = "{value2}"
customParam.param3 = "{value3}"
customParam.param4 = "{value4}"

ASSIGN customParamjson = "{customParam.asJSON()}" 

如果没有要发送的自定义有效负载参数，但需要脚本参数代码片段，您可以在该代码片段中包含变量声明，而不分配任何值。例如：

DYNAMIC customParam
ASSIGN customParamjson = "{customParam.asJSON()}" 

要使用此代码片段：

1. 根据需要更改参数名称和值，以满足您的组织和您使用的坐席助手应用程序的需求。
2. 将脚本中的 Snippet 操作放在 Agent Assist 操作之前。
3. 利用保留 JSON 的变量名称在 Agent Assist action操作中配置 scriptParams 属性。在提供的示例中，这将是 customParamjson。

新脚本与现有脚本

您可以创建新脚本以与自定义坐席助手集成一起使用。您还可以修改现有脚本。请勿直接对当前正在生产的脚本进行更改。这样做可能会导致错误，从而中断联系路由。

如果您想使用现有脚本，请保存脚本的副本并进行修改。当您的自定义集成经过全面测试并准备好实施后，您可以将修改后的脚本移回生产环境。通过执行以下操作之一将脚本移至生产环境：

• 使用当前正在制作的脚本的名称保存。
• 配置联络点 呼入联系人用来发起交互的入口点，如电话号码或电子邮件地址。以使用该脚本。在配置联络点之前，您可能需要使用新名称保存脚本。

坐席隧道 webhook 开发和规范

坐席隧道是 CXone 和坐席助手应用程序端点之间的中间件。所有请求和响应都通过它传递。它必须将来自 CXone 的请求转换为坐席助手应用程序可以理解的格式。同样，它必须将坐席助手应用程序的响应转换为 CXone 理解的格式。要完成这些转换，您必须映射CXone和坐席助手应用程序之间的端点。

不需要代理隧道。但是，建议您将其包含在集成中。坐席隧道具有以下优点：

• 它提供了更高的安全性，因为您的数据中心只有一个入口点进行管理。
• 它提供故障转移和负载平衡。
• 它转换 CXone 和坐席助手提供程序系统之间的协议。

如果您的集成中未包含坐席隧道，脚本会将初始 websocket 请求发送到 webhook URL。您必须将脚本配置为以坐席助手应用程序期望的格式发送和接收请求。

以下部分提供：

• 有关自定义坐席助手集成和代理隧道端点的关键事实。
• 来自 CXone 的初始 WebSocket 请求的格式，用于语音交互。
• 语音交互的握手响应格式。
• 聊天交互的 Webhook 连接格式。
• 包含请求的配置参数的格式。

坐席隧道开发的关键事实

以下信息可以帮助您规划和开发坐席隧道端点：

• 文本中继端点必须使用 HTTPS。它不适用于 HTTP。

• 音频中继端点必须是 websocket。它可以是安全的 (WSS) 或不安全的 (WS)。

• 所有坐席隧道端点必须能够从 NICE CXone 网络发送和接收通信。

• 只有二​​进制数据流经 webhook。

• 对于语音交互，从呼叫发送的唯一数据是音频字节。不包括呼叫控制或其他元数据。

• 自定义坐席协助集成支持至少 2000 个并发请求。

• 流传输交互没有过期时间或最大连接时间。自定义坐席助手集成允许呼叫在呼叫处于活动状态时保持开放状态。当呼叫结束时，连接将关闭。

• 当呼叫挂起时，连接保持打开状态，但不会发送任何数据。

• 每个 业务单位 用于管理 CXone环境的技术支持、计费和全局设置的高级组织分组 的联系人 ID 都是唯一的。CXone 有一个 您可以使用的 API 获取有关contactID的实时数据。要查看有关 API 的文档，您需要访问 CXone 开发门户。向您的 CXone 客户代表 询问有关访问的信息。

连接到音频 webhook：初始请求

语音交互必须使用 websocket 请求（WSS 或 WS）。来自 CXone 的初始 websocket 请求遵循以下格式：

 
"authenticationToken": "[header provided in Custom Agent Assist app]",
"executionInfo": {    
      "contactId": 0, 
      "busNo": 0, 
      "requestId": 0,  
      "actionType": "string",  
      "actionId": 0,  
      "scriptName": "string"
},
      "systemTelemetryData": {    
            "consumerProcessHost": "string",  
            "consumerProcessName": "string",  
            "consumerProcessVersion": "string",  
            "inContactClusterAlias": "string",  
            "inContactScriptEngineHost": "string",  
            "consumerMetaData": {  
                  "additionalProp1": "string",
                  "additionalProp2": "string",   
                  "additionalProp3": "string"  
            }
      },
"streamPerspective": "TX/RX/MIX",
"streamsConfiguration": "string",
"appParams": "string",
"appConfig": "string"
			
		

此请求中的参数在此页面的架构部分中进行了描述：

• authenticationToken、streamsConfiguration、appParams 和 appConfig 均在 WebSocketHookInitializeMessage 中描述部分。
• systemTelemetryData 在其自己的部分中描述。
• streamPerspective 在其自己的部分中描述。

连接到音频挂钩：握手响应

如果提供了 authenticationToken，请验证令牌或标头，然后发送握手响应。响应必须遵循CXoneWebSocketMessage类格式：

public class CXOneWebSocketMessage 
{ 
/// Type of command - see CXOneWebSocketCommandType below
public CXOneWebSocketCommandType command { get; set; } 

/// Type of message returned 
public string messageType { get; set; } 

/// Text message 
public string message { get; set; } 

/// Additional parameters 
public object parameters { get; set; } 
)

public enum CXOneWebSocketCommandType
{ 
CONNECT, 
/// When the initial message/auth validation is a success 
CONNECTED, 
/// Message command 
MESSAGE,  
/// Error command, for example when the initial message/auth is invalid 
ERROR
}
		

例如：

{
    "command": "CONNECTED",
    "messageType": "COMMAND",
    "message": "BEGIN AUDIO STREAM"
}
		

使用 websocket 连接的代码示例：

	
WebSocketReceiveResult result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);
if (result.MessageType == WebSocketMessageType.Text)
{ 
    _logger.LogInformation(string.Concat ("MessageType : ", result.MessageType.ToString()));
    if (buffer == null || buffer?.Length == 0)
    {
       return;
    }
    var message = Encoding.UTF8.GetString(buffer, 0, buffer?.Length ?? 0);
    _logger.LogInformation(string.Concat("On Connected", message));
 
    // Validates initial message
    var initialMessage = JsonConvert.DeserializeObject<WebSocketHookInitializeMessage>(message);
    webSocketHookInitilizeMessage = initialMessage;
    param = JsonConvert.SerializeObject(webSocketHookInitializeMessage.appConfig);
 
    // Send response back to  after successful validation
    CXOneWebSocketMessage connectedMessage = new CXOneWebSocketMessage
    {
       command = CXOneWebSocketCommandType.CONNECTED,
       messageType = "COMMAND", 
       message = "BEGIN AUDIO STREAM"
   }; 

    var jsonResponse = Newtonsoft.Json.JsonConvert.SerializeObject(connectedMessage);
    await webSocket?.SendAsync(buffer: new ArraySegment<byte>(array: Encoding.UTF8.GetBytes(jsonResponse),
             offset: 0,
             count: jsonResponse.Length),
             messageType: WebSocketMessageType.Text,
             endOfMessage: true,
             cancellationToken: CancellationToken.None);
}

else if (result.MessageType == WebSocketMessageType.Binary)
{
// You can read the binary voice data
}		
				
		

查看示例代码的图像

本页的架构部分描述了以下内容：

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

连接到文本挂钩

要接收文本聊天数据，您需要连接到文本 webhook。仅接受 HTTP/HTTPS 请求。

每个请求都包含以下对象。仅当您在坐席协助中心中的Custom Agent Assist Endpoints应用程序里添加一个授权标头时，才会发送授权标头。不需要授权标头。

public class WebHooksMessagesRequest
{
	/// If you provide this information in the configuration, it's included.
	public string authorizationHeader { get; set; }
	public int contactId { get; set; }
	public int busNo { get; set; }
	
	
	/// This will be one of the following: patron, agent, or system
	public string participantId { get; set; }
	
	/// Text of the user input (from participantId)
	public string messageBody { get; set; }
	
	/// Other useful data about the message or that are part of the message, such as images or links.
	public object messageData { get; set; }
	
	/// Configuration blob from 坐席协助中心. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}
 	

此代码中的参数在此页面的架构部分中进行了描述：

配置参数

当您在坐席协助中心中配置自定义坐席助手端点应用程序时，您可以添加其他参数。如果您的坐席助手提供程序要求随每个请求发送某些参数，这会有所帮助。但并不是必需的。您添加的任何参数都将在WebHooksMessagesRequest 对象中的agentAssistAppConfig 对象中发送。例如：

"agentAssistAppConfig":{ 
   "param1": "value1", 
   "param2": "value2",
} 
		

CXone 自定义坐席助手集成端点

此处提供的 API 端点是交互式参考，您可以将其与自定义坐席助手集成共同使用，以获取来自 CXone 的请求示例。其他信息（包括原始架构）可在API Swagger 文档中找到。

基于语音的坐席助手应用程序的端点

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server：此端点为您提供了 websocket 服务器请求 URL 的示例。此示例符合 CXone 音频 websocket 挂钩规范 。

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example：此端点为您提供websocket 初始化消息的示例。

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example：此端点为您提供了初始请求和响应的示例。请参阅 WebSocketHookInitializeMessage 架构 和CXoneWebSocketMessage 架构了解详细信息。

基于聊天的坐席助手应用程序的端点

POST ​/agent_assist_text_webhooks​/utterance：此端点为您提供实时接收文本话语 联系人所说或输入的内容。及异步提供坐席帮助的示例。话语可以仅是联系人、仅是坐席或两者。

Schemas

以下部分提供有关与自定义坐席助手端点共同使用的架构信息。在脚本中使用此信息之前，请务必验证最新版本 Swagger 文档 中的架构。

ActionExecutionInfo

包含有关正在执行的操作和脚本的信息。

参数	类型	详细信息
contactId	整数	交互的唯一标识符。
busNo	整数	脚本所在的 CXone 业务部门的 ID 用于管理 CXone环境的技术支持、计费和全局设置的高级组织分组。
requestId	整数	标识特定交互中的每个请求的迭代数。如果您在请求中包含 requestId，则它可以包含在响应中。 这有助于排除故障或解决其他问题。如果 requestID 是唯一值，则可用于在日志文件中查找单个请求/响应。
actionType	字符串	向自定义端点发出请求的操作类型。
actionId	整数	脚本中 Studio 操作的 ID 号码。操作 ID 基于操作添加到脚本的顺序。
scriptName	字符串	发出请求的脚本的路径和名称。

AgentAssistUtterance_V1

包含消息正文和有关消息的信息。

参数	类型	详细信息
contactId	整数 ($int64)	脚本当前实例中联系人的 ID。
busNo	整数 ($int32)	脚本所在的CXone 业务部门的 ID 用于管理 CXone环境的技术支持、计费和全局设置的高级组织分组。
tenantId	字符串	该参数不需要。
participantId	字符串	指示消息是否包含联系人（顾客）、坐席（坐席），或两者（系统）。
messageBody	字符串	消息文本。
messageMetaData		包含保存有关 messageBody 中消息的有用数据参数。如果消息是聊天消息，则此参数还可以保存作为消息的一部分发送的图像、链接或其他内容。
agentAssistAppConfig		包含来自 坐席协助中心 的配置信息。对于具有大型配置 blob 的坐席助手应用程序，此对象可能仅包含配置标识符。 { "agentAssistAppConfig":         { "param1": "value1", "param2": "value2"         } }

CXoneWebSocketCommandType

定义正在发送的命令类型。可能的值包括：

• 连接。
• 已连接，表示初始消息或授权验证成功。
• 消息，用于发送消息时使用。
• 错误，用于初始消息或授权验证无效时。

CXoneWebSocketMessage

包含从坐席协助应用程序发送到CXone的消息。

{ additional parameters

}

StreamPerspective

包含一个具有三个可能值的字符串数组。此参数反映在坐席协助中心中的自定义坐席助手端点应用程序中进行的参与者配置。它定义音频流是否仅包含来自联系人的音频（0 (TX) ）、仅坐席（1 (RX) ）或组合 （2 (MX)）。

SystemTelemetryData

包含与 Studio 脚本操作无关的 API 使用者的数据。该对象包含的数据可能对调试、计费、报告等有用。

{
	< * >:

}

WebSocketHookInitializeMessage

这是来自连接的 websocket 客户端的第一个有效负载的 消息结构，例如 NICE CXone 媒体服务器。

{ parameters

}

{ parameters

}