Ressources pour les Intégrations Custom Agent Assist

Les ressources de cette page fournissent les informations nécessaires à la planification et l'implémentation d'une intégration personnalisée d'Agent Assist avec NiCE CXone.

Applications Agent prises en charge

MAX et les applications NiCE CXone Agent Workspace (Agent) sont prises en charge pour une utilisation avec des intégrations d'assistance aux agents personnalisées. Dans les applications NiCE CXone Agent Workspace (Agent), les intégrations d'assistance aux agents personnalisées s'ouvrent toujours dans un nouvel onglet.

Streaming audio

Les paquets audio sont codés au format audio brut G.711 μlaw, 8 bits, 8 000 kHz. Ce format est identique à celui de tout audio téléphonique NiCE CXone.

Lorsque vous configurez l'intégration personnalisée d'Agent Assist dans Agent Assist Hub, vous pouvez choisir les données audio à envoyer à l'application Agent Assist. Vous pouvez envoyer les données audio depuis le contact, l'agent ou les deux.

Au début de chaque flux, NiCE CXone envoie un message initial à l'application Terminal Custom Agent Assist. Le message initial inclut le paramètre streamPerspective, qui indique si le flux audio est celui de l'Agent ou du contact :

• "streamPerspective": "RX" : audio transmis par le téléphone de l'agent : l'agent qui parle.
• "streamPerspective": "TX" : L'audio que l'Agent entend : le contact qui parle, ou Multiple gens, si l'interaction est en mode conférence.
• "streamPerspective": "MIX": contient à la fois les flux audio de l'agent et du contact.

Une connexion websocket individuelle ne contient les données audio que d'une seule perspective. En règle générale, il s'agit de TX ou RX, qui assure la séparation stéréo. Un mélange des deux dans un flux mono unique est possible. En cas d'interaction en mode conférence, les données audio qui sont reçues dépendent de la perspective du flux configuré. Si la perspective est TX, l'audio de tous les Participants à l'exception de l'Agent est reçu.

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.

Si un contact est mis en attente, la connexion du websocket est fermée. Lorsque l'interaction reprend, une nouvelle connexion de websocket est lancée. La procédure de négociation doit être identique à celle d'origine.

Autorisation

Vous pouvez utiliser l'autorisation dans les intégrations personnalisées d'Agent Assist. Votre intégration peut nécessiter l'authentification pour les requêtes au niveau du tunnel de proxy et de l'application Agent Assist.

Autorisation du tunnel de proxy

Si vous souhaitez que le tunnel de proxy demande une autorisation pour les requêtes qui le traversent, vous devez le spécifier au niveau de la conception. Vous pouvez utiliser n'importe quel type d'autorisation, comme les en-têtes ou l'autorisation dynamique basée sur des jetons. Vous devez créer votre propre tunnel de proxy pour utiliser la méthode d'autorisation choisie.

Vous devez également configurer votre script Studio pour gérer l'autorisation :

• Pour l'autorisation basée sur l'en-tête, le script doit inclure l'en-tête dans les requêtes qu'il envoie.
• Pour l'autorisation basée sur les jetons, le script doit demander un jeton, le stocker en mémoire cache et en gérer les délais d'expiration. Lorsque le jeton expire, le script doit en demander un nouveau, si nécessaire. Utilisez l’REST API Studio action pour communiquer avec le serveur d'authentification.

Si vous utilisez l'autorisation dynamique, vous devez également définir un serveur d'autorisation, si vous n'en disposez pas encore. Le serveur d'autorisation fournit des jetons lorsque le script les demande.

Autorisation pour l'application Agent Assist

Si votre fournisseur Agent Assist nécessite une autorisation pour chaque requête, vous pouvez le configurer depuis l'application Custom Agent Assist Endpoint dans Agent Assist Hub.

Pour utiliser l'autorisation avec votre intégration personnalisée, vous devez :

• Générer l'en-tête d'autorisation à utiliser dans vos scripts d'intégration Agent Assist personnalisés. Reportez-vous à la documentation de votre fournisseur Agent Assist pour toutes les configurations applicables.
• Ajoutez les en-têtes requis à l'application Terminal Custom Agent Assist dans Agent Assist Hub. Si vous utilisez l'application Agent Assist avec des interactions texte et voix, vous devez séparer les en-têtes pour chaque type d'interaction. Reportez-vous à la documentation de votre fournisseur Agent Assist pour plus d'informations sur la génération des en-têtes.

Vous n'avez pas besoin de configurer quoi que ce soit dans votre script. L'application Custom Agent Assist Endpoint gère le transfert de l'en-tête à l'application Agent Assist.

NiCE CXone Exigences de configuration de la plateforme

Il n'y a pas de modifications de configuration requise dans la plateforme NiCE CXone pour configurer une intégration Agent Assist personnalisée. Vous pouvez modifier les scripts existants pour inclure la nouvelle application Agent Assist. Cependant, il peut être nécessaire de configurer l'application pour s'adapter de façon plus précise au mode de fonctionnement de votre organisation. Vous devrez peut-être :

• Créez un canal Divers moyens de communication vocale et numérique qui facilitent les interactions avec les clients dans un centre de contacts. pour la voix ou le chat ACD.
• Créer un nouveau profil de chat pour le chat ACD.
• Créer une ou plusieurs compétences ACD et les affecter aux agents pour lesquels vous souhaitez que l'application d'assistance Agent personnalisée soit disponible.
• Créer un point de contact pour un nouveau canal.
• Modifier un point de contact point d’entrée qu’un contact entrant utilise pour amorcer une interaction, comme un numéro de téléphone ou une adresse courriel. existant pour lancer un nouveau script. Ne faites pas cette modification avant que votre intégration d'agent personnalisé soit entièrement testée et prête à entrer en production.

Diagrammes de séquence

Les diagrammes séquentiels indiquent comment les différentes parties d'une intégration d'agent personnalisé interagissent et l'ordre appliqué pour ces séquences. Elles affichent une chronologie d'une interaction, commençant dans le coin supérieur gauche, puis se déplaçant d'avant en arrière vers le bas de la Page.

Les diagrammes séquentiels constituent un élément important de la planification de votre intégration personnalisée. Vous pouvez les utiliser pour mapper le flux de requêtes et de réponses entre NiCE CXone, Agent Assist Hub, le tunnel de proxy et votre application Agent Assist. Ils peuvent également être utiles pour déterminer le flux que doit suivre votre script Studio.

Studio Critères et directives pour le script

Utilisez les exemples suivants comme base pour créer les scripts permettant d'intégrer votre application d'assistance aux agents dans NiCE CXone. Les interactions entrantes et sortantes nécessitent des scripts différents. L'image suivante illustre les actions essentielles pour un script entrant :

Cette image indique les actions essentielles pour un script sortant :

Dans les deux scripts, l'Extrait de Charge utile de paramètre de script est en option. Vous ne devez l'inclure que si vous devez transférer des paramètres à l'application d'assistance aux agents.

Pour terminer la configuration de votre script :

• Attribuez l'application de configuration Custom Agent Assist Endpoints à l'action Agent Assist.

• Assurez-vous que l'action en option Script Param Payload Snippet contient le JSON de charge utile personnalisée à envoyer au fournisseur Agent Assist.

• Assurez-vous que la propriété scriptParams de l'action Agent Assist est définie sur {customPayloadJSON}. Cela est requis uniquement si vous incluez l'action Extrait en option avec une charge utile personnalisée.

• Ajoutez des extraits d'initialisation au script à l'aide de Extrait actions.Cela permet de personnaliser votre application Agent Assist.
• Reconfigurez les connecteurs d'Action pour garantir le bon déroulement du flux de contact et corriger les erreurs potentielles éventuelles.
• Complétez le script s’il y a lieu et testez-le.

Si vous avez besoin d'aide concernant les scripts dans Studio, contactez votre représentant de compte, consultez la section Référence Technique Guide de l'aide en ligne Studio, ou visitez le site NiCE Community pour NiCE CXone.

Extrait de la Charge utile des paramètres du script

Cet extrait définit les données transmises à l'application d'assistance à l'agent par l'Agent Assist action. Ajoutez ce code à une Snippet action dans votre script :

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

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

S'il n'y a aucun paramètre de charge utile personnalisée à envoyer, mais que l'extrait Paramètres de script est requis, vous pouvez inclure les déclarations de Variable dans l'extrait sans attribuer de valeurs. Par exemple :

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

Pour utiliser cet extrait :

1. Modifiez les noms et les valeurs des paramètres en fonction des besoins de votre organisation et de l'application d'assistance d'agent que vous utilisez.
2. Placez l'action Snippet dans le script avant l'action Agent Assist.
3. Configurez la propriété scriptParams dans l'Agent Assist action avec le nom de la variable qui contient le JSON. Dans l'exemple fourni, il s'agirait de customParamjson.

Scripts nouveaux et existants

Vous pouvez créer des scripts pour votre intégration Agent Assist personnalisée.Vous pouvez également modifier les scripts existants. Ne modifiez pas directement les scripts en cours de production. Sinon vous risquez de créer des erreurs qui vont interrompre le routage des contacts.

Si vous voulez utiliser un script existant, enregistrez une copie de ce script et modifiez-la. une fois votre intégration personnalisée entièrement testée et prête à être implémentée, vous pouvez remettre le script modifié en production. Pour mettre le script en production, procédez de l'une des façons suivantes :

• l'enregistrant sous le nom d'un script actuellement en production ;
• configurant un point de contact point d’entrée qu’un contact entrant utilise pour amorcer une interaction, comme un numéro de téléphone ou une adresse courriel. pour utiliser le script. Il est conseillé d'enregistrer le script sous un nouveau nom avant de configurer le point de contact.

Développement de webhooks pour le tunnel de proxy et spécifications

Le tunnel de proxy est un logiciel intermédiaire, placé entre NiCE CXone et le terminal de votre application Agent Assist. Toutes les requêtes et les réponses y transitent. Il doit transférer les requêtes de NiCE CXone à un format que l'application Agent Assist comprend. De même, il doit convertir les réponses de l'application Agent Assist à un format que NiCE CXone comprend. Pour réaliser ces conversions, vous devez mapper les terminaux entre NiCE CXone et l'application Agent Assist.

Le tunnel proxy n'est pas requis. Toutefois, il est recommandé de l'inclure dans votre intégration. Le tunnel proxy présente les avantages suivants :

• Il renforce la sécurité, car il n'y a qu'un seul point d'entrée à gérer pour votre centre de données.
• Il assure la tolérance des pannes et l'équilibrage des charges.
• Il convertit les protocoles entre NiCE CXone et le fournisseur du système d'assistance à l'agent.

Si vous n'incluez pas de tunnel proxy dans votre intégration, le script envoie la demande websocket initiale aux URL de webhook. Vous devez configurer votre script pour envoyer et recevoir des requêtes à un format lisible par l'application d'assistance aux agents.

Les sections suivantes sont :

• Faits clés sur les intégrations personnalisées Agent Assist et les points de terminaison du tunnel proxy.
• Format de la demande websocket initiale de NiCE CXone pour les interactions vocales.
• Format de la réponse de négociation pour les interactions voix.
• Format pour la connexion webhook pour les interactions chat.
• Format pour inclure des paramètres de configuration avec les demandes.

Faits clés pour le développement du tunnel Proxy

Les informations suivantes peuvent vous aider à planifier et développer le terminal de tunnel de proxy :

• Le terminal de relais de texte doit utiliser HTTPS. Il ne fonctionne pas avec HTTP.

• Le terminal de relais audio doit être un websocket. Il peut être sécurisé (WSS) ou non (WS).

• Tous les terminaux du tunnel de proxy doivent pouvoir communiquer dans les deux sens avec le réseau NiCE CXone.

• Seules les données binaires transitent à travers le webhook.

• Pour les interactions vocales, les seules données envoyées depuis l'appel sont des octets audio. Aucun contrôle d'appel ou autres métadonnées ne sont inclus.

• Les intégrations personnalisées d'Agent Assist prennent en charge au moins 2 000 requêtes concurrentes.

• Il n'y a pas de date/heure limite de connexion ou d'expiration pour les flux d'interactions. Les intégrations personnalisées d'Agent Assist permettent aux appels de rester ouverts aussi longtemps qu'ils sont actifs. Lorsque l'appel se termine, la connexion s'interrompt.

• Si un appel est mis en attente, la connexion reste ouverte, mais il n'y a pas d'envoi de données.

• Les id de contact sont uniques par Locataire Regroupement organisationnel de haut niveau utilisé pour gérer le soutien technique, la facturation et les paramètres globaux de votre système NiCE CXone.. NiCE CXone dispose d'une API que vous pouvez utiliser pour obtenir des données en temps réel sur le contactID. Pour consulter la documentation relative à l'API, vous devez disposer d'un accès au NiCE CXone Dev Portal. Demandez à votre représentant de compte des informations concernant l'accès.

Connecter au Webhook audio : Demande initiale

Les interactions vocales doivent utiliser des requêtes websocket (WSS ou WS). La requête de websocket initiale de NiCE CXone applique le format suivant :

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

Les paramètres de cette requête sont décrits dans la section Schémas de cette page :

• authenticationToken, streamsConfiguration, appParams, et appConfig sont tous décrits dans la section WebSocketHookInitializeMessage.
• systemTelemetryData est décrit dans sa propre section.
• streamPerspective est décrit dans sa propre section.

Connexion à audio Hook : Réponse de handshake

Si authenticationToken est fourni, validez le jeton ou l'en-tête, puis envoyez la réponse de négociation. La réponse doit appliquer le format de classe 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
}
		

Par exemple :

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

Exemple de code de connexion par 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
}		
				
		

Voir une image de l'exemple de code

La section Schémas de cette page décrit ce qui suit :

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

Connexion au hook texte

Pour recevoir les données texte de chat, connectez-vous au webhook texte seules les demandes HTTP/HTTPS sont acceptées.

Toutes les requêtes incluent les objets suivants. L’en-tête d’autorisation est envoyé uniquement si vous en ajoutez un dans l’application Custom Agent Assist Endpoints dans Agent Assist Hub. Les en-têtes d'autorisation ne sont pas requis.

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; }
	public string tenantId { 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; }
}
 	

Les paramètres de ce code sont décrits dans la section Schémas de cette page.

Paramètres de configuration

Vous pouvez inclure des paramètres supplémentaires lorsque vous configurez l'application Custom Agent Assist Endpoints dans Agent Assist Hub. Cela devient utile si votre fournisseur Agent Assist demande à envoyer certains paramètres avec chaque requête. Ils ne sont pas requis. Les paramètres que vous ajoutez, le cas échéant, sont envoyés dans l'objet agentAssistAppConfig appartenant lui-même à l'objet WebHooksMessagesRequest. Par exemple :

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

Terminaux NiCE CXone pour les Intégrations personnalisées d'Agent Assist

Les terminaux d'API fournis ici sont des références interactives que vous pouvez utiliser avec votre intégration personnalisée d'Agent Assist pour obtenir des exemples de requête de NiCE CXone. Des Informations supplémentaires, y compris les schémas d'origine, sont disponibles dans le documentation Swagger de l'API.

Points de terminaison pour les Applications Agent Assist basées sur la Voix

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server : ce terminal donne un exemple d'URL de requête de serveur websocket. Cet exemple est conforme à la NiCE CXone spécification de hook de websocket audio.

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example : ce terminal donne un exemple de message d'initialisation de websocket.

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example : ce terminal donne un exemple de requête initiale et de réponse. Consultez le WebSocketHookInitializeMessage schéma et le CXoneWebSocketMessage schéma pour plus de détails.

Terminal pour les Applications d'Adjoint(e) aux agents basées sur le chat

POST ​/agent_assist_text_webhooks​/utterance : ce terminal vous donne un exemple de réception d'énoncés Ce qu’un contact dit ou tape. en temps réel et d'assistance asynchrone de l'agent. Les énoncés peuvent provenir uniquement du contact, uniquement de l'Agent, ou des deux.

Schémas

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

Contient des informations sur l’action et le script en cours d’exécution.

Paramètre	Type	Détails
contactId	Entier	L’identifiant unique de l’interaction.
busNo	Entier	L'ID de l'NiCE CXoneunité commerciale Regroupement organisationnel de haut niveau utilisé pour gérer le soutien technique, la facturation et les paramètres globaux de votre système NiCE CXone. dans laquelle se trouve le script.
requestId	Entier	Un numéro itératif qui identifie chaque demande dans une interaction particulière. Si vous incluez un requestId dans les demandes, il peut être inclus dans les réponses. Cela peut être utile pour le dépannage ou la résolution de problèmes. Si requestID est une valeur unique, il peut servir à localiser une demande/réponse dans les fichiers journaux.
actionType	Chaîne de caractères	Le type d’action qui effectue la demande au point de terminaison personnalisé.
actionId	Entier	Le numéro d’identification de l’action Studio au sein du script. Les identifiants d’actions se fondent sur l’ordre dans lequel les actions ont été ajoutées au script.
scriptName	Chaîne de caractères	Le chemin et le nom du script effectuant la demande.

AgentAssistUtterance_V1

Contient le corps du message et des informations sur le message.

Paramètre	Type	Détails
contactId	entier ($int64)	L'id du contact dans l'instance actuelle du script.
busNo	entier ($int32)	L'ID de l'NiCE CXone unité commerciale Regroupement organisationnel de haut niveau utilisé pour gérer le soutien technique, la facturation et les paramètres globaux de votre système NiCE CXone. où se trouve le script.
tenantId	chaîne de caractères	L'id du locataire NiCE CXone où se trouve le script.
participantId	chaîne de caractères	Indique si le message inclut le contact (Usager), l’agent (Agent) ou les deux (Système).
messageBody	chaîne de caractères	Le texte du message.
messageMetaData		Contient des paramètres ayant des données utiles sur le message dans messageBody. Si le message est un message clavardage, ce paramètre peut également contenir des Images, des liens ou tout autre contenu envoyé dans le cadre du message.
agentAssistAppConfig		Contient des informations de configuration provenant de Agent Assist Hub. Pour les applications d'assistance Agent comportant des blocs de configuration de grande taille, cet objet peut inclure uniquement l'identifiant de configuration. { "agentAssistAppConfig":         {           "param1": "value1",           "param2": "value2"         } }

CXoneWebSocketCommandType

Définit le type de commande qui est envoyé. Les valeurs possibles sont :

• CONNECT .
• CONNECTED lorsque le message initial ou la validation d'autorisation aboutit.
• MESSAGE à utiliser lors de l'envoi d'un message.
• Erreur à utiliser lorsque le message initial ou la demande d'autorisation n'est pas valide.

CXoneWebSocketMessage

Contient le message envoyé à NiCE CXone depuis l'application Agent Assist.

{
	additional parameters

}

StreamPerspective

Contient un tableau de chaînes avec trois valeurs possibles. This paramètre reflète la configuration des Participants effectuée dans l'application Custom Agent Assist Endpoints dans Agent Assist Hub. Il définit si le flux audio contient des données audio du contact uniquement (0 (TX)), de l'agent seul (1 (RX) ) ou d'une combinaison des deux (2 (MX)).

SystemTelemetryData

Contient des données relatives à l’usager de l’API qui n’est pas associé avec l’action de script Studio. Les données que contient cet objet peuvent être utiles pour déboguer, facturer, créer des rapports, etc.

{
	< * >:

}

WebSocketHookInitializeMessage

Voici la structure du message pour la première charge utile provenant d'un client websocket qui se connecte, tel que le serveur média NiCE CXone.

{
	parameters

}

{
	parameters

}