Transferir llamadas

Artículo
06/28/2024

Durante una llamada activa, puede transferirla a otra persona, número o buzón de voz. Veamos cómo hacerlo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un recurso de Communication Services implementado. Cree un recurso de Communication Services.
Un token de acceso de usuario para habilitar el cliente de llamada. Para más información, consulte Inicio rápido: Creación y administración de tokens de acceso.
Opcional: Realice el inicio rápido para agregar llamadas de voz a la aplicación

Instalación del SDK

Use el comando npm install para instalar los SDK comunes y de llamada de Azure Communication Services para JavaScript:

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

Inicialización de los objetos necesarios

Se requiere una instancia de CallClient para la mayoría de las operaciones de llamada. Al crear una nueva instancia de CallClient, puede configurarla con opciones personalizadas, como una instancia de Logger.

Con la instancia de CallClient, puede crear una instancia de CallAgent llamando al createCallAgent. Este método devuelve un objeto de instancia CallAgent de manera asincrónica.

El método createCallAgent utiliza CommunicationTokenCredential como argumento. Acepta un token de acceso de usuario.

Puede usar el método getDeviceManager en la instancia de CallClient para acceder a deviceManager.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Cuál es la mejor forma de administrar la conectividad del SDK en la infraestructura de Microsoft

La instancia de Call Agent le ayuda a administrar llamadas (para unirse o iniciar llamadas). Para trabajar con el SDK de llamadas, debe conectarse a la infraestructura de Microsoft para obtener notificaciones de llamadas entrantes y coordinar otros detalles de la llamada. Call Agent tiene dos posibles estados:

Conectado: un valor connectionStatue Call Agent con estado Connected significa que el SDK de cliente está conectado y es capaz de recibir notificaciones de la infraestructura de Microsoft.

Desconectado: un valor connectionStatue Call Agent con estado Disconnected indica que hay un problema que impide que el SDK se conecte correctamente. Call Agent se debe volver a crear.

invalidToken: si un token ha expirado o no es válido, la instancia de Call Agent se desconecta con este error.
connectionIssue: si hay un problema cuando el cliente se conecta a la infraestructura de Microsoft, después de muchos reintentos, Call Agent expone el error connectionIssue.

Para comprobar si el Call Agent local está conectado a la infraestructura de Microsoft, inspeccione el valor actual de la propiedad connectionState. Durante una llamada activa, puede escuchar el evento connectionStateChanged para determinar si Call Agent cambia de Conectado a Desconectado.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

La trasferencia de llamadas es una característica extendida de la API Call principal. En primer lugar, debe importar las características de llamada desde el SDK de llamada:

import { Features} from "@azure/communication-calling";

A continuación, puede obtener el objeto de API de la característica de transferencia de la instancia de llamada:

const callTransferApi = call.feature(Features.Transfer);

Las transferencias de llamadas implican tres entidades:

Transmitente: la persona que inicia la solicitud de transferencia.
Adquirente: la persona que se va a transferir.
Destino de la transferencia: la persona a la que se transfiere.

Transferencia al participante:

Ya hay una llamada conectada entre el transmitente y el adquirente. El transmitente decide transferir la llamada del adquirente al destino de la transferencia.
El transmitente llama a transfer API.
El destino de la transferencia recibe una llamada entrante.

Para transferir la llamada actual, puede usar transfer API. transfer toma el objeto transferCallOptions opcional, que permite establecer la marca disableForwardingAndUnanswered:

disableForwardingAndUnanswered = false: si el destino de la transferencia no responde a la llamada de transferencia, la transferencia sigue las configuraciones de reenvío y sin respuesta del destino de la transferencia.
disableForwardingAndUnanswered = true: si el destino de la transferencia no responde a la llamada de transferencia, el intento de transferencia finalizará.

// transfer target can be an Azure Communication Services user
const id = { communicationUserId: <ACS_USER_ID> };

// call transfer API
const transfer = callTransferApi.transfer({targetParticipant: id});

Transferencia para llamar:

Ya hay una llamada conectada entre el transmitente y el adquirente.
Ya hay una llamada conectada entre el transmitente y el destino de la transferencia.
El transmitente decide transferir la llamada con el adquirente a la llamada con destino de la transferencia.
El transmitente llama a transfer API.
El destino de la transferencia recibe una llamada entrante.

Para transferir la llamada actual, puede usar transfer API.

// transfer to the target call specifying the call id
const id = { targetCallId: <CALL_ID> };

// call transfer API
const transfer = callTransferApi.transfer({ targetCallId: <CALL_ID> });

La API transfer permite suscribirse a stateChanged. También incluye una transferencia state y propiedades error

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

El transferido puede escuchar un evento de transferAccepted. El cliente de escucha de este evento tiene un TransferEventArgs que contiene el objeto de llamada de la nueva llamada de transferencia entre el transferido y el destino de transferencia.

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

El transmitente puede suscribirse a eventos para cambiar el estado de la transferencia. Si la llamada al adquirente se conectó correctamente con destino de transferencia, el transmitente puede hacer que la llamada original se cuelgue con el adquirente.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

Transferencia al buzón de voz:

Hay una llamada conectada entre el transmitente y el adquirente.
Se conoce el identificador de usuario de Teams del buzón de voz del participante de destino.
El transmitente decide transferir la llamada con el adquirente al correo de voz del participante de destino mediante el identificador de usuario de Teams del participante de destino.
El transmitente llama a transfer API.
El adquirente recibe la solicitud de transferencia.

Para transferir la llamada actual, puede usar transfer API.

// transfer to the target participant voicemail specified by their Teams User Identifier
const id: MicrosoftTeamsUserIdentifier = { microsoftTeamsUserId: userId}

// call transfer API
const transfer = callTransferApi.transfer({ targetParticipantVoicemail: id });

La API transfer permite suscribirse a stateChanged. También incluye una transferencia state y propiedades error

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

El transmitente puede suscribirse a eventos para cambiar el estado de la transferencia. Si la llamada al adquirente se conectó correctamente con el buzón de voz del participante de destino, el transmitente puede hacer que la llamada original se cuelgue con el adquirente.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

Compartir vía