Recursos para las integraciones personalizadas de asistencia del agente

Los recursos en esta página contienen la información que necesita para planificar e implementar una integración personalizada de asistencia del agente con CXone.

Aplicaciones compatibles de agente

MAX es actualmente la única aplicación compatible de agente que puede usarse con las integraciones personalizadas de asistencia del agente.

Streaming de audio

Los paquetes de audio se codifican como G711 μlaw, audio sin procesar de 8 bits a 8000 kHz. Este es el mismo formato utilizado en todo el audio de telefonía CXone.

Al configurar su integración personalizada de asistencia del agente en Centro de asistencia del agente, puede elegir qué audio desea enviar a la aplicación de asistencia del agente. Puede enviar audio del contacto, el agente o ambos.

Al inicio de cada flujo, CXone envía un mensaje inicial a la aplicación Terminal Personalizado de Asistencia del Agente. Un ejemplo diagrama de secuencias para una integración personalizada de asistencia del agente.El mensaje inicial contiene el parámetro streamPerspective, que indica si el flujo de audio pertenece al agente o al contacto:

• "streamPerspective": "RX": El audio que se transmite a través del teléfono del agente: el agente hablando.
• "streamPerspective": "TX": El audio que el agente escucha: el contacto hablando, o varias personas si la interacción está en modo de conferencia.
• "streamPerspective": "MIX": Contiene transmisiones de audio tanto del agente como del contacto.

Una conexión individual de Websocket solo contiene audio desde una perspectiva. Normalmente, esto es TX o RX, lo que proporciona separación estéreo. También es posible tener una mezcla de ambos en una sola transmisión mono. Si una interacción ocurre en modo de conferencia, el audio que se recibe depende de la perspectiva de transmisión configurada. Si la perspectiva es TX, se recibe el audio de todos los participantes excepto el agente.

Si la conexión se interrumpe o presenta otros problemas, como la pérdida de paquetes, el terminal de asistencia personalizada del agente intenta recuperar la conexión con el Websocket. Espera un nuevo inicio de autenticación idéntico al inicial que recibe.

Si se pone al contacto en espera, se cierra la conexión del Websocket. Cuando se reanuda la interacción, se inicia una nueva conexión de Websocket. Espera un protocolo de enlace idéntico al original.

Autorización

En las integraciones personalizadas de asistencia del agente puede usar una autorización. Su integración podría necesitar una autenticación para las solicitudes en el túnel de proxy y en la aplicación de asistencia del agente.

Autorización para el túnel de proxy

Si desea que el túnel de proxy exija una autorización para las solicitudes que lo atraviesen, debe incluir este requisito en su diseño. Puede usar cualquier tipo de autorización, como una autorización basada en tokens dinámicos o en encabezados. Debe construir su túnel de proxy para usar el método de autorización elegido.

También debe configurar su script de Studio para gestionar la autorización:

• En el caso de una autorización basada en encabezado, el script debe contener las solicitudes que envía.
• Para las autorizaciones basadas en tokens, el script debe solicitar una un token, almacenarlo en la caché y gestionar la caducidad del token. Cuando el token caduca, el script debe solicitar uno nuevo, si fuera necesario. Use la acción REST API Studio para comunicarse con el servidor de autenticación.

Si utiliza autorización dinámica, también debe configurar un servidor de autorización, si aún no dispone de uno. El servidor de autorización proporciona tokens cuando el script los solicita.

Autorización para la aplicación de asistencia del agente

Si su proveedor de asistencia del agente exige una autorización con todas las solicitudes, puede configurarla en la aplicación Terminal Personalizado de Asistencia del Agente en Centro de asistencia del agente.

Para usar la autorización con su integración personalizada, debe:

• Generar el encabezado de autorización que se usará en los scripts de integración personalizada de asistencia del agente. Consulte la documentación de su proveedor de asistencia del agente para obtener más información sobre todas las configuraciones pertinentes.
• Agregue los encabezados necesarios a la aplicación Terminal Personalizado de Asistencia del Agente en Centro de asistencia del agente. Si usa la aplicación de asistencia del agente con interacciones de texto y voz, necesitará un encabezado diferente para cada tipo de interacción. Consulte la documentación de su proveedor de asistencia del agente para obtener información sobre cómo generar los encabezados.

No necesita configurar nada en su script. La aplicación Terminal Personalizado de Asistencia del Agente gestiona la transferencia del encabezado a la aplicación de asistencia del agente.

Requisitos de configuración de la plataforma de CXone

Para implementar una integración personalizada de asistencia del agente, no es necesario cambiar la configuración de la plataforma de CXone. Puede modificar los scripts existentes para incluir la nueva aplicación de asistencia del agente. Sin embargo, podría necesitar algún tipo de configuración según la manera en que su organización use la nueva aplicación. Es posible que deba:

• Cree un nuevo canal Una forma de que los contactos interactúen con agentes o bots. Un canal puede ser de voz, correo electrónico, chat, redes sociales, etc. para voz o chat ACD.
• Cree un nuevo perfil de charla para el chat ACD.
• Cree una o más habilidades ACD y asígnelas a los agentes para los que desee que esté disponible la aplicación personalizada de asistencia del agente.
• Cree un punto de contacto para un canal nuevo.
• Modifique un punto de contacto El punto de entrada que utiliza un contacto entrante para iniciar una interacción, como un número de teléfono o una dirección de correo electrónico. existente para lanzar un script nuevo. No aplique este cambio hasta haber probado su integración personalizada de asistencia del agente por completo y que esté lista para entrar en producción.

Diagramas de secuencias

Los diagramas de secuencias muestran la interacción entre las diversas partes de una integración personalizada de asistencia del agente y el orden en que ocurren esas interacciones. Muestran la cronología de una interacción, comenzando desde la esquina superior izquierda y avanzando y retrocediendo por la página.

Los diagramas de secuencias son una parte importante de la planificación de su integración personalizada. Puede usarlos para mapear el flujo de solicitudes y respuestas entre CXone, Centro de asistencia del agente, el túnel de proxy y su aplicación de asistencia del agente. También pueden resultar útiles para determinar el flujo que debe seguir su script de Studio.

Studio Requisitos y directrices para la creación de scripts

Use los siguientes ejemplos como base para crear los scripts para integrar su aplicación de asistencia al agente en CXone. Las interacciones entrantes y salientes necesitan scripts diferentes. La siguiente imagen muestra las acciones esenciales para un script de entrada:

Esta imagen muestra las acciones esenciales para un script de salida:

En ambos scripts, la carga útil del parámetro de script Snippet es opcional. Sólo debe incluirlo si necesita transmitir parámetros a la aplicación de asistencia de agente.

Para completar el script, debe:

• Conectar las otras ramas de cada acción.
• Agregue otras acciones, configuraciones y lógica de script según sea necesario para que el script funcione como se requiere en su entorno.

• Verifique que la acción opcional Carga útil del parámetro de script Snippet contenga la carga útil en formato Json para enviar al proveedor de asistencia del agente.

• Verifique que la propiedad scriptParams en la acción Agent Assist está definida a {customPayloadJSON}. Esto solo es necesario si incluye la acción opcional de Snippet con carga personalizada.
• Asigne la aplicación de configuración Custom Agent Assist Endpoints a la acción Agent Assist.
• Agregue fragmentos de inicialización al script usando acciones Snippet. Puede hacer esto para personalizar su aplicación de asistencia de agentes.
• Vuelva a configurar los conectores de acción para garantizar un flujo de contactos adecuado y corregir cualquier posible error.
• Completar cualquier script adicional y probar el script.

Si necesita ayuda con el scripting en Studio, comuníquese con su Representante de cuenta CXone, consulte la sección Guía de scripting de la ayuda en línea o visite el sitio Comunidad de NICE CXone.

Fragmento de carga útil de los parámetros de script

Este snippet define los datos que se transfieren a la aplicación de asistencia del agente por parte de la acción Agent Assist action. Agregue este código a una acción Snippet actionen su script:

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

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

De no haber parámetros de carga personalizados para su envío pero se requiere el snippet de Parámetros del Script, puede incluir las declaraciones de variables en el snippet sin asignar ningún valor. Por ejemplo:

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

Para usar este snippet:

1. Cambie los nombres y valores de los parámetros según sea necesario para satisfacer las necesidades de su organización y la aplicación de asistencia de agentes que use.
2. Colocar la acciónSnippet en el script antes de la acción Agent Assist.
3. Configurar la propiedad scriptParams en la acción Agent Assist actioncon el nombre de la variable que contiene el JSON. En el ejemplo presentado, esto sería customParamjson.

Scripts nuevos versus existentes

Puede crear nuevos scripts para usarlos con su integración personalizada de asistencia del agente. Un ejemplo diagrama de secuencias para una integración personalizada de asistencia del agente.También puede modificar scripts existentes. No aplique cambios directamente en los scripts que se encuentren en producción. Esto podría causar errores que interrumpan el enrutamiento de los contactos.

Si desea usar un script existente, guarde una copia del script y modifique esa versión. Después de someter la integración personalizada a todas las pruebas necesarias y confirmar que está lista para la implementación, puede transferir el script modificado a producción. Lleve un script a producción realizando una de las siguientes acciones:

• Guárdelo con el nombre de un script que ya esté en producción.
• Configure un punto de contacto El punto de entrada que utiliza un contacto entrante para iniciar una interacción, como un número de teléfono o una dirección de correo electrónico. para usar el script. Quizás desee guardar el script con otro nombre, antes de configurar el punto de contacto.

Desarrollo y especificaciones del webhook del túnel de proxy

El túnel de proxy es el middleware entre CXone y su terminal para la aplicación de asistencia del agente. Todas las solicitudes y respuestas pasan a través de él. Debe traducir las solicitudes de CXone a un formato que la aplicación de asistencia del agente pueda comprender. De manera similar, debe traducir las respuestas de la aplicación de asistencia del agente a un formato que CXone comprenda. Para efectuar estas traducciones, usted debe mapear los terminales entre CXone y la aplicación de asistencia del agente.

No se requiere el túnel proxy. No obstante, se recomienda incluirlo en la integración. El túnel proxy proporciona las siguientes ventajas:

• Proporciona una mayor seguridad porque hay un único punto de entrada en su centro de datos para gestionar.
• Proporciona recuperación ante fallos y equilibrio de carga.
• Traduce los protocolos entre CXone y el sistema del proveedor de asistencia de agente.

Si no incluye un túnel proxy en su integración, el script envía la solicitud inicial de websocket a las URL de webhook. Debe configurar su script para enviar y recibir solicitudes en el formato esperado por la aplicación de asistencia de agente.

Las secciones a continuación contienen lo siguiente:

• Datos clave sobre las integraciones personalizadas de asistencia del agente y los terminales de túnel de proxy.
• Formato de la solicitud inicial de websocket proveniente de CXone para las interacciones de voz.
• Formato de la respuesta de protocolo de enlace para las interacciones de voz.
• Formato de la conexión webhook para las interacciones de chat.
• Formato para incluir parámetros de configuración con solicitudes.

Datos clave sobre el desarrollo del túnel de proxy

La información siguiente puede ser útil para planificar y desarrollar el terminal del túnel de proxy:

• El terminal de retransmisión de texto debe usar HTTPS. No funciona con HTTP.

• El terminal de retransmisión de audio debe ser un websocket. Puede ser seguro (WSS) o inseguro (WS).

• Todos los terminales de túnel de proxy deben ser capaces de enviar y recibir comunicaciones de la red NICE CXone.

• Sólo fluyen datos binarios a través del webhook.

• En el caso de las interacciones de voz, los únicos datos que se envían desde la llamada son los bytes de audio. No se incluye el control de llamada ni otros metadatos.

• Las integraciones personalizadas de asistencia del agente admiten al menos 2000 solicitudes de manera simultánea.

• No hay una hora de caducidad ni un tiempo máximo de conexión para el streaming de una interacción. Las integraciones personalizadas de asistencia del agente permiten que las llamadas queden abiertas siempre que la llamada permanezca activa. Cuando la llamada finaliza, la conexión se cierra.

• Cuando la llamada se coloca en espera, la conexión se mantiene abierta, pero no se envían datos.

• Las identificaciones de contactos son únicas según unidad de negocio Agrupación organizativa de alto nivel utilizado para administrar el soporte técnico, facturación y configuración global para su CXone entornotenant. CXone tiene una API que puede usar para obtener datos en tiempo real sobre contactID. Para ver la documentación relativa a la API, necesita acceso al Portal Dev de CXone. Consulte a su Representante de cuenta CXone para obtener información sobre el acceso.

Webhook de conexión a audio: solicitud inicial

Las interacciones de voz deben usar solicitudes de websocket (WSS o WS). La solicitud inicial de websocket proveniente de CXone sigue este formato:

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

Los parámetros en esta solicitud se describen en la sección Esquemas de esta página:

• authenticationToken, streamsConfiguration, appParams y appConfig se describen en la sección WebSocketHookInitializeMessage.
• systemTelemetryData se describe en su propia sección.
• streamPerspective se describe en su propia sección.

Conexión con el enlace de audio: respuesta del protocolo de enlace

Si se proporciona authenticationToken, valide el token o encabezado y, después, envíe una respuesta de protocolo de enlace. La respuesta debe tener el formato de clase 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
}
		

Por ejemplo:

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

Ejemplo de código para conectar con el 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
}		
				
		

Ver una imagen del código de ejemplo

La sección Esquemas de esta página describe lo siguiente:

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

Conexión con el enlace de texto

Para recibir los datos del chat de texto, debe conectarse con el webhook de texto. Solo se aceptarán las solicitudes HTTP/HTTPS.

Cada solicitud contiene los siguientes objetos. Solo se le envía el encabezado de autorización si usted agrega uno en la aplicación Custom Agent Assist Endpoints en Centro de asistencia del agente. No son necesarios los encabezados de autorización.

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 Centro de asistencia del agente. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}
 	

Los parámetros en este código se describen en la sección Esquemas de esta página.

Parámetros de configuración

Puede incluir otros parámetros al configurar la aplicación Terminal Personalizado de Asistencia del Agente en Centro de asistencia del agente. Esto es útil si su proveedor de asistencia del agente exige que se envíen ciertos parámetros con cada solicitud. No son obligatorios. Todo parámetro que agregue se envía en el objeto de agentAssistAppConfig en el objeto de WebHooksMessagesRequest. Por ejemplo:

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

CXone Terminales para Integraciones personalizadas de asistencia del agente

Los terminales API provistos aquí son referencias interactivas que puede usar con su integración personalizada de asistencia del agente para obtener ejemplos de solicitudes de CXone. En la documentación de Swagger de la API hay más información, por ejemplo los esquemas originales.

Terminales para aplicaciones de asistencia del agente basada en voz

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server: Este terminal ofrece un ejemplo de una URL de solicitud a servidor de websocket. Este ejemplo está de acuerdo con la especificación del enlace de websocket de audio de CXone .

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example: Este terminal ofrece un ejemplo de un mensaje de inicialización de websocket.

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example: Este terminal ofrece un ejemplo de la solicitud y respuesta iniciales. Consulte el esquema de WebSocketHookInitializeMessage y el esquema de CXoneWebSocketMessage para conocer los detalles.

Terminal para aplicaciones de asistencia del agente basada en chat

POST ​/agent_assist_text_webhooks​/utterance: Este terminal ofrece un ejemplo de recepción de enunciados Lo que dice o escribe un contacto. basados en texto en tiempo real y de cómo prestar asistencia a los agentes de manera asincrónica. Los enunciados pueden ser solo para el contacto, solo para el agente o para ambos.

Esquemas

Las secciones a continuación contienen información sobre los esquemas que se utilizan con los terminales personalizado de asistencia del agente. Verifique siempre los esquemas de la última versión del documento Swagger antes de usar esta información en sus scripts.

ActionExecutionInfo

Contiene información sobre la acción y el script que se están ejecutando.

Parámetro	Tipo	Detalles
contactId	Entero	El identificador único de la interacción.
busNo	Entero	La identificación de la unidad de negocio Agrupación organizativa de alto nivel utilizado para administrar el soporte técnico, facturación y configuración global para su CXone entorno de CXone donde se encuentra el script.
requestId	Entero	Un número interactivo que identifica cada solicitud de una interacción en particular. Si incluye requestId en las solicitudes, puede incluirse en las respuestas. Esto puede ser útil para resolver problemas. Si requestID es un valor único, puede usarse para localizar una solicitud/respuesta única en los archivos de registro.
actionType	Cadena de caracteres	El tipo de acción que efectúa la solicitud al terminal personalizado.
actionId	Entero	El número de identificación de la acción Studio dentro del script. Las ID de acción se basan en el orden en que se agregaron las acciones al script.
scriptName	Cadena de caracteres	La ruta y el nombre del script que hace la solicitud.

AgentAssistUtterance_V1

Contiene el cuerpo del mensaje e información sobre el mensaje.

Parámetro	Tipo	Detalles
contactId	entero ($int64)	La identificación del contacto en la instancia actual del script.
busNo	entero ($int32)	La identificación de la unidad de negocio Agrupación organizativa de alto nivel utilizado para administrar el soporte técnico, facturación y configuración global para su CXone entorno de CXone donde se encuentra el script.
tenantId	Cadena	Este parámetro no es necesario.
participantId	Cadena	Indica si el mensaje contiene el contacto (Usuario), el agente (Agente) o ambos (Sistema).
messageBody	Cadena	El texto del mensaje.
messageMetaData		Contiene parámetros con datos útiles sobre el mensaje en messageBody. Si un mensaje es un mensaje de chat, este parámetro contiene también imágenes, enlaces u otros contenidos que se envían como parte del mensaje.
agentAssistAppConfig		Contiene información de configuración de Centro de asistencia del agente. Par las aplicaciones de asistencia del agente con grandes blobs de configuración, este objeto puede contener solo el identificador de configuración. { "agentAssistAppConfig":         { "param1": "value1", "param2": "value2"         } }

CXoneWebSocketCommandType

Define el tipo de comando que se está enviando. Los posibles valores son:

• CONECTAR .
• CONECTADO para cuando el mensaje inicial o la validación de autorización tienen éxito.
• MENSAJE para usar al enviar un mensaje.
• ERROR para usar cuando el mensaje inicial o la validación de autorización no son válidos.

CXoneWebSocketMessage

Contiene el mensaje enviado a CXone desde la aplicación de asistencia del agente.

{ additional parameters

}

StreamPerspective

Contiene una serie de cadena con tres valores posibles. Este parámetro refleja la configuración de Participantes establecida en la aplicación Terminales personalizados de asistencia del agente en Centro de asistencia del agente. Define si el flujo de audio contiene audio solo del contacto (0 (TX)), solo del agente (1 (RX) ) o una combinación (2 (MX)).

SystemTelemetryData

Contiene datos sobre el consumidor de API que no están asociados con la acción de script Studio. Los datos que contiene este objeto pueden ser útiles para depurar, facturar, generar informes, etcétera.

{
	< * >:

}

WebSocketHookInitializeMessage

Esta es la estructura del mensaje para la primera carga útil proveniente de un cliente de conexión con websocket, como el servidor de medios de NICE CXone.

{ parameters

}

{ parameters

}