Uso del SDK de llamadas de ACS para pasar datos contextuales de información de usuario a usuario (UUI) entre llamadas
En este artículo, aprenderá a pasar información contextual personalizada 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 (ACS) proporciona a los desarrolladores la incorporación de 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 insertados 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 estándar de información de usuario a usuario (UUI). Además, cuando recibe una llamada entrante, los encabezados personalizados y UUI se incluyen en la carga de 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 que llama. 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 de información de usuario a usuario (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 usar la capacidad de pasar datos de información de usuario a usuario (UUI) mediante el SDK de llamada, debe usar la versión GA del SDK de WebJS 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 5 encabezados SIP personalizados 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-". Tenga en cuenta que, cuando se agrega el encabezado SIP, el SDK de llamada agregará automáticamente el prefijo "X-MS-Custom-" (que se puede ver si inspecciona el encabezado SIP con el inspector de paquetes).
La clave de encabezado SIP puede constar de caracteres alfanuméricos y algunos símbolos seleccionados, entre los que se 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 SBC. El valor de encabezado SIP puede constar de caracteres alfanuméricos y algunos símbolos seleccionados, entre los que se 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:
Actualmente, solo se admite la adición de encabezados personalizados de información de usuario a usuario al iniciar una llamada 1:1. Por el momento no se admite el paso de encabezados de información de usuario a usuario en llamadas de grupo. Para solucionar esto después de iniciar la llamada 1:1, puede incluir participantes adicionales mientras mantiene la información de usuario a usuario dentro de las llamadas.
Para obtener más información sobre la API de interfaz de contexto personalizada, consulte la página de recursos de la API de contexto personalizada.
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`);
}
}
});