自訂客服專員助理整合的資源

本頁上的資源提供了您在規劃和實現與 CXone 的自訂客服專員助理整合時所需的資訊。

支援的客服專員應用程式

您可以使用MAX，Agent應用程式是 ，支援與自訂客服專員助理整合一起使用。

音訊串流

音訊封包被編碼為 G711 μlaw 8-bit 8000 kHz 原始音訊。 這與所有 CXone 電話音訊的格式相同。

當您在 Agent Assist Hub 中配置自訂客服專員助理整合時，您可以選擇要傳送到客服專員助理應用程式的音訊。 您可以從聯絡人、客服專員或兩者都傳送音訊。

在每個串流開始時，CXone 向 Custom Agent Assist Endpoint 應用程式傳送一個初始訊息。 初始訊息包括 streamPerspective 參數，其表示音訊流是客服專員或聯絡人：

• "streamPerspective": "RX"：客服專員的電話正在傳輸的音訊：客服專員在說話。
• "streamPerspective": "TX"：客服專員聽到的音訊：聯絡人在說話，或如果互動是在多方通話模式下，則是多個人在說話。
• "streamPerspective": "MIX"：包含客服專員和聯絡人音訊流。

一個單獨的 WebSocket 連接只包含一個方面的音訊。 通常，這是 TX 或 RX，其提供立體聲分離。 在單個單聲道流中混合兩者是可能的。 如果在多方通話模式下發生互動，收到的音訊取決於配置的流視角。 如果視角是 TX，則接收到除客服專員之外的所有參與者的音訊。

如果連接斷開或發生其他問題，如丟包，自訂客服專員助理終點會嘗試恢復與 WebSocket 的連接。 它期望新的驗證握手與它接收到的初始握手相同。

如果聯絡被保留，將會關閉 WebSocket 連接。 當互動恢復時，將啟動新的 WebSocket 連接。 其期望握手方式與原始握手方式相同。

授權

您可以在自訂客服專員助理整合中使用授權。 您的整合可能需要對代理隧道和客服專員助理應用程式中的請求進行驗證。

代理隧道的授權

如果希望代理隧道在請求通過時要求對其進行授權，則需要在設計中包含此要求。 您可以使用任何類型的授權，例如標頭或基於權杖的動態授權。 您必須構建代理隧道才能使用您選擇的授權方法。

您還需要配置 Studio 指令碼來管理授權：

• 對於基於標頭的授權，指令碼必須在其傳送的請求中包括標頭。
• 對於基於權杖的授權，指令碼需要請求一個權杖，將其儲存在緩衝中，並管理權杖逾期資訊。 當權杖逾期時，如果需要，指令碼必須請求新的權杖。 使用 REST API Studio 動作以與驗證伺服器通訊。

如果使用動態授權，如果您還沒有可用授權伺服器，您還需要對其進行設定。 授權伺服器指令碼請求權杖時提供權杖。

客服專員助理應用程式的授權

如果您的客服專員助理提供者需要對所有請求進行授權，您可以在 Agent Assist Hub 中的 Custom Agent Assist Endpoint 應用程式中對其進行配置。

要對自訂整合使用授權，您需要：

• 產生要在自訂客服專員助理整合指令碼中使用的授權標頭。 關於所有適用的配置，請參閱客服專員助理提供者的文件。
• 將所需的標頭新增至 Agent Assist Hub 中的Custom Agent Assist Endpoint 應用程式。 如果您使用客服專員助理應用程式進行文字和語音互動，您需要為每種類型的互動單獨編寫標頭。 有關如何產生標頭的資訊，請參閱您的客服專員助理提供者的文件。

您不需要在指令碼中進行任何配置。 Custom Agent Assist Endpoint 應用程式對標頭傳遞給客服專員助理應用程式的過程進行處理。

CXone 平台配置要求

不需要在 CXone 平台中變更配置，以設定自訂客服專員助理整合。 您可以修改現有指令碼以包括新的客服專員助理應用程式。 但是，根據組織使用新應用程式的方式，可能需要進行一些配置。 您可能需要：

• 為語音或 ACD 聊天建立新的通道 聯絡人與客服專員或機器人互動的方式。 通道可以是語音、電郵、聊天、社交媒體等等。。
• 為 ACD 聊天建立新的聊天設定檔。
• 建立一個或多個 ACD 技能並將它們指派給您希望使用自訂客服專員助理應用程式的客服專員。
• 為新的通道建立聯絡點。
• 修改現有聯絡點 呼入聯絡人用來發起互動的入口點，如電話號碼或電郵地址。以啟動新的指令碼。 不要進行此變更，直到您的自訂客服專員助理整合已完全測試完畢，並已準備投入生產。

序列圖

序列圖顯示了自訂客服助理整合的各個部分如何進行互動以及這些互動發生的順序。 序列圖顯示了互動的時間線，從左上角開始，然後在頁面上來回移動。

序列圖是規劃自訂整合的一個重要部分。 您可以使用序列圖繪製 CXone、Agent Assist Hub、代理隧道和客服專員助理應用程式之間的請求和回應流程。 序列圖還有助於確定 Studio 指令碼必須遵循的流程。

Studio指令碼要求和指南

使用以下樣本為基礎，建立指令碼，將您的客服專員助理應用程式整合到CXone。 傳入和傳出的互動需要單獨的指令碼。 下圖所示為一個傳入指令碼的基本動作：

此圖所示為一個傳出指令碼的基本動作：

在這兩個指令碼中，指令碼參數工作負載Snippet為可選。 只有當您需要向客服專員輔助應用程式傳遞參數時，才需要包括它。

要完成指令碼的配置：

• 將 Custom Agent Assist Endpoints 配置應用程式指派給 Agent Assist 動作。

• 確保可選指令碼參數工作負載Snippet動作包含自訂工作負載 JSON以傳送給客服專員助理提供者。

• 確保Agent Assist動作中的 scriptParams 屬性設定為 {customPayloadJSON}。 只有在包括擁有自訂工作負載的可選 Snippet 動作時才需要此設定。
• 使用 Snippet 動作將初始化 snippet 新增到指令碼中。 您可以藉此來自訂您的客服專員助理應用程式。
• 重新配置動作連接器，確保適當的聯絡流程並糾正任何潛在的錯誤。
• 完成任何額外的指令碼編寫並測試指令碼。

如果您需要在 Studio 中編寫指令碼方面的幫助，與您的 客戶代表 聯絡，請參閱 線上說明中的技術參考指南Studio部分，或訪問{ 9} 社區NICE 的網站。CXone

指令碼參數工作負載 Snippet

此 snippet 定義了 Agent Assist action動作傳遞給客服專員輔助應用程式的資料。 將此代碼新增至指令碼中的 Snippet action動作：

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

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

如果沒有要傳送的自訂工作負載參數，但需要使用指令碼參數 snippet，則可以在 snippet 中包含變數聲明，而無需賦值。 範例：

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

要使用此 snippet：

1. 根據需要改變參數名稱和值，以滿足您的組織和您使用的客服專員輔助應用程式的需要。
2. 將Snippet動作放在指令碼中Agent Assist動作之前。
3. 在 Agent Assist action動作中使用保留 JSON 的變數名稱配置 scriptParams 屬性。 在提供的範例中，這將是 customParamjson。

新的與現有的指令碼

您可以建立與自訂客服專員助理整合一起使用的新指令碼。 您也可以修改現有的指令碼。 不要直接對目前正在生產的指令碼進行修改。 這樣做可能會導致聯絡路由中斷的錯誤。

如果您想使用現有的指令碼，儲存指令碼的副本並對其進行修改。 自訂客服專員助理整合已完全測試完畢並已準備實施時，您可以將修改後的指令碼移回生產中。 透過以下方式之一將指令碼移到生產中：

• 用目前正在生產的指令碼的名稱來儲存它。
• 配置聯絡點 呼入聯絡人用來發起互動的入口點，如電話號碼或電郵地址。來使用該指令碼。 在配置聯絡點之前，您可能希望使用新名稱儲存指令碼。

代理隧道 Webhook 開發與規範

代理隧道是 CXone 與客服專員助理應用程式終點之間的中介軟體。 所有請求和回應都要透過其傳輸。 它必須將來自CXone的請求轉換成客服專員助理應用程式能夠理解的格式。 同樣，它必須將來自客服專員助理應用程式的回應轉換成CXone理解的格式。 為了完成這些轉換，必須對 CXone 和客服專員助理應用程式之間的終點進行對應。

不需要代理隧道。 但是，建議將其包括在您的整合中。 代理隧道提供以下好處：

• 它提供了更高的安全性，因為只有一個進入資料中心的入口點需要管理。
• 它提供容錯移轉和負載均衡。
• 它轉換 CXone 和客服專員助理提供者的系統之間的通訊協定。

如果整合中不包括代理隧道，指令碼會將初始 WebSocket 請求傳送到 Webhook URL。 您必須配置指令碼，以便以客服專員助理應用程式所期望的格式傳送和接收請求。

以下部分提供：

• 重要事實關於自訂客服專員助理整合和代理隧道終點。
• 用於語音互動的 CXone 初始 websocket 請求的格式。
• 用於語音互動的握手回應格式。
• 用於聊天互動的 webhook 連接格式。
• 包含用於請求的配置參數格式。

代理隧道開發的關鍵資訊

以下資訊可以協助您規劃和開發代理隧道終點：

• 文字中繼終點必須使用 HTTPS。 它不會與 HTTP 一起工作。

• 音訊中繼終點必須有 WebSocket。 它可以是安全的 (WSS) 或不安全的 (WS)。

• 所有代理隧道終點必須能夠傳送和接收來自 CXone 網路的通訊。

• 僅二進位資料可以流經 Webhook。

• 對於語音互動，僅從呼叫中傳送的資料是音訊位元組。 不包括呼叫控制或其他中繼資料。

• 自訂客服專員助理整合支援至少 2000 個併行請求。

• 串流互動沒有逾期時間或最長連接時間。 只要呼叫處於活躍狀態，自訂客服專員助理整合允許呼叫保持打開狀態。 當呼叫結束後，連接就會關閉。

• 當呼叫處於保留狀態時，連接保持打開狀態，但不會傳送資料。

• 每 業務單位 用於管理 CXone 環境的技術支援、計費和全域設定的高級組織分組 的聯絡 ID 是唯一的。 CXone 有一個 API，您可以使用 來獲得關於 contactID 的即時資料。 要檢視關於 API 的文件，您需要存取 CXone 開發入口網站。 向 客戶代表 諮詢有關存取的資訊。

連接到 Audio 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"
			
		

本頁的「結構描述」部分中描述了此請求中的參數：

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

連接到 Audio Hook：握手回應

如果提供了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

連接到 Text Hook

要接收文字聊天資料，您需要連接到文字 Webhook。 只接受 HTTP/HTTPS 請求。

每個請求都包括以下物件。 僅在 Agent Assist Hub 的 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 Agent Assist Hub. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}
 	

本頁的「結構描述」部分中描述了此代碼中的參數：

配置參數

當您在 Agent Assist Hub 中配置 Custom Agent Assist Endpoints 應用程式時，可以包含其他參數。 如果您的客服專員助理提供者要求隨每個請求傳送某些參數，這將很有幫助。 它們不是必需的。 您新增的任何參數都將在 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 Hook 規範。

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：此終點為您提供了即時接收基於文字的話語 聯絡人所說或所輸入的內容。和非同步提供客服專員助理的範例。 話語可以僅為聯絡人，也可以僅為客服專員，或者兩者兼而有之。

結構描述

以下各部分提供了與自訂客服專員助理終點一起使用的結構描述之資訊。 在指令碼中使用這些資訊之前，一定要驗證最新版本的Swagger 文件中的結構描述。

ActionExecutionInfo

包含有關執行的動作和指令碼的資訊。

參數	類型	詳細資訊
contactId	整數	互動的唯一識別碼。
busNo	整數	指令碼所在的CXone網路 用於管理 CXone 環境的技術支援、計費和全域設定的高級組織分組的 ID。
requestId	整數	迭代數，用於確定特定互動中的每個請求。 如果您在請求中包括requestId，它可以包括在回應中。 這可以幫助疑難排解或解決其他問題。 如果requestID是唯一的值，它可以用來在記錄檔案中定位單個請求/回應。
actionType	字串	向自訂端點發出請求的動作類型。
actionId	整數	指令碼中Studio動作的 ID 號。 動作 ID 是基於動作被新增到指令碼中的順序。
scriptName	字串	提出請求的指令碼的路徑和名稱。

AgentAssistUtterance_V1

包含訊息主體和有關訊息的資訊。

參數	類型	詳細資訊
contactId	整數 ($int64)	指令碼的當前實例中的聯絡 ID。
busNo	整數 ($int32)	指令碼所在的 CXone 業務單元 用於管理 CXone 環境的技術支援、計費和全域設定的高級組織分組 ID。
tenantId	字串	不需要此參數。
participantId	字串	表示訊息是否包括聯絡人（客戶）、客服專員（客服專員），或兩者（系統）。
messageBody	字串	訊息的文字。
messageMetaData		包含儲存 messageBody 中有關訊息的有用資料的參數。 如果訊息是聊天資訊，此參數還可以儲存圖像、連結或其他作為訊息一部分傳送的內容。
agentAssistAppConfig		包含來自 Agent Assist Hub 的配置資訊。 對於具有大配置 blob 的客服專員助理應用程式，此物件可能只包括配置識別碼。 { "agentAssistAppConfig":         { "param1": "value1", "param2": "value2"         } }

CXoneWebSocketCommandType

定義正在傳送命令的類型。 可能值為：

• 連接。
• 連接初始訊息或授權驗證成功時使用。
• 訊息傳送資訊時使用。
• 錯誤初始訊息或授權驗證無效時使用。

CXoneWebSocketMessage

包含從客服專員助理應用程式傳送到 CXone 的訊息。

{ additional parameters

}

StreamPerspective

包含帶有三個可能值的字串陣列。 該參數反映了在 Agent Assist Hub 中的 Custom Agent Assist Endpoints 應用程式中所進行的參與者配置。 它定義了音訊流是否僅包含聯絡人的音訊 (0 (TX))、僅包含客服專員的音訊 (1 (RX) )，或組合的音訊 (2 (MX))。

SystemTelemetryData

包含與Studio指令碼動作無關的 API 消費者的相關資料。 此物件包含的資料可能對偵錯、計費、報告等有用。

{
	< * >:

}

WebSocketHookInitializeMessage

這是來自連接 WebSocket 用戶端的第一個工作負載的訊息結構，例如 CXone 媒體伺服器。

{ parameters

}

{ parameters

}