Recursos para integraciones personalizadas de Agent Assist

Los recursos en esta página proporcionan la información que necesita al planificar e implementar una integrar personalizada de asistencia al agente con NiCE CXone.

Aplicaciones de Agente Admitidas

MAX y las aplicaciones NiCE CXone Agent Workspace (Agent) son compatibles para su uso con integraciones personalizadas de agente Assist. En las aplicaciones NiCE CXone Agent Workspace (Agent), las integraciones personalizadas de agente Assist siempre se abren en una pestaña nueva.

Transmisión 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 NiCE CXone.

Cuando configura su integración de asistencia para agentes personalizada en Agent Assist Hub, puede elegir qué audio desea enviar a la aplicación de asistencia para agentes. Puede enviar audio del contacto, el agente o ambos.

Al inicio de cada flujo, NiCE CXone envía un mensaje inicial a la aplicación Terminal Personalizado de Asistencia del Agente.El mensaje inicial incluye el parámetro streamPerspective, que indica si el flujo de audio corresponde al agente o al contacto:

• "streamPerspective": "RX": El audio transmitido por el teléfono del agente: el agente hablando.
• "streamPerspective": "TX": El audio que escucha el agente: la conversación del contacto, o múltiples 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 del agente.

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 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. Es posible que su Integración requiera autenticación para las solicitudes en el túnel proxy y en la aplicación de asistencia al 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. Utilice la REST API Studio acción 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 Agent Assist Hub.

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

• Genere el encabezado autorización que se utilizará en sus Scripts de integración personalizados de asistencia para agentes. Consulte la documentación de su proveedor de asistencia del agente para obtener más información sobre todas las configuraciones pertinentes.
• Agregar los encabezados requeridos a la aplicación Custom Agent Assist Endpoint en Agent Assist Hub. Si utiliza la aplicación de asistencia al Agente con interacciones de texto y voz, necesita encabezados separados 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 Custom Agent Assist Endpoint se encarga de pasar el encabezado a la aplicación de asistencia al Agente.

NiCE CXone Requisitos de configuración de la plataforma

No se requieren cambios de configuración en la plataforma NiCE CXone para configurar una integración de asistencia personalizada para agentes. El agente puede modificar los scripts existentes para incluir la nueva aplicación de asistencia al agente. Sin embargo, puede ser necesaria alguna configuración dependiendo de cómo su organización esté utilizando la nueva aplicación. Es posible que deba:

• Cree un nuevo canal Diversos medios de comunicación de voz y digitales que facilitan las interacciones con los clientes en un centro de contacto. para voz o chat ACD.
• Cree un nuevo perfil de chat para el chat de 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 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 realice este cambio hasta que su integración de asistencia para agente personalizada esté completamente probada y lista para ponerse en producción.

Diagramas de secuencia

Los diagramas de secuencia muestran cómo interactúan las distintas partes de una integrar de asistencia de agente personalizado, y el orden en que ocurren esas interacciones. Muestran una línea de tiempo de una interacción, que comienza en la esquina superior izquierda y luego se mueve de un lado a otro hacia abajo en la página.

Los diagramas de secuencia son una parte importante de la planificación de su integrar personalizada. Puede usarlos para trazar el flujo de solicitudes y respuestas entre NiCE CXone, Agent Assist Hub, el túnel proxy y su aplicación de agent assist. También pueden ser útiles para determinar el flujo que debe seguir su script de Studio.

Studio Requisitos y directrices para la creación de scripts

Utilice las siguientes muestras como base para crear los Scripts que integrarán su aplicación de asistencia para agentes en NiCE 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, el Snippet de Carga útil de Parámetro de Script es opcional. solo necesita incluirlo si necesita pasar parámetros a la aplicación de asistencia al agente.

Para completar la configuración de su script:

• Asigne la aplicación de configuración de Custom Agent Assist Endpoints a la acción Agent Assist.

• Asegúrese de que la acción opcional Script Param Payload Snippet contenga el JSON de carga útil personalizada que se enviará al proveedor de agent assist.

• Asegúrese de que la propiedad scriptParams en la acción Agent Assist esté configurada en {customPayloadJSON}. Esto solo es necesario si incluye la acción opcional Snippet con carga útil personalizada.

• Agregue snippets de inicialización al script usando las Snippet acciones. Puede hacer esto para personalizar su aplicación de asistencia al agente.
• Reconfigure los conectores de acción para garantizar el flujo de contacto adecuado y corregir cualquier error potencial.
• Completar cualquier script adicional y probar el script.

Si necesita ayuda con la creación de scripts en Studio, comuníquese con su representante de cuenta, consulte la sección Referencia Técnica Guide en la ayuda en línea de Studio, o visite el sitio NiCE Community para NiCE CXone.

Fragmento de Carga útil de parámetros de script

Este Snippet define los datos que se envían a la aplicación de asistencia al agente mediante la Agent Assist acción. Agregue este código a una Snippet acción en su script:

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

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

Si no hay parámetros de carga útil personalizada para enviar, pero se requiere el Snippet de Parámetros de script, puede incluir las declaraciones de Variable 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. Coloque la acción Snippet en el script antes de la acción Agent Assist.
3. Configure la propiedad scriptParams en la Agent Assist acción con el nombre de la variable que contiene el JSON. En el ejemplo proporcionado, esta sería customParamjson.

Scripts nuevos versus existentes

Puede crear nuevos scripts para usarlos con su integrar de agente assist personalizada.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. Cuando su integrar personalizado esté completamente probado y listo para la implementación, puede mover el script modificado de nuevo 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 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 proxy es el middleware entre NiCE CXone y el terminal de la aplicación de asistencia al agente. Todas las solicitudes y respuestas pasan a través de él. Debe traducir las solicitudes de NiCE CXone a un formato que la aplicación de asistencia al agente entienda. De manera similar, debe traducir las respuestas de la aplicación de asistencia del agente al formato que NiCE CXone entiende. Para realizar estas traducciones, debe asignar los extremos entre NiCE CXone y la aplicación de asistencia al agente.

No se requiere el túnel proxy. Sin embargo, se recomienda que lo incluya en su 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 NiCE CXone y el sistema del proveedor de asistencia de agente.

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

Las secciones a continuación contienen lo siguiente:

• Datos clave acerca de las integraciones personalizadas de asistencia de agente y los puntos de conexión del túnel proxy.
• Formato de la solicitud de websocket inicial de NiCE CXone para 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.

• Los id de contacto son únicos por Abonado Agrupación organizativa de alto nivel utilizada para administrar el soporte técnico, la facturación y la configuración global de su sistema NiCE CXone.. NiCE CXone tiene una API que puede usar para obtener datos en tiempo real sobre el contactID. Para ver la documentación sobre la API, necesita acceso al Dev Portal de NiCE CXone. Solicite información sobre el acceso a su representante de cuenta.

Conectarse a Audio Webhook: Solicitud inicial

Las interacciones de voz deben usar solicitudes de websocket (WSS o WS). La solicitud inicial de websocket proveniente de NiCE 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.

Conectarse a Audio Hook: Respuesta de enlace (Handshake)

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 aceptan solicitudes HTTP/HTTPS.

Cada solicitud contiene los siguientes objetos. El encabezado de autorización se envía solo si agrega uno en la aplicación Custom Agent Assist Endpoints en Agent Assist Hub. Los encabezados de autorización no son necesarios.

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

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 parámetros adicionales cuando configure la app de Custom Agent Assist Endpoints en Agent Assist Hub. Esto es útil si su proveedor de asistencia del agente exige que se envíen ciertos parámetros con cada solicitud. No son obligatorios. Cualquier parámetro que agregue se envía en el objeto agentAssistAppConfig dentro del objeto WebHooksMessagesRequest. Por ejemplo:

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

NiCE CXone Terminales para Integraciones personalizadas de asistencia del Agente

Los puntos de conexión de API proporcionados aquí son referencias interactivas que puede usar con su integrar personalizado de asistencia al agente para obtener ejemplos de solicitudes de NiCE CXone. La Información adicional, incluidos los esquemas originales, está disponible en la documentación de Swagger de la API.

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 cumple con la NiCE CXone especificación de enlace de websocket de audio.

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 WebSocketHookInitializeMessage esquema y el CXoneWebSocketMessage esquema para obtener más detalles.

Terminal para Aplicaciones de Asistente de agente basadas en chat

POST ​/agent_assist_text_webhooks​/utterance: Este terminal ofrece un ejemplo de recepción de enunciados Lo que un contacto dice o escribe. 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

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

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

El parámetro	Tipo	Detalles
contactId	Entero	El identificador único de la interacción.
busNo	Entero	El id de la NiCE CXoneunidad de negocio Agrupación organizativa de alto nivel utilizada para administrar el soporte técnico, la facturación y la configuración global de su sistema NiCE 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. Los Id de acciones se basan en el orden en que las acciones se agregaron 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.

El parámetro	Tipo	Detalles
contactId	entero ($int64)	La identificación del contacto en la instancia actual del script.
busNo	entero ($int32)	El id de la unidad de negocio Agrupación organizativa de alto nivel utilizada para administrar el soporte técnico, la facturación y la configuración global de su sistema NiCE CXone. NiCE CXone donde se encuentra el script.
tenantId	Cadena de caracteres	El ID del abonado NiCE CXone donde se encuentra el script.
participantId	Cadena de caracteres	Indica si el mensaje contiene el contacto (Usuario), el agente (Agente) o ambos (Sistema).
messageBody	Cadena de caracteres	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 Agent Assist Hub. Para las aplicaciones de asistencia del agente con blobs de configuración grandes, este objeto puede incluir 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 NiCE CXone desde la aplicación de asistencia del agente.

{
	additional parameters

}

StreamPerspective

Contiene una matriz de cadenas con tres valores posibles. Este parámetro refleja la configuración de Participantes realizada en la aplicación Custom Agent Assist Endpoints en Agent Assist Hub. 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 depuración, facturación, informes, etc.

{
	< * >:

}

WebSocketHookInitializeMessage

Esta es la estructura del mensaje para la primera carga útil de un cliente de websocket que se está conectando, como el servidor de medios de NiCE CXone.

{
	parameters

}

{
	parameters

}