Teilen über

Übergeben von Kontextinformationen

  • Artikel

In diesem Artikel erfahren Sie, wie Sie beim Weiterleiten von Anrufen mit Azure Communication Services Calling-SDKs benutzerdefinierte Kontextinformationen übergeben. Mithilfe dieser Funktion können Benutzer Metadaten über den Anruf oder die angerufene Person oder andere Informationen übergeben, die für ihre Anwendung oder Geschäftslogik relevant sind.

Unterstützte Kontextinformationen umfassen sowohl benutzerdefinierte Freiform-Header als auch den standardmäßigen UUI-SIP-Header (User-to-User Information). Wenn Sie einen eingehenden Anruf erhalten, sind die benutzerdefinierten Header und UUI ebenfalls in der incomingCall-Payload enthalten.

Alle benutzerdefinierten Kontextdaten sind für Calling SDK- oder SIP-Protokolle nicht sichtbar, und ihre Inhalte sind nicht mit grundlegenden Funktionen verknüpft.

Wichtig

Die in diesem Artikel beschriebenen Funktionen befinden sich derzeit in der öffentlichen Vorschauphase. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und ist nicht für Produktionsworkloads vorgesehen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Voraussetzungen

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

Tätigen eines Anrufs mit Kontextinformationen

// Set up customContext
this.callOptions.customContext = {
    userToUser: <USER_TO_USER_VALUE>,
    xHeaders: [
        { key: <CUSTOM_HEADER_KEY>, value: <CUSTOM_HEADER_VALUE> },
    ]
};

Verwenden Sie für einen 1:1-Anruf bei einem Benutzer den folgenden Code:

const userId = { communicationUserId: 'ACS_USER_ID' };
this.currentCall = this.callAgent.startCall([userId], this.callOptions);

Um einen Anruf an ein PSTN (Public Switched Telephone Network) zu tätigen, verwenden Sie die Methode startCall für callAgent, und übergeben Sie den PhoneNumberIdentifier des Empfängers. Die Communication Services-Ressource muss so konfiguriert werden, dass Anrufe über das Telefonfestnetz möglich sind.

Wenn Sie eine Telefonfestnetznummer anrufen, geben Sie Ihre alternative Anrufer-ID an. Eine alternative Anrufer-ID bezieht sich auf eine Telefonnummer (basierend auf dem E.164-Standard), die den Anrufer in einem PSTN-Anruf identifiziert. Dies ist die Telefonnummer, die dem Anrufempfänger bei einem eingehenden Anruf angezeigt wird.

Verwenden Sie für einen 1:1-Anruf einer PSTN-Nummer den folgenden Code:

const phoneNumber = { phoneNumber: <ACS_PHONE_NUMBER> };
this.callOptions.alternateCallerId = { phoneNumber: <ALTERNATE_CALLER_ID>}
this.currentCall = this.callAgent.startCall([phoneNumber], this.callOptions);

Hinweis

Das Übergeben kontextbezogener Informationen in Gruppenanrufen und Szenarien zum Hinzufügen von Teilnehmern werden nicht unterstützt.

Eingehenden Anruf entgegennehmen

Die callAgent-Instanz gibt das Ereignis incomingCall aus, wenn die angemeldete Identität einen eingehenden Anruf empfängt. Um auf dieses Ereignis zu lauschen und Kontextinformationen zu extrahieren, abonnieren Sie es mit einer der folgenden Optionen:

const incomingCallHandler = async (args: { incomingCall: IncomingCall }) => {
    const incomingCall = args.incomingCall;

    // receiving customContext
    const customContext = args.incomingCall.customContext;

    // Get incoming call ID
    var incomingCallId = incomingCall.id

    // Get information about this Call. This API is provided as a preview for developers
    // and may change based on feedback that we receive. Do not use this API in a production environment.
    // To use this api please use 'beta' release of Azure Communication Services Calling Web SDK
    var callInfo = incomingCall.info;

    // Get information about caller
    var callerInfo = incomingCall.callerInfo

    // Accept the call
    var call = await incomingCall.accept();

    // Reject the call
    incomingCall.reject();

    // Subscribe to callEnded event and get the call end reason
     incomingCall.on('callEnded', args => {
        console.log(args.callEndReason);
    });

    // callEndReason is also a property of IncomingCall
    var callEndReason = incomingCall.callEndReason;
};
callAgentInstance.on('incomingCall', incomingCallHandler);

Nächste Schritte