Resources for Custom Agent Assist Integrations

The resources on this page provide information you need when planning and implementing a custom agent assist integration with CXone.

Supported Agent Applications

MAX is currently the only supported agent application for use with custom agent assist integrations.

Audio Streaming

Audio packets are encoded as G711 μlaw 8-bit 8000 kHz raw audio. This is the same format as all CXone telephony audio.

When you configure your custom agent assist integration in Agent Assist Hub, you can choose which audio you want to send to the agent assist application. You can send audio from the contact, the agent, or both.

At the start of each stream, CXone sends an initial message to the Custom Agent Assist Endpoint app. The initial message includes the streamPerspective parameter, which indicates whether the audio stream is the agent or the contact:

• "streamPerspective": "RX": The audio being transmitted by the agent's phone: the agent talking.
• "streamPerspective": "TX": The audio that the agent hears: the contact talking, or multiple people if the interaction is in conference mode.
• "streamPerspective": "MIX": Contains both agent and contact audio streams.

An individual websocket connection only contains audio from one perspective. Typically, this is TX or RX, which provides stereo separation. A mix of both in a single mono stream is possible. If an interaction occurs in conference mode, the audio that's received depends on the configured stream perspective. If the perspective is TX, the audio from all participants except the agent is received.

If the connection drops or has other problems, such as lost packets, the custom agent assist endpoint tries to recover the connection to the websocket. It expects a new authentication handshake identical to the initial one it receives.

If a contact is put on hold, the websocket connection is closed. When the interaction resumes, a new websocket connection is initiated. It expects a handshake identical to the original one.

Authorization

You can use authorization in custom agent assist integrations. Your integration may require authentication for requests at the proxy tunnel and at the agent assist application.

Authorization for the Proxy Tunnel

If you want the proxy tunnel to require authorization for requests when they pass through it, you need include this requirement in your design. You can use any kind of authorization, such as headers or dynamic token-based authorization. You must build your proxy tunnel to use the authorization method you've chosen.

You also need to configure your Studio script to manage the authorization: 

• For header-based authorization, the script must include the header in the requests it sends.
• For token-based authorization, the script needs to request a token, store it in cache, and manage the token expiration. When the token expires, the script must request a new token, if needed. Use the REST API Studio action to communicate with the authentication server.

If you use dynamic authorization, you also need to set up an authorization server, if you don't already have one available. The authorization server provides tokens when the script requests them.

Authorization for the Agent Assist Application

If your agent assist provider requires authorization with all requests, you can configure it in the Custom Agent Assist Endpoint app in Agent Assist Hub.

To use authorization with your custom integration, you need to: 

• Generate the authorization header to use in your custom agent assist integration scripts. Refer to the documentation for your agent assist provider for all applicable configurations.
• Add the required headers to the Custom Agent Assist Endpoint app in Agent Assist Hub. If you use the agent assist application with text and voice interactions, you need separate headers for each type of interaction. Refer to the documentation for your agent assist provider for information about how to generate headers.

You don't need to configure anything in your script. The Custom Agent Assist Endpoint app handles passing the header to the agent assist application.

CXone Platform Configuration Requirements

There are no required configuration changes in the CXone platform to set up a custom agent assist integration. You can modify existing scripts to include the new agent assist application. However, some configuration may be needed depending on how your organization is using the new application. You may need to: 

• Create a new channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. for voice or ACD chat.
• Create a new chat profile for ACD chat.
• Create one or more ACD skills and assign them to the agents you want the custom agent assist application to be available for.
• Create a point of contact for a new channel.
• Modify an existing point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. to launch a new script. Do not make this change until your custom agent assist integration is fully tested and ready to put into production.

Sequence Diagrams

Sequence diagrams show how various parts of a custom agent assist integration interact and the order those interactions take place. They show a timeline of an interaction, starting in the top left corner, then moving back and forth down the page.

Sequence diagrams are an important part of planning your custom integration. You can use them to map out the flow of requests and responses between CXone, Agent Assist Hub, the proxy tunnel, and your agent assist application. They may also be helpful in determining the flow your Studio script must follow.

Studio Script Requirements and Guidelines

Use the following samples as a foundation to create the scripts to integrate your agent assist application into CXone. Inbound and outbound interactions require separate scripts. The following image shows the essential actions for an inbound script:

This image shows the essential actions for an outbound script: 

In both scripts, the Script Param Payload Snippet is optional. You only need to include it if you need to pass parameters to the agent assist application.

To complete the configuration of your script: 

• Assign the Custom Agent Assist Endpoints configuration app to the Agent Assist action.

• Ensure that the optional Script Param Payload Snippet action contains the custom payload JSON to send to the agent assist provider.

• Ensure that the scriptParams property in the Agent Assist action is set to {customPayloadJSON}. This is only required if you include the optional Snippet action with custom payload.
• Add initialization snippets to the script using Snippet actions. You can do this to customize your agent assist application.
• Reconfigure the action connectors to ensure proper contact flow and correct any potential errors.
• Complete any additional scripting and test the script.

If you need assistance with scripting in Studio, contact your CXone Account Representative, see the Technical Reference Guide section in the Studio online help, or visit the NICE CXone Community site.

Script Params Payload Snippet

This snippet defines the data passed to the agent assist application by the Agent Assist actionaction. Add this code to a Snippet actionaction in your script:

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

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

If there are no custom payload parameters to send but the Script Parameters snippet is required, you can include the variable declarations in the snippet without assigning any values. For example: 

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

To use this snippet: 

1. Change the parameter names and values as needed to meet the needs of your organization and the agent assist application you use.
2. Place the Snippet action in the script before the Agent Assist action.
3. Configure the scriptParams property in the Agent Assist actionaction with the name of the variable that holds the JSON. In the example provided, this would be customParamjson.

New versus Existing Scripts

You can create new scripts to use with your custom agent assist integration. You can also modify existing scripts. Do not make changes directly to scripts that are currently in production. Doing this may result in errors that interrupt contact routing.

If you want to use an existing script, save a copy of the script and modify that. When your custom integration is fully tested and ready for implementation, you can move the modified script back into production. Move a script into production by doing one of the following:

• Saving it with the name of a script that's currently in production.
• Configure a point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. to use the script. You may want to save the script with a new name before configuring the point of contact.

Proxy Tunnel Webhook Development and Specifications

The proxy tunnel is the middle ware between CXone and your agent assist application's endpoint. All requests and responses pass through it. It must translate requests from CXone into a format that the agent assist application understands. Similarly, it must translate responses from the agent assist application into the format that CXone understands. To accomplish these translations, you must map the endpoints between CXone and the agent assist application.

The proxy tunnel is not required. However, it's recommended that you include it in your integration. The proxy tunnel provides the following benefits: 

• It provides increased security because there's a single entry point into your data center to manage.
• It provides failover and load balancing.
• It translates protocols between CXone and the agent assist provider's system.

If you don't include a proxy tunnel in your integration, the script sends the initial websocket request to the webhook URLs. You must configure your script to send and receive requests in the format expected by the agent assist application.

The following sections provide: 

• Key facts about custom agent assist integrations and the proxy tunnel endpoints.
• Format of the initial websocket request from CXone for voice interactions.
• Format of the handshake response for voice interactions.
• Format for the webhook connection for chat interactions.
• Format for including configuration parameters with requests.

Key Facts for Proxy Tunnel Development

The following information can help you plan and develop the proxy tunnel endpoint: 

• The text relay endpoint must use HTTPS. It will not work with HTTP.

• The audio relay endpoint must be a websocket. It can be secured (WSS) or unsecured (WS).

• All proxy tunnel endpoints must be able to send and receive communication from the NICE CXone network.

• Only binary data flows through the webhook.

• For voice interactions, the only data sent from the call are audio bytes. No call control or other metadata is included.

• Custom agent assist integrations support at least 2000 concurrent requests.

• There isn't an expiration time or a maximum connection time for streaming an interaction. Custom agent assist integrations allow calls to remain open as long as the call is active. When the call ends, the connection closes.

• When a call is placed on hold, the connection remains open, but no data is sent.

• Contact IDs are unique per business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment. CXone has an API you can use to obtain real-time data about the contactID. To view the documentation about the API, you need access to the CXone Dev Portal. Ask your CXone Account Representative for information about access.

Connect to Audio Webhook: Initial Request

Voice interactions must use websocket requests (WSS or WS). The initial websocket request from CXone follows this format:

 
"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"
			
		

The parameters in this request are described in the Schemas section of this page:

• authenticationToken, streamsConfiguration, appParams, and appConfig are all described in the WebSocketHookInitializeMessage section.
• systemTelemetryData is described in its own section.
• streamPerspective is described in its own section.

Connect to Audio Hook: Handshake Response

If authenticationToken is provided, validate the token or header, then send a the handshake response. The response must follow the CXoneWebSocketMessage class format: 

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
}
		

For example:

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

An example of code for connecting with 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
}		
				
		

View an image of the example code

The Schemas section of this page describes the following:

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

Connect to the Text Hook

To receive text chat data, you need to connect to the text webhook. Only HTTP/HTTPS requests are accepted.

Every request includes the following objects. The authorization header is sent only if you add one in the Custom Agent Assist Endpoints app in Agent Assist Hub. Authorization headers are not required.

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; }
}
 	

The parameters in this code are described in the Schemas section on this page.

Configuration Parameters

You can include additional parameters when you configure the Custom Agent Assist Endpoint app in Agent Assist Hub. This is helpful if your agent assist provider requires certain parameters to be sent with each request. They're not required. Any parameters that you add are sent in the agentAssistAppConfig object in the the WebHooksMessagesRequest object. For example: 

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

CXone Endpoints for Custom Agent Assist Integrations

The API endpoints provided here are interactive references that you can use with your custom agent assist integration to obtain examples of requests from CXone. Additional information, including the original schemas, is available in the API's Swagger documentation.

Endpoints for Voice-Based Agent Assist Applications

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server: This endpoint gives you an example of a websocket server request URL. This example conforms to the CXone audio websocket hook specification.

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example: This endpoint gives you an example of a websocket initialization message.

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example: This endpoint gives you an example of the initial request and response. See the WebSocketHookInitializeMessage schema and the CXoneWebSocketMessage schema for details.

Endpoint for Chat-Based Agent Assistant Applications

POST ​/agent_assist_text_webhooks​/utterance: This endpoint gives you an example of receiving text-based utterances What a contact says or types. in real time and of providing agent assistance asynchronously. Utterances can be the contact only, the agent only, or both.

Schemas

The following sections provide information about the schemas used with the custom agent assist endpoints. Always verify the schemas in the latest version of the Swagger document before using this information in your scripts.

ActionExecutionInfo

Contains information about the action and script being executed.

Parameter	Type	Details
contactId	Integer	The unique identifier for the interaction.
busNo	Integer	The ID of the CXonebusiness unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment where the script is located.
requestId	Integer	An iterative number that identifies each request in a particular interaction. If you include the requestId in requests, it can be included in the responses. This can help helpful for troubleshooting or other problem-solving. If requestID is a unique value, it can be used to locate a single request/response in log files.
actionType	String	The action type that makes the request to the custom endpoint.
actionId	Integer	The ID number of the Studio action within the script. Action IDs are based on the order the actions were added to the script.
scriptName	String	The path and name of the script making the request.

AgentAssistUtterance_V1

Contains the message body and information about the message.

Parameter	Type	Details
contactId	integer ($int64)	The ID of the contact in the current instance of the script.
busNo	integer ($int32)	The ID of the CXone business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment where the script is located.
tenantId	string	This parameter is not needed.
participantId	string	Indicates whether the message includes the contact (Patron), the agent (Agent), or both (System).
messageBody	string	The text of the message.
messageMetaData		Contains parameters that hold useful data about the message in messageBody. If the message is a chat message, this parameter can also hold images, links, or other content sent as part of the message.
agentAssistAppConfig		Contains configuration information from Agent Assist Hub. For agent assist applications with large configuration blobs, this object may include only the configuration identifier. { "agentAssistAppConfig":         {           "param1": "value1",           "param2": "value2"         } }

CXoneWebSocketCommandType

Defines the type of command is being sent. Possible values are: 

• CONNECT .
• CONNECTED for when the initial message or authorization validation is successful.
• MESSAGE for use when sending a message.
• ERROR for use when the initial message or authorization validation is invalid.

CXoneWebSocketMessage

Contains the message sent to CXone from the agent assist application.

{
	additional parameters

}

StreamPerspective

Contains a string array with three possible values. This parameter reflects the Participants configuration made in the Custom Agent Assist Endpoints app in Agent Assist Hub. It defines whether the audio stream contains audio from the contact only (0 (TX)), the agent only (1 (RX) ), or a combination (2 (MX)).

SystemTelemetryData

Contains data about the API consumer that is not associated with the Studio script action. The data this object contains may be useful for debugging, billing, reports, and so on.

{
	< * >:

}

WebSocketHookInitializeMessage

This is the message structure for the first payload from a connecting websocket client, such as the NICE CXone media server.

{
	parameters

}

{
	parameters

}