Informatiebronnen voor Custom Agent Assist Integrations

De informatiebronnen op deze pagina bieden u de informatie die u nodig hebt wanneer u een Custom Agent Assist Integration met CXone gaat plannen en implementeren.

Ondersteunde agentapplicaties

MAX is momenteel de enige agentapplicatie die wordt ondersteund voor gebruik met Custom Agent Assist Integrations.

Audiostreaming

Audiopakketten worden gecodeerd als G711 μlaw 8-bit 8000 kHz raw audio. Dit is dezelfde indeling als alle telefonieaudio in CXone.

Wanneer u uw Custom Agent Assist Integration in Agent Assist Hub configureert, kunt u kiezen welke audio naar de agentassistentie-applicatie moet worden verzonden. U kunt audio verzenden van het contact, de agent of allebei.

Bij de start van elke stream verzendt CXone een eerste bericht naar de Custom Agent Assist Endpoint-app. Het eerste bericht bevat streamPerspective-parameter, die aangeeft of de audiostream van de agent of het contact is:

• "streamPerspective": "RX": de audio die door de telefoon van de agent wordt geschakeld: de agent is aan het woord.
• "streamPerspective": "TX": de audio die de agent hoort: het contact is aan het woord, of meerdere contactpersonen spreken, als de interactie plaatsvindt in conferentiemodus.
• "streamPerspective": "MIX": bevat audiostreams van zowel de agent als het contact.

Een individuele websocketverbinding bevat slechts audio vanuit één perspectief. Meestal is dit TX of RX, wat zorgt voor stereoscheiding. Een mix van beide is mogelijk is een enkelvoudige monostream. Als een interactie plaatsvindt in conferentiemodus, hangt de ontvangen audio af van het geconfigureerde streamperspectief. Als het perspectief TX is, wordt de audio van alle deelnemers behalve de agent ontvangen.

Als de verbinding wegvalt of andere problemen heeft, zoals verloren pakketten, probeert het aangepaste agentassistenteindpunt de verbinding met de websocket te herstellen. Het verwacht een nieuwe authenticatiehanddruk die identiek is aan de aanvankelijke handdruk die het ontvangt.

Als een contact in de wacht wordt gezet, wordt de websocketverbinding gesloten. Wanneer de interactie wordt hervat, wordt een nieuwe websocketverbinding gestart. Het verwacht een handdruk die identiek is aan de oorspronkelijke handdruk.

Autorisatie

U kunt autorisatie gebruiken in Custom Agent Assist Integrations. Uw integratie vereist mogelijk authenticatie voor verzoeken die bij de proxytunnel en de agentassistentie-applicatie worden gedaan.

Autorisatie voor de proxytunnel

Als u wilt dat de proxytunnel autorisatie vereist voor verzoeken wanneer deze door de proxytunnel gaan, moet u hiermee rekening houden in uw ontwerp. U kunt elke vorm van autorisatie gebruiken, zoals headers of dynamische autorisatie op basis van tokens. U moet uw proxytunnel configureren om de gekozen autorisatiemethode te gebruiken.

Daarnaast moet u uw Studio-script configureren om de autorisatie te beheren:

• Voor autorisatie op basis van headers moet het script de header toevoegen aan de verzoeken die het verzendt.
• Voor autorisatie op basis van tokens moet het script een token aanvragen, dit opslaan in het cachegeheugen en de vervaldatum van het token beheren. Als het token verloopt, moet het script een nieuw token aanvragen, indien nodig. Gebruik de REST API Studio-actie om te communiceren met de authenticatieserver.

Als u dynamische autorisatie gebruikt, moet u ook een autorisatieserver opzetten indien er nog geen beschikbaar is. De autorisatieserver levert tokens wanneer het script deze aanvraagt.

Autorisatie voor de agentassistentie-applicatie

Als de provider van uw agentassistentie autorisatie vereist voor alle verzoeken, kunt u deze configureren in de Custom Agent Assist Endpoint-app in Agent Assist Hub.

Om autorisatie te gebruiken met uw aangepaste integratie moet u het volgende doen:

• Genereer de autorisatieheader voor gebruik in de scripts van uw Custom Agent Assist Integration. Raadpleeg de documentatie voor uw provider van agentassistentie voor alle toepasselijke configuraties.
• Voeg de vereiste headers toe aan de Custom Agent Assist Endpoint-app in Agent Assist Hub. Als u de agentassistentie-applicatie gebruikt met tekst- en spraakinteracties, hebt u voor elk interactietype aparte headers nodig. Raadpleeg de documentatie voor uw provider van agentassistentie voor informatie over het genereren van headers.

U hoeft niets te configureren in uw script. De Custom Agent Assist Endpoint-app stuurt de header naar de agentassistentie-applicatie.

Vereisten voor de configuratie van het CXone-platform

De configuratie van het CXone-platform hoeft niet gewijzigd te worden om een Custom Agent Assist Integration in te stellen. U kunt bestaande scripts aanpassen om de nieuwe agentassistentie-applicatie op te nemen. Het is mogelijk dat u sommige configuratietaken moet uitvoeren, afhankelijk van hoe uw organisatie de nieuwe applicatie gebruikt. U moet mogelijk het volgende doen:

• Maak een nieuw kanaal Een manier waarop contacten kunnen communiceren met agents of bots, zoals spraak (telefoon), e-mail, chat, social media enzovoort. voor spraak- of ACD-chat.
• Maak een nieuw chatprofiel voor ACD-chat.
• Maak een of meerdere ACD-skills en wijs deze toe aan de agents die de aangepaste agentassistentie-applicatie moeten kunnen gebruiken.
• Maak een contactpunt voor een nieuw kanaal.
• Wijzig een bestaand contactpunt Het toegangspunt dat een inbound contact gebruikt om een interactie te starten, zoals een telefoonnummer of e-mailadres. om een nieuw script te starten. Breng deze wijziging niet aan totdat uw Custom Agent Assist Integration volledig is getest en in productie kan worden genomen.

Responsreeksdiagrammen

Responsreeksdiagrammen tonen de interactie tussen de verschillende onderdelen van een Custom Agent Assist Integration en de volgorde van de interacties. Ze geven een tijdlijn van een interactie, die begint in de linkerbovenhoek en daarna verdergaat op de pagina.

Responsreeksdiagrammen vormen een belangrijk onderdeel van de planning van uw aangepaste integratie. U kunt ze gebruiken om de flow van verzoeken en responsen tussen CXone, Agent Assist Hub, de proxytunnel en uw agentassistentie-applicatie in kaart te brengen. Ze kunnen ook handig zijn bij het bepalen van de flow die uw Studio-script moet volgen.

Vereisten en richtlijnen voor Studio-scripts

Gebruik de volgende voorbeelden als basis voor het maken van de scripts om uw agentassistentie-applicatie te integreren in CXone. Voor inbound en outbound interacties zijn afzonderlijke scripts nodig. De volgende afbeelding toont de essentiële acties voor een script voor inbound interacties:

De volgende afbeelding toont de essentiële acties voor een script voor outbound interacties:

In beide scripts is de Snippet Script Param Payload optioneel. Dit hoeft u alleen op te nemen als u parameters moet doorgeven aan de agentassistentie-applicatie.

Om het script te voltooien moet u:

• De andere vertakkingen van elke actie verbinden.
• Voeg indien nodig andere acties, configuraties en scriptlogica toe zodat het script functioneert zoals vereist in uw omgeving.

• Zorg ervoor dat de optionele Script Param Payload-actie Snippet de aangepaste payload-JSON voor de agentassistentieprovider bevat.

• Zorg ervoor dat de eigenschap scriptParams in de actie Agent Assist is ingesteld op {customPayloadJSON}.. Dit is alleen vereist als u de optionele actie Snippet met aangepaste payload opneemt.
• Wijs de configuratie-app van Aangepaste agentassistentie-eindpunten toe aan de actie Agent Assist.
• Initialiseringsfragmenten aan het script toevoegen met behulp van Snippet -acties. Hierdoor kunt u uw agentassistentie-app aanpassen.
• Pas de actieconnectoren aan om een goede contactflow te waarborgen en eventuele fouten te corrigeren.
• Eventuele aanvullende scripts maken en het script testen.

Als u hulp nodig hebt bij het maken van scripts in Studio, neem dan contact op met uwCXone-accountmanager, lees de sectie Scripthandleiding in de online Help, of bezoek de -website van de NICE CXone Community.

Scriptparameters Payload-snippet

Dit fragment definieert de gegevens die zijn doorgegeven aan de agentassistentietoepassing door de Agent Assist action-actie. Voeg deze code toe aan een Snippet action-actie in uw script:

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

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

Als er geen aangepaste payloadparameters zijn om te verzenden, maar het fragment scriptparameters vereist is, kunt u de variabeledeclaraties opnemen in het fragment zonder enige waarden toe te wijzen. Voorbeeld:

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

Om dit fragment te gebruiken:

1. Wijzig de parameternamen en -waarden zoals nodig om te voldoen aan de behoeften van uw organisatie en de agentassistentietoepassing die u gebruikt.
2. Plaats de Snippet-actie in het script vóór de Agent Assist-actie.
3. Configureer de scriptParams-eigenschap van de Agent Assist action-actie met de naam van de variabele die JSON bevat. In het opgegeven voorbeeld, zou dit customParamjson zijn.

Nieuwe scripts versus bestaande scripts

U kunt nieuwe scripts maken voor gebruik met uw Custom Agent Assist Integration. U kunt ook bestaande scripts aanpassen. Wijzig scripts die momenteel in productie zijn niet. Als u dit wel doet, kunnen er fouten optreden die de routering van contacten verstoren.

Als u een bestaand script wilt gebruiken, slaat u een kopie van het script op en past u die aan. Wanneer uw aangepaste integratie volledig is getest en klaar is voor implementatie, kan het gewijzigde script weer in productie worden genomen. U neemt als volgt een script weer in productie:

• Sla het script op met de naam van een script dat momenteel in productie is.
• Configureer een contactpunt Het toegangspunt dat een inbound contact gebruikt om een interactie te starten, zoals een telefoonnummer of e-mailadres. om het script te gebruiken. Voordat u het contactpunt configureert, is het slim om het script op te slaan met een nieuwe naam.

Ontwikkeling en specificaties van proxytunnel/webhook

De proxytunnel vormt de middleware tussen CXone en het eindpunt van uw agentassistentie-applicatie. Alle verzoeken en responsen gaan hierdoorheen. Het moet verzoeken van CXone vertalen naar een indeling die de agentassistentie-applicatie begrijpt. Het moet ook de responsen van de agentassistentie-applicatie vertalen naar de indeling die CXone begrijpt. Hiervoor moet u de eindpunten tussen CXone en de agentassistentie-applicatie toewijzen.

De proxytunnel is niet vereist. Het wordt echter wel aanbevolen om deze in uw integratie op te nemen. De proxytunnel biedt de volgende voordelen:

• De tunnel biedt verbeterde beveiliging omdat er één toegangspunt in uw datacenter is dat beheerd moet worden.
• De tunnel biedt failover en load balancing.
• De tunnel vertaalt protocols tussen CXone en het systeem van de agentassistentprovider.

Als u geen proxytunnel in uw integratie opneemt, stuurt het script het aanvankelijke websocketverzoek naar de webhook-URL's. U moet uw script configureren om verzoeken te verzenden en te ontvangen in de indeling die wordt verwacht door de agentassistentie-applicatie.

De volgende gedeelten bieden het volgende:

• Belangrijke feiten over aangepaste Agentassistentie-integraties en proxytunneleindpunten.
• Indeling van het eerste websocketverzoek van CXone voor spraakinteracties.
• Indeling van de handshakerespons voor spraakinteracties.
• Indeling van de webhookverbinding voor chatinteracties.
• Indeling voor het opnemen van configuratieparameters bij verzoeken.

Belangrijkste feiten voor de ontwikkeling van een proxytunnel

De volgende informatie kan u helpen bij het plannen en ontwikkelen van het proxytunneleindpunt:

• Het text relay-eindpunt moet HTTPS gebruiken. Het werkt niet met HTTP.

• Het audio relay-eindpunt moet een websocket zijn. Deze kan beveiligd (WSS) of onbeveiligd (WS) zijn.

• Alle proxytunneleindpunten moeten communicatie kunnen verzenden en ontvangen van het NICE CXone-netwerk.

• Alleen binaire gegevens stromen door de webhook.

• Voor spraakinteracties zijn audiobytes de enige gegevens die van de oproep worden verzonden. Er worden geen gespreksfuncties of andere metadata meegestuurd.

• Aangepaste agentassistentie-integraties bieden ondersteuning voor minimaal 2000 gelijktijdige verzoeken.

• Er is geen verlooptijd of een maximale verbindingstijd voor het streamen van een interactie. Met Custom Agent Assist Integrations kunnen oproepen geopend blijven zolang de oproep actief is. Wanneer de oproep wordt beëindigd, wordt de verbinding verbroken.

• Wanneer een oproep in de wachtstand wordt gezet, blijft de verbinding open, maar worden er geen gegevens verzonden.

• Contact-ID's zijn uniek voor elke bedrijfseenheid Een organisatorische eenheid die wordt gebruikt om technische ondersteuning, facturering en globale instellingen voor uw CXone-omgeving te beheren . CXone heeft een API die u kunt gebruiken om realtime data over de contactID te verkrijgen. Om de documentatie over de API weer te geven, hebt u toegang nodig tot de CXone Developer portal. Vraag uw CXone-accountmanager voor informatie over toegang.

Verbinding maken met audiowebhook: eerste verzoek

Spraakinteracties moeten gebruik maken van websocketverzoeken (WSS of WS). Het eerste websocketverzoek van CXone volgt deze indeling:

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

De parameters in dit verzoek worden beschreven in het gedeelte Schema's op deze pagina:

• authenticationToken, streamsConfiguration, appParams en appConfig worden beschreven in het gedeelte WebSocketHookInitializeMessage.
• systemTelemetryData wordt beschreven in een apart gedeelte.
• streamPerspective wordt beschreven in een apart gedeelte.

Verbinding maken met audiohook: handshakerespons

Als authenticationToken is opgegeven, valideert het token of de header en stuurt u vervolgens de handshakerespons. De respons moet de indeling van de CXoneWebSocketMessage-klasse volgen:

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
}
		

Voorbeeld:

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

Een voorbeeld van code om verbinding te maken met de 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
}		
				
		

Een afbeelding van de voorbeeldcode weergeven

In het gedeelte Schema's wordt het volgende beschreven:

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

Verbinding maken met de teksthook

Om tekstchatgegevens te ontvangen, moet u verbinding maken met de tekstwebhook. Alleen HTTP/HTTPS-verzoeken worden geaccepteerd.

Elk verzoek bevat de volgende objecten. De autorisatieheader wordt alleen verzonden als u er een toevoegt in de Aangepaste agentassistentie-eindpunten-app in Agent Assist Hub. Autorisatieheaders zijn niet vereist.

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

De parameters in deze code worden beschreven in het gedeelte Schema's op deze pagina.

Configuratieparameters

U kunt extra parameters opnemen wanneer u de Custom Agent Assist Endpoint-app configureert in Agent Assist Hub. Dit is handig als de provider van uw agentassistentie vereist dat bij elk verzoek bepaalde parameters worden meegestuurd. Deze zijn niet vereist. Alle parameters die u toevoegt, worden verzonden in het agentAssistAppConfig-object in het WebHooksMessagesRequest-object. Voorbeeld:

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

CXone Eindpunten voor Custom Agent Assist Integrations

De API-eindpunten die hier worden geleverd, zijn interactieve referenties die u met uw Custom Agent Assist Integration kunt gebruiken om voorbeelden van verzoeken van CXone te verkrijgen. Extra informatie, inclusief de oorspronkelijke schema's, is beschikbaar in de Swagger-documentatie van de API.

Eindpunten voor spraakgebaseerde agentassistentie-apps

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server: dit eindpunt geeft u een voorbeeld van een websocketserververzoek-URL. Dit voorbeeld komt overeen met de CXone specificatie van de audiohook van de websocket.

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example: dit eindpunt geeft u een voorbeeld van een initialisatiebericht van de websocket.

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example: dit eindpunt biedt een voorbeeld van de eerste aanroep en de respons. Zie het WebSocketHookInitializeMessage-schema en CXoneWebSocketMessage-schema voor meer informatie.

Eindpunten voor chatgebaseerde agentassistentie-apps

POST ​/agent_assist_text_webhooks​/utterance: dit eindpunt geeft u een voorbeeld van het in realtime ontvangen van tekstgebaseerde uitingen Iets wat een contact zegt of typt. en het leveren van asynchrone agentassistentie. Uitingen kunnen van alleen het contact, alleen de agent of beide komen.

Schema's

De volgende gedeelten bieden informatie over de schema's die worden gebruikt met de Custom Agent Assist Endpoints. Controleer altijd de schema's in de laatste versie van het Swagger-document voordat u deze informatie toepast in uw scripts.

ActionExecutionInfo

Bevat informatie over de actie en het script dat wordt uitgevoerd.

Parameter	Type	Details
contactId	Integer	De unieke ID van de interactie.
busNo	Integer	De ID van de CXonebedrijfseenheid Een organisatorische eenheid die wordt gebruikt om technische ondersteuning, facturering en globale instellingen voor uw CXone-omgeving te beheren waar het script zich bevindt.
requestId	Integer	Een iteratief nummer dat elk verzoek in een specifieke interactie identificeert. Als u de requestId opneemt in verzoeken, kan deze ook worden opgenomen in de respons. Dit kan nuttig zijn bij het oplossen van problemen. Als requestID een unieke waarde is, kan deze worden gebruikt om een specifieke verzoeken/responsen terug te zoeken in logbestanden.
actionType	String	Het actietype dat het verzoek naar het aangepaste eindpunt verstuurt.
actionId	Integer	De ID van de Studio-actie binnen het script. Actie-ID's zijn gebaseerd op de volgorde waarin de acties aan het script zijn toegevoegd.
scriptName	String	Het pad en de naam van het script dat de aanvraag verstuurt.

AgentAssistUtterance_V1

Dit bevat de berichttekst en informatie over het bericht.

Parameter	Type	Details
contactId	integer ($int64)	De ID van het contact in de huidige instantie van het script.
busNo	integer ($int32)	De ID van de CXone-bedrijfseenheid Een organisatorische eenheid die wordt gebruikt om technische ondersteuning, facturering en globale instellingen voor uw CXone-omgeving te beheren waar het script zich bevindt.
tenantId	string	Deze parameter is niet vereist.
participantId	string	Geeft aan of het bericht het contact (Klant), de agent (Agent) of beide (Systeem) bevat.
messageBody	string	De tekst van het bericht.
messageMetaData		Bevat parameters met handige gegevens over het bericht in messageBody. Als het bericht een chatbericht is, kan deze parameter ook afbeeldingen, links en andere inhoud bevatten die als onderdeel van het bericht worden verzonden.
agentAssistAppConfig		Bevat configuratie-informatie van Agent Assist Hub. Voor agentassistentie-applicaties met grote configuratie-blobs kan dit object alleen de configuratie-ID bevatten. { "agentAssistAppConfig":         { "param1": "value1", "param2": "value2"         } }

CXoneWebSocketCommandType

Bepaalt het type commando dat wordt verzonden. De mogelijke waarden zijn:

• VERBINDING MAKEN.
• VERBONDEN wanneer het eerste bericht of de autorisatievalidatie is gelukt.
• BERICHT wanneer er een bericht wordt verzonden.
• FOUT wanneer het eerste bericht of autorisatievalidatie ongeldig is.

CXoneWebSocketMessage

Bevat het bericht naar CXone is verzonden vanuit de agentassistentie-applicatie.

{ additional parameters

}

StreamPerspective

Bevat een stringmatrix met drie mogelijke waarden. Deze parameter komt overeen met de configuratie van Deelnemers in de Custom Agent Assist Endpoints-app in Agent Assist Hub. Hiermee wordt bepaald of de audiostream alleen audio van het contact (0 (TX)), de agent (1 (RX) ) of een combinatie van beide (2 (MX)) bevat.

SystemTelemetryData

Bevat gegevens over de API-gebruiker die niet zijn gekoppeld aan de Studio-scriptactie. De gegevens in dit object kunnen handig zijn voor debuggen, factureren, rapporteren enzovoorts.

{
	< * >:

}

WebSocketHookInitializeMessage

Dit is de berichtstructuur voor de eerste payload websocket-client die verbinding maakt, zoals de NICE CXone-mediaserver.

{ parameters

}

{ parameters

}