Configurar los encabezados SIP X para agentes con voz

En este artículo se explica cómo configurar las cabeceras X del Protocolo de inicio de sesiones (SIP) para las llamadas entrantes y salientes en agentes habilitados para voz en Copilot Studio para su uso en Dynamics 365 Contact Center.

Los encabezados SIP te permiten transferir metadatos personalizados entre sistemas de telefonía y tus agentes con voz activa. Dynamics 365 Contact Center ofrece soporte para agentes habilitados para voz que manejan tanto los encabezados X entrantes como salientes. Esta configuración permite un intercambio de datos fluido durante las transferencias de llamadas y el enrutamiento.

Prerrequisitos

• Dynamics 365 Contact Center con agentes habilitados para voz

• acceso a Copilot Studio con los permisos adecuados

• Enrutamiento directo para la configuración telefónica

• Conocimientos básicos de Copilot Studio creación de temas y gestión de variables

Configurar los encabezados X entrantes

Los encabezados X entrantes contienen metadatos transmitidos desde sistemas de telefonía externos a tu agente con voz activada. Para recibir y utilizar estos datos, debes configurar un nodo de Valor de Análisis para extraer la información de la cabecera X de la Conversation.SipXHeader variable del sistema.

Requisitos de entrada para los encabezados X

• Conteo máximo: Cinco X-headers por llamada entrante.

• Requisito de nombre: Todos los nombres de los encabezados X deben comenzar por x-.

  Nota:

  En Copilot Studio, todos los encabezados X entrantes deben comenzar con minúsculas x-, incluso si el sistema externo que envía el encabezado X usa un X- mayúsculas. El encabezado X saliente definido en Copilot Studio puede ser en minúsculas o mayúsculas, dependiendo de cómo lo espere el sistema externo.

• Longitud del nombre: Hasta 64 caracteres.

• Longitud del valor: hasta 256 caracteres.

• Se requiere un esquema JSON para todos los X-headers esperados.

• Actualiza el esquema JSON cuando cambien los nombres de los encabezados X.

• Dependencia de datos del canal: los encabezados X deben estar presentes en Conversation.SipXHeader.

Añadir Gestión de Variables - Nodo de Analizar Valor

1. Navega al tema de tu agente con voz activada.

2. Añade un nuevo nodo de tema.

3. Selecciona Gestión de variables y selecciona Valor de Analizar.

   

Configurar el nodo de Valor de Análisis

1. Desde el menú Sistema , establece el campo de valores de análisis en Conversation.SipXHeader.

2. Establece el tipo de dato en Desde los datos de muestra.

3. Define la estructura esperada de X-header seleccionando Get schema from sample JSON.

   

Definir esquema JSON para los encabezados X

En el diálogo Obtener esquema del JSON de ejemplo, proporciona la estructura JSON que incluye los nombres de los encabezados X que esperas recibir. Por ejemplo, si esperas cabeceras como X-CallID y X-AAI-Incoming en una llamada entrante, añádelas a tu esquema JSON.

Selecciona Confirmar para aplicar el esquema.

Ejemplo de JSON para X-headers

{

"x-CallID": "",

"x-AAI-Incoming": ""  
}

Guardar los datos analizados

1. Crea o selecciona una variable en el campo Guardar como (por ejemplo, IncomingSipXHeader).

   

2. Configura el alcance de la variable a Global para permitir el acceso a varios temas en tu agente.

Accede a los valores de X-header en tus temas

Una vez configurado, puedes acceder a valores individuales de los encabezados X usando notación de puntos, similar a los siguientes ejemplos:

• Global.IncomingSipXHeader.'x-AAI-Incoming'

• IncomingSIPXHeaders.sipXHeader.'X-CallID'

Comportamiento en tiempo de ejecución

• Copilot Studio solo recibe los cinco primeros encabezados X enviados por el sistema externo.

• Copilot Studio rellena automáticamente el registro con valores de encabezado X cuando los nombres coinciden con el esquema.

• Los X-headers que faltan tienen valores de cadena vacíos.

• Las actualizaciones de esquema son necesarias cuando cambian los nombres de los encabezados X o si quieres recibir cabeceras adicionales.

Configurar los encabezados X salientes

Puedes pasar datos personalizados al transferir llamadas a números de teléfono externos usando los encabezados X salientes. Configura estas cabeceras en el nodo Transferir conversación.

Requisitos de salida para los encabezados X

• Número máximo: Cinco X-headers por transferencia.

• Requisito de nombre: Todos los nombres de los encabezados X pueden comenzar con X- o x-, dependiendo del caso que espere el sistema externo.

  Nota:

  En Copilot Studio, todos los encabezados X entrantes deben comenzar con minúsculas x-, incluso si el sistema externo que envía el encabezado X usa un X- mayúsculas. El encabezado X saliente definido en Copilot Studio puede ser en minúsculas o mayúsculas, dependiendo de cómo lo espere el sistema externo.

• Longitud del nombre: Hasta 64 caracteres.

• Longitud del valor: hasta 256 caracteres.

• Tipo de transferencia: Solo disponible para transferencia de número de teléfono externo.

Configurar el nodo de conversación Transfer

1. Añade un nodo de transferencia de conversación a tu flujo de temas.

2. En Tipo de transferencia, seleccione Transferir a un número de teléfono externo e introduzca el número de transferencia. Por ejemplo, +18005551212.

Configurar encabezados X en las propiedades del nodo de Transferencia de Conversación

1. Seleccione el icono Más (…) del nodo y luego seleccione Propiedades.

2. Seleccione + Añadir para añadir pares clave-valor de encabezado X.

   

3. Define las entradas de encabezado X. Los nombres de los encabezados X salientes se envían exactamente como los defines en el nodo Transferencia de conversación. Elige el caso adecuado en función de lo que espera el sistema receptor.

   • Nombre clave: Debe comenzar con X- o x- (por ejemplo, X-AAI-Outgoing o X-CallID)
   • Valor: Introduce un valor estático o asigna una variable

   

procedimientos recomendados

Diseño del esquema

• Utiliza nombres descriptivos de encabezado X que indiquen claramente su propósito.

• Mantén actualizado el esquema JSON cuando cambien los requisitos de los X-headers.

• Documenta el esquema de tu X-header para referencia del equipo y solución de problemas.

Gestión de variables

• Utiliza variables globales para los datos de los X-headers a los que se debe acceder entre temas.

• Elige nombres de variables significativas (por ejemplo, IncomingSIPXHeaders o CustomerXHeaders).

• Inicializa las variables desde el principio del flujo de conversación.

Control de errores

• Siempre comprueba la presencia de los encabezados X antes de usar valores en tu lógica.

• Implementa comportamientos de respaldo para datos de cabecera X que faltan o no son válidos.

• Prueba a fondo con varios escenarios de X-headers.

Consideraciones sobre el rendimiento

• Analiza los encabezados X al principio de tu conversación.

• Almacenar en caché valores usados frecuentemente en variables separadas si es necesario.

• Evita el análisis repetido de los mismos datos de canal.

Problemas comunes con los encabezados X entrantes

Valores X-header no recibidos

• Verifica que el esquema JSON coincida exactamente con los nombres esperados de los encabezados X.

• Comprueba que el nodo de Valor de Análisis esté configurado con Conversation.SipXHeader.

• Asegúrate de que la variable esté configurada en alcance global si se accede desde varios temas.

• Asegúrate de que no se esperen más de cinco X-headers y que los X-headers sean los cinco mejores que envía el sistema externo.

Valores de encabezado X vacíos o nulos

• Confirma que el sistema externo está enviando encabezados X con los nombres esperados.

• Verifica que el esquema JSON incluya todos los nombres de encabezado X requeridos con un prefijo minúsculo x- .

Problemas comunes con las cabeceras salientes

X-headers no enviados durante la transferencia

• Verifica que todos los nombres de los encabezados X empiecen por X- o x-.

• Asegúrate de que el tipo de transferencia esté configurado como Transferencia de número de teléfono externo.

• Asegúrese de que los valores de X-header se asignen correctamente antes del nodo Transferir conversación.

Error de transferencia con X-headers

• Confirma que los nombres y valores de los encabezados X no superan los límites de longitud.

• Verifica que el sistema receptor pueda gestionar los encabezados X que se están enviando.

• Revisa si hay personajes especiales que puedan causar problemas de análisis sintáctico.

Administración de esquemas

Actualización del esquema de cabeceras X

• Para recibir nuevos encabezados X, actualiza la muestra JSON en Definir el esquema JSON para los encabezados X.

• Confirma y guarda el esquema actualizado.

• Prueba el esquema con la nueva configuración de la cabecera X.