Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este artículo se describe cómo pasar información de usuario a usuario (UUI) en un encabezado al enrutar llamadas con SDK de llamadas de Azure Communication Services. Esta funcionalidad permite a los usuarios pasar metadatos sobre la llamada, el destinatario o cualquier otra información relevante para su aplicación o lógica de negocios.
El SDK de WebJS de Azure Communication Services permite a los desarrolladores incluir datos contextuales personalizados (incluidos como encabezado en el objeto de llamada) al dirigir y enrutar llamadas de una persona a otra. Esta información, también conocida como datos de información de usuario a usuario (UUI) o datos UUI de control de llamadas, es un pequeño fragmento de datos insertado por una aplicación que inicia la llamada. Los datos UUI son opacos para los usuarios finales que realizan una llamada.
La información contextual admitida incluye encabezados personalizados de forma libre y el encabezado SIP UUI estándar. Además, cuando recibe una llamada entrante, los encabezados personalizados y UUI se incluyen en la carga incomingCall.
Todos los datos de contexto personalizados son opacos para llamar al SDK o protocolos SIP y su contenido no está relacionado con ninguna función básica.
Los desarrolladores pueden pasar este contexto mediante encabezados personalizados, que constan de pares clave-valor opcionales. Estos pares se pueden incluir en las acciones AddParticipant o Transfer dentro del SDK de llamadas. Una vez agregado, puede leer la carga de datos a medida que la llamada se mueve entre los puntos de conexión. Al buscar de forma eficaz estos metadatos y asociarlos a la llamada, los desarrolladores pueden evitar búsquedas de bases de datos externas y hacer que la información de contenido esté disponible fácilmente en el objeto de llamada.
El contexto de llamada personalizado se puede transmitir a los puntos de conexión SIP mediante el protocolo SIP. Esta transmisión incluye los encabezados personalizados y el encabezado SIP UUI estándar. Cuando se enruta una llamada entrante desde la red de telefonía, los datos del Controlador de límites de sesión (SBC) en los encabezados personalizados y en UUI también se incluyen en la carga del evento IncomingCall.
Es importante tener en cuenta que todos los datos de contexto personalizados permanecen transparentes para el SDK de llamada y no están relacionados con ninguna de las funciones fundamentales del SDK cuando se usan en protocolos SIP. Este es un tutorial que le ayudará a agregar encabezados de contexto personalizados al usar el SDK de WebJS.
Importante
Para pasar datos de UUI mediante el SDK de llamada, debe usar el SDK de WebJS GA o la versión preliminar pública 1.29.1 o posterior.
Parámetros técnicos
El SDK de llamada admite la adición de hasta cinco encabezados SIP personalizados (5) y 1000 encabezados VOIP personalizados. Además, los desarrolladores pueden incluir un encabezado de usuario a usuario dedicado como parte de la lista de encabezados SIP.
La longitud máxima de una clave de encabezado SIP es de 64 caracteres, incluido el prefijo "X-MS-Custom-". Al agregar el encabezado SIP al SDK de llamada, agrega automáticamente el X-MS-Custom- prefijo, que puede ver inspeccionando el encabezado SIP con el inspector de paquetes.
La clave de encabezado SIP puede constar de caracteres alfanuméricos y algunos símbolos seleccionados, que incluyen ., !, %, *, _+, , ~, . - La longitud máxima del valor del encabezado SIP es de 256 caracteres. Se aplican las mismas limitaciones al configurar los encabezados SIP en el controlador de borde de sesión (SBC). El valor del encabezado SIP puede constar de caracteres alfanuméricos y algunos símbolos seleccionados, que incluyen =, ;, ., !, %, *, _, +, ~, -.
La longitud máxima de una clave de encabezado VOIP es de 64 caracteres. La longitud máxima del valor del encabezado VOIP es de 1024 caracteres.
Al agregar estos encabezados personalizados como desarrollador, puede optar por agregar solo encabezados SIP, solo encabezados VoIP o ambos.
Nota:
Al enviar encabezados SIP, se recomienda codificar los valores de los encabezados con URL. Incluso si los valores solo contienen caracteres válidos, los operadores intermedios pueden no analizarlos correctamente a menos que estén codificados con dirección URL.
Nota:
Actualmente, solo se admite la adición de encabezados personalizados de información de usuario a usuario al iniciar una llamada 1:1. Actualmente no se admite el paso de encabezados de información de usuario a usuario en llamadas de grupo. Para solucionar esta restricción después de iniciar la llamada 1:1, puede agregar participantes mientras mantiene la información de usuario a usuario dentro de las llamadas.
Para más información sobre la API de interfaz de contexto personalizada, consulte recurso de API de contexto personalizado.
Realizar una llamada con datos de información de usuario a usuario (UUI)
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
Leer y analizar encabezados de información de usuario a usuario en una llamada
La instancia de callAgent emite un evento incomingCall cuando la identidad que ha iniciado sesión recibe una llamada entrante. Para escuchar este evento y extraer información contextual, suscríbase mediante una de estas opciones:
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});