Freigeben über

Durchstellen von Anrufen

Während eines aktiven Anrufs können Sie den Anruf an eine andere Person, Nummer oder voicemail übertragen. Hier erfahren Sie, wie Sie dazu vorgehen.

Voraussetzungen

Installieren des SDKs

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

Verwalten der SDK-Konnektivität mit der 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 Call Agent für Connected bedeutet, dass das Client-SDK verbunden ist und Benachrichtigungen von der Microsoft-Infrastruktur empfangen kann.

Getrennt: Der connectionState-Wert Call Agent für Disconnected 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 dem Client bei der Verbindung zur Microsoft-Infrastruktur auftritt, zeigt Call Agent nach vielen Versuchen den connectionIssue Fehler an.

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:

  • Transferor: Die Person, die die Übertragungsanforderung initiiert.
  • Transferee: Die Person, die übertragen wird.
  • Übertragungsziel: Die Person, an die der Anruf weitergeleitet wird.

Übertragung an Teilnehmer*in:

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

Um einen aktuellen Anruf zu übertragen, können Sie den transfer Vorgang verwenden. Der Vorgang transfer verwendet die optionale transferCallOptions, mit der Sie ein disableForwardingAndUnanswered-Flag 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:

  1. Es besteht bereits eine Anrufverbindung zwischen dem Durchsteller und dem Durchgestellten.
  2. Es besteht bereits eine Anrufverbindung zwischen Durchsteller*innen und dem Durchstellungsziel.
  3. Die Durchsteller*innen beschließen, den Anruf mit den Durchgestellten an den Anruf mit dem Durchstellungsziel zu übertragen.
  4. Der Transferor ruft den transfer Vorgang auf.
  5. Das Übertragungsziel empfängt einen eingehenden Anruf.

Um einen aktuellen Anruf zu übertragen, verwenden Sie 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> });

Mit dem transfer Aobject 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 TransferEventArgs, das das Aufrufobjekt 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:

  1. Es gibt einen verbundenen Anruf zwischen dem Überträger und dem Empfänger.
  2. Der Teams-Benutzerbezeichner der Voicemail des Zielteilnehmers ist bekannt.
  3. Der Durchsteller entscheidet, den Anruf mit dem Durchgestellten mithilfe des Teams-Benutzerbezeichners des Zielteilnehmers an die Voicemail des Zielteilnehmers zu übertragen.
  4. Der Übertragender ruft transfer an.
  5. Der Durchgestellte empfängt die Durchstellungsanforderung.

Um einen aktuellen Anruf zu übertragen, verwenden Sie 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 });

Der transfer-Vorgang ermöglicht es Ihnen, stateChanged zu 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 TransferEventArgs, welches das Anrufobjekt der neuen Anrufdurchstellung zwischen dem Übertragungsempfänger und dem Voicemailsystem 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 an den Transferee erfolgreich mit der Voicemail des Zielteilnehmers verbunden wurde, kann der Transferor den ursprünglichen Anruf mit "Transferee" auflegen.

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

Anfängliche Anrufer- und Übertragungsinformationen

Wenn ein Teilnehmer einen Anruf weiterleitet oder überträgt, wird transferInfo mit Informationen über den vorherigen Anrufstatus ausgefüllt. Diese Informationen enthalten callerInfo, die den anfänglichen Aufrufer beschreiben und transferorInfo, die die Entität beschreibt, die den Anruf überträgt oder weiterleitet.

Wenn beispielsweise ein Azure Communication Services-Benutzer einen Anruf an eine Teams-Anrufwarteschleife platziert, die dann den Anruf an einen Microsoft 365-Benutzer verteilt, geben Sie den callerInfo Azure Communication Services-Benutzer an und geben die transferorInfo Teams-Anrufwarteschleife an. Anrufer und Transferoren haben die Möglichkeit, ihre displayNameDaten zu aktualisieren. Wenn sie es tun, löst die Änderung die callerInfoChanged oder transferorInfoChanged Ereignisse aus.

Weitere Informationen zu Änderungsereignissen finden Sie unter "Event: callerInfoChanged " und "Event: transferorInfoChanged". Änderungsereignisse gelten für alle Anrufe und für jede Identität, einschließlich Bring Your Own Identity (BYOI) oder Microsoft 365.

const incomingCallHandler = async (args: { incomingCall: IncomingCall }) => {
    const incomingCall = args.incomingCall;
    // Get information about initial caller
    const callerInfo = incomingCall.callerInfo
    // Get information about initial caller
    const transferorInfo = incomingCall.transferorInfo
};

Nächste Schritte

  • Last updated on