Trasferire e inoltrare chiamate

Articolo
07/08/2024

Durante una chiamata attiva, è possibile trasferire la chiamata a un'altra persona, numero o segreteria telefonica. Si apprenderà come.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Una risorsa di Servizi di comunicazione distribuita. Creare una risorsa di Servizi di comunicazione.
Token di accesso utente per abilitare il client chiamante. Per altre informazioni, vedere Creare e gestire i token di accesso.
Facoltativo: Completare la guida introduttiva per aggiungere chiamate vocali all'applicazione

Installazione dell'SDK

Usare il comando npm install per installare SDK comuni e di chiamata di Servizi di comunicazione di Azure per JavaScript:

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

Inizializzare gli oggetti necessari

Per la maggior parte delle operazioni di chiamata è necessaria un'istanza di CallClient. Quando si crea una nuova istanza di CallClient, è possibile configurarla con opzioni personalizzate come un'istanza di Logger.

Con l'istanza di CallClient è possibile creare un'istanza di CallAgent chiamando il createCallAgent. Questo metodo restituisce in modo asincrono un oggetto istanza CallAgent.

Il metodo createCallAgent usa CommunicationTokenCredential come argomento. Accetta un token di accesso utente.

È possibile usare il metodo getDeviceManager nell'istanza di CallClient per accedere 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()

Come gestire al meglio la connettività dell'SDK all'infrastruttura Microsoft

L'istanza Call Agent consente di gestire le chiamate (per partecipare o avviare le chiamate). Per lavorare con l'SDK per chiamate, è necessario connettersi all'infrastruttura Microsoft per ricevere notifiche delle chiamate in arrivo e coordinare altri dettagli delle chiamate. Call Agent ha due possibili stati:

Connesso : un valore connectionStatue Call Agent di Connected indica che l'SDK client è connesso e in grado di ricevere notifiche dall'infrastruttura Microsoft.

Disconnesso : un valore connectionStatue Call Agent di Disconnected indica un problema che impedisce all'SDK di connettersi correttamente. Call Agent deve essere ricreato.

invalidToken: se un token è scaduto o non è valido l'istanza Call Agent si disconnette con questo errore.
connectionIssue: se si verifica un problema con il client che si connette a Microsoft infrascture, dopo molti tentativi Call Agent espone l'errore connectionIssue.

È possibile verificare se l'infrastruttura locale Call Agent è connessa all'infrastruttura Microsoft controllando il valore corrente della proprietà connectionState. Durante una chiamata attiva è possibile restare in ascolto dell'evento connectionStateChanged per determinare se Call Agent cambia dallo stato Connesso a Disconnesso.

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

Il trasferimento delle chiamate è una funzionalità estesa dell'API principale Call. È prima necessario importare le funzionalità chiamante da Calling SDK:

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

È quindi possibile ottenere l'oggetto API della funzionalità di trasferimento dall'istanza di chiamata:

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

I trasferimenti di chiamata coinvolgono tre parti:

Transferor: persona che avvia la richiesta di trasferimento.
Transferee: la persona che viene trasferita.
Destinazione trasferimento: la persona a cui viene trasferito.

Trasferimento al partecipante:

Esiste già una chiamata connessa tra il transferor e il trasferee. Il transferor decide di trasferire la chiamata dal transferee alla destinazione trasferimento.
Il transferor chiama l'API transfer.
La destinazione di trasferimento riceve una chiamata in ingresso solo se il transferee accetta la richiesta di trasferimento.

Per trasferire una chiamata corrente, è possibile usare l'API transfer. transfer accetta l'oggetto facoltativo transferCallOptions, che consente di impostare un flag disableForwardingAndUnanswered:

disableForwardingAndUnanswered = false: se la destinazione di trasferimento non risponde alla chiamata di trasferimento, il trasferimento segue l'inoltro di destinazione del trasferimento e le impostazioni senza risposta.
disableForwardingAndUnanswered = true: se la destinazione di trasferimento non risponde alla chiamata di trasferimento, il tentativo di trasferimento termina.

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

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

Trasferisci per chiamare:

Esiste già una chiamata connessa tra il transferor e il trasferee.
Esiste già una chiamata connessa tra il transferor e la destinazione di trasferimento.
Il transferor decide di trasferire la chiamata con il transferee alla chiamata con destinazione di trasferimento.
Il transferor chiama l'API transfer.
La destinazione di trasferimento riceve una chiamata in ingresso solo se il transferee accetta la richiesta di trasferimento.

Per trasferire una chiamata corrente, è possibile usare l'API transfer.

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

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

L'API transfer consente di sottoscrivere stateChanged. Viene inoltre fornito con proprietà di trasferimento state e 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

L'oggetto transferee può restare in ascolto di un evento transferAccepted. Il listener per questo evento ha un TransferEventArgs che contiene l'oggetto chiamata della nuova chiamata di trasferimento tra il transferee e la destinazione di trasferimento.

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

Il transferor può sottoscrivere eventi per la modifica dello stato del trasferimento. Se la chiamata al transferee è stata connessa correttamente con la destinazione di trasferimento, il transferor può appendere la chiamata originale con il transferee.

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

Trasferimento alla segreteria telefonica:

Esiste una chiamata connessa tra il transferor e il trasferee.
L'identificatore utente di Teams della segreteria telefonica del partecipante di destinazione è noto.
Il transferor decide di trasferire la chiamata con il transferee alla segreteria telefonica del partecipante di destinazione usando l’ID utente di Teams del partecipante di destinazione.
Il transferor chiama l'API transfer.
Il transferee riceve la richiesta di trasferimento.

Per trasferire una chiamata corrente, è possibile usare l'API transfer.

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

L'API transfer consente di sottoscrivere stateChanged. Viene inoltre fornito con proprietà di trasferimento state e 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;
});

Il transferor può sottoscrivere eventi per la modifica dello stato del trasferimento. Se la chiamata al transferee è stata connessa correttamente alla segreteria telefonica del partecipante di destinazione, transferor può appendere la chiamata originale con transferee.

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

Condividi tramite