Weiterleiten und Übergeben von Anrufen

Artikel
12/23/2024

Während eines aktiven Anrufs können Sie den Anruf bei Bedarf an eine andere Person oder Nummer oder an das Voicemailsystem durchstellen. Hier erfahren Sie, wie Sie dazu vorgehen.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine bereitgestellte Communication Services-Ressource. Erstellen Sie eine Communication Services-Ressource.
Ein Benutzerzugriffstoken zum Aktivieren des Anrufclients. Weitere Informationen finden Sie unter Erstellen und Verwalten von Zugriffstoken.
Optional: Arbeiten Sie den Schnellstart zum Hinzufügen von Sprachanrufen zu Ihrer Anwendung durch.

Das SDK installieren

Verwenden Sie den Befehl npm install, um die Common und Calling SDKs von Azure Communication Services für JavaScript zu installieren:

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

Initialisieren erforderlicher Objekte

Für die meisten Anrufvorgänge ist eine CallClient-Instanz erforderlich. Wenn Sie eine neue CallClient-Instanz erstellen, können Sie diese mit benutzerdefinierten Optionen wie einer Logger-Instanz konfigurieren.

Mit der CallClient-Instanz können Sie eine CallAgent-Instanz erstellen, indem Sie den Agent für die Anruferstellung (createCallAgent) aufrufen. Durch diese Methode wird ein CallAgent-Instanzobjekt asynchron zurückgegeben.

Die Methode createCallAgent verwendet CommunicationTokenCredential als Argument, welches ein Benutzerzugriffstoken akzeptiert.

Sie können die Methode getDeviceManager für die Instanz CallClient verwenden, um auf deviceManager zuzugreifen.

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

Optimale Verwaltung der Konnektivität zwischen SDK und Microsoft-Infrastruktur

Die Call Agent-Instanz unterstützt Sie bei der Verwaltung von Anrufen (Annehmen oder Starten von Anrufen). Damit Ihr Calling SDK funktioniert, muss eine Verbindung mit der Microsoft-Infrastruktur hergestellt werden, um Benachrichtigungen über eingehende Anrufe zu erhalten und andere Anrufdetails zu koordinieren. Ihre Call Agent-Instanz kann zwei Status haben:

Connected (Verbunden) – Der connectionState-Wert Connected für Call Agent bedeutet, dass das Client-SDK verbunden ist und Benachrichtigungen von der Microsoft-Infrastruktur empfangen kann.

Disconnected (Getrennt) – Der connectionState-Wert Disconnected für Call Agent weist darauf hin, dass das SDK nicht ordnungsgemäß verbunden werden kann. Call Agent muss neu erstellt werden.

invalidToken: Wenn ein Token abgelaufen oder ungültig ist, wird die Call Agent-Instanz mit diesem Fehler getrennt.
connectionIssue: Wenn ein Problem mit der Verbindung zwischen dem Client und der Microsoft-Infrastruktur auftritt, gibt Call Agent nach mehreren Versuchen den connectionIssue-Fehler zurück.

Sie können überprüfen, ob Ihre lokale Call Agent-Instanz mit der Microsoft-Infrastruktur verbunden ist, indem Sie den aktuellen Wert der connectionState-Eigenschaft prüfen. Während eines aktiven Anrufs können Sie auf das connectionStateChanged-Ereignis lauschen, um zu bestimmen, ob sich der Call Agent-Status von Connected in Disconnected ändert.

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

Die Anrufdurchstellung ist ein erweitertes Feature der zentralen Call-API. Sie müssen zunächst aufrufende Features aus dem aufrufenden SDK importieren:

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

Anschließend können Sie das API-Objekt für das Übertragungsfeature aus der Aufrufinstanz abrufen:

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

Am Durchstellen von Anrufen sind drei Parteien beteiligt:

Durchsteller: die Person, die die Durchstellungsanforderung auslöst.
Durchgestellter: die Person, deren Anruf durchgestellt wird.
Durchstellungsziel: die Person, an die der Anruf durchgestellt wird.

Übertragung an Teilnehmer*in:

Es besteht bereits eine Anrufverbindung zwischen dem Durchsteller und dem Durchgestellten. Der Durchsteller beschließt, den Anruf vom Durchgestellten an das Durchstellungsziel zu übertragen.
Der Durchsteller ruft die transfer-API auf.
Das Übertragungsziel empfängt einen eingehenden Anruf.

Zum Durchstellen eines aktuellen Anrufs können Sie die transfer-API verwenden. transfer verwendet die optionalen transferCallOptions, mit denen Sie ein Flag disableForwardingAndUnanswered festlegen können:

disableForwardingAndUnanswered = false: Wenn das Durchstellungsziel den durchgestellten Anruf nicht annimmt, werden die Einstellungen für Weiterleitung und Nichtannahme des Durchstellungsziels befolgt.
disableForwardingAndUnanswered = true: Wenn das Durchstellungsziel den durchgestellten Anruf nicht annimmt, wird der Durchstellungsversuch beendet.

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

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

Übertragung an Anruf:

Es besteht bereits eine Anrufverbindung zwischen dem Durchsteller und dem Durchgestellten.
Es besteht bereits eine Anrufverbindung zwischen Durchsteller*innen und dem Durchstellungsziel.
Die Durchsteller*innen beschließen, den Anruf mit den Durchgestellten an den Anruf mit dem Durchstellungsziel zu übertragen.
Der Durchsteller ruft die transfer-API auf.
Das Übertragungsziel empfängt einen eingehenden Anruf.

Zum Durchstellen eines aktuellen Anrufs können Sie die transfer-API verwenden.

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

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

Mit der transfer-API können Sie stateChanged abonnieren. Es verfügt auch über eine Übertragung state und error Eigenschaften

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

Der Übertragungsempfänger kann ein transferAccepted-Ereignis anhören. Der Listener für dieses Ereignis hat einen TransferEventArgs, der das Anrufobjekt des neuen Übertragungsaufrufs zwischen dem Übertragungsempfänger und dem Übertragungsziel enthält.

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

Die Durchsteller*innen können Ereignisse abonnieren, um den Status der Übertragung zu ändern. Wenn der Anruf an die Durchgestellten erfolgreich mit dem Übertragungsziel verbunden wurde, können die Durchsteller*innen den ursprünglichen Anruf mit den Durchgestellten beenden.

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

Durchstellen an das Voicemailsystem:

Es besteht eine Anrufverbindung zwischen dem Durchsteller und dem Durchgestellten.
Der Teams-Benutzerbezeichner der Voicemail des Zielteilnehmers ist bekannt.
Der Durchsteller entscheidet, den Anruf mit dem Durchgestellten mithilfe des Teams-Benutzerbezeichners des Zielteilnehmers an die Voicemail des Zielteilnehmers zu übertragen.
Der Durchsteller ruft die transfer-API auf.
Der Durchgestellte empfängt die Durchstellungsanforderung.

Zum Durchstellen eines aktuellen Anrufs können Sie die transfer-API verwenden.

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

Mit der transfer-API können Sie stateChanged abonnieren. Es verfügt auch über eine Übertragung state und error Eigenschaften

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

Der Übertragungsempfänger kann ein transferAccepted-Ereignis anhören. Der Listener für dieses Ereignis verfügt über ein Element vom Typ TransferEventArgs, das das Anrufobjekt der neuen Anrufdurchstellung zwischen dem Durchgestellten und der Voicemail des Zielteilnehmers enthält.

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

Die Durchsteller*innen können Ereignisse abonnieren, um den Status der Übertragung zu ändern. Wenn der Anruf für den Durchgestellten erfolgreich mit der Voicemail des Zielteilnehmers verbunden wurde, kann der Durchsteller den ursprünglichen Anruf mit dem Durchgestellten beenden.

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

Freigeben über