Transférer des appels

Article
06/28/2024

Pendant un appel actif, vous souhaiterez peut-être transférer l’appel vers une autre personne, un autre numéro ou une messagerie vocale. Voyons comment procéder :

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Une ressource Communication Services déployée. Créez une ressource Communication Services.
Un jeton d’accès utilisateur pour activer le client appelant. Pour plus d’informations, consultez Créer et gérer des jetons d’accès.
Facultatif : suivez le guide de démarrage rapide permettant d’ajouter l’appel vocal à votre application.

Installer le SDK

Utilisez la commande npm install pour installer le SDK Azure Communication Services Common et le SDK Azure Communication Services Calling pour JavaScript :

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

Initialiser les objets nécessaires

Une instance CallClient est requise pour la plupart des opérations d’appel. Lorsque vous créez une instance CallClient, vous pouvez la configurer avec des options personnalisées comme une instance Logger.

Avec l’instance CallClient, vous pouvez créer une instance CallAgent en appelant createCallAgent. Cette méthode renvoie un objet d’instance CallAgent de manière asynchrone.

La méthode createCallAgent utilise CommunicationTokenCredential comme argument. Elle accepte un jeton d’accès utilisateur.

Vous pouvez utiliser la méthode getDeviceManager sur l’instance CallClient pour accéder à 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()

Comment gérer au mieux la connectivité du SDK à l’infrastructure Microsoft

L’instance Call Agent vous aide à gérer les appels (pour rejoindre ou démarrer des appels). Pour fonctionner, votre SDK d’appel doit se connecter à l’infrastructure Microsoft pour recevoir des notifications d’appels entrants et coordonner d’autres détails de l’appel. Votre Call Agent a deux états possibles :

Connecté : un Call Agent dont la valeur connectionStatue est égale à Connected signifie que le SDK client est connecté et capable de recevoir des notifications de l’infrastructure Microsoft.

Déconnecté : un Call Agent dont la valeur connectionStatue est égale à Disconnected indique qu’un problème empêche le SDK de se connecter correctement. Call Agent doit être recréé.

invalidToken : si un jeton a expiré ou n’est pas valide, l’instance Call Agent se déconnecte avec cette erreur.
connectionIssue : en cas de problème de connexion du client à l’infrastructure Microsoft, après plusieurs tentatives, Call Agent lève l’erreur connectionIssue.

Vous pouvez vérifier si votre Call Agent local est connecté à l’infrastructure Microsoft en inspectant la valeur actuelle de la propriété connectionState. Pendant un appel actif, vous pouvez écouter l’événement connectionStateChanged pour déterminer si Call Agent passe de l’état Connecté à l’état Déconnecté.

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

Le transfert d’appels est une fonctionnalité étendue de l’API Call principale. Vous devez d’abord importer les fonctionnalités d’appel à partir du Kit de développement logiciel (SDK) Appel :

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

Vous pouvez ensuite récupérer l’objet API de la fonctionnalité de transfert à partir de l’instance Appel :

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

Les transferts d’appels impliquent trois parties :

Transférant : personne qui lance la demande de transfert.
Transféré : personne qui est transférée.
Cible de transfert : personne vers laquelle le transfert est effectué.

Transférer au participant :

Il existe déjà un appel connecté entre le transférantet le transféré. Le transférant décide de transférer l’appel depuis le transféré vers la cible de transfert.
Le transférant appelle l’API transfer.
La cible de transfert reçoit un appel entrant seulement si le transféré accepte la demande de transfert.

Pour transférer un appel en cours, vous pouvez utiliser l’API transfer. transfer prend les transferCallOptions facultatives, ce qui vous permet de définir un indicateur disableForwardingAndUnanswered :

disableForwardingAndUnanswered = false : si la cible de transfert ne répond pas à l’appel transféré, le transfert suit les paramètres de transfert et de non-réponse de la cible de transfert.
disableForwardingAndUnanswered = true : si la cible de transfert ne répond pas à l’appel transféré, la tentative de transfert se termine.

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

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

Transférer vers l’appel :

Il existe déjà un appel connecté entre le transférantet le transféré.
Il existe déjà un appel connecté entre le transférantet la cible de transfert.
Le transférant décide de transférer l’appel avec le transféré vers l’appel avec la cible de transfert.
Le transférant appelle l’API transfer.
La cible de transfert reçoit un appel entrant seulement si le transféré accepte la demande de transfert.

Pour transférer un appel en cours, vous pouvez utiliser 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 vous permet de vous abonner à stateChanged. Elle est également fournie avec des propriétés state et error de transfert.

// 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

Le transféré peut être à l’écoute d’un événement transferAccepted. L’écouteur de cet événement a un TransferEventArgs qui contient l’objet d’appel du nouvel appel de transfert entre le transféré et la cible de transfert.

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

Le transférant peut s’abonner aux événements pour la modification de l’état du transfert. Si l’appel au transféré a été correctement connecté avec la cible de transfert, le transférant peut raccrocher l’appel d’origine avec le transféré.

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

Transférer vers une messagerie vocale :

Il existe un appel connecté entre le transférantet le transféré.
L’identifiant utilisateur Teams de la messagerie vocale du participant cible est connu.
Le transférant décide de transférer l’appel avec le transféré vers la messagerie vocale du participant cible en utilisant l’identificateur d’utilisateur Teams du participant cible.
Le transférant appelle l’API transfer.
La personne transférée reçoit la demande de transfert.

Pour transférer un appel en cours, vous pouvez utiliser 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 vous permet de vous abonner à stateChanged. Elle est également fournie avec des propriétés state et error de transfert.

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

Le transférant peut s’abonner aux événements pour la modification de l’état du transfert. Si l’appel vers la personne transférée a été correctement connecté avec la messagerie vocale du participant cible, l’auteur du transfert peut raccrocher l’appel d’origine avec la personne transférée.

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

Partager via