Verwenden des ACS Calling SDK zum Übergeben kontextbezogener UUI-Daten (User-to-User Informationen, Benutzer-zu-Benutzer-Informationen) zwischen Anrufen
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.
Das Azure Communication Services (ACS) WebJS SDK bietet Entwicklern die Möglichkeit, benutzerdefinierte Kontextdaten (eingeschlossen als Header des anrufenden Objekts) einzuschließen, wenn Anrufe von einer Person an eine andere weitergeleitet werden. Diese Informationen, auch als UUI-Daten (User-to-User Information) oder Anrufsteuerungs-UUI-Daten bezeichnet, sind eine kleine Datenmenge, die von einer Anwendung eingefügt wird, die den Anruf initiiert. Die UUI-Daten sind für Endbenutzer, die einen Anruf tätigen, nicht transparent.
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.
Entwickler können diesen Kontext mithilfe von benutzerdefinierten Headern übergeben, die aus optionalen Schlüssel-Wert-Paaren bestehen. Diese Paare können in die Aktionen „AddParticipant“ oder „Transfer“ im Calling SDK aufgenommen werden. Nach dem Hinzufügen können Sie die Datennutzlast lesen, während der Anruf zwischen Endpunkten wechselt. Durch die effiziente Suche nach diesen Metadaten und ihre Verknüpfung mit dem Anruf können Entwickler externe Datenbankabfragen vermeiden, und ihnen stehen Inhaltsinformationen sofort innerhalb des Anrufobjekts zur Verfügung.
Der benutzerdefinierte Anrufkontext kann mithilfe des SIP-Protokolls an SIP-Endpunkte übertragen werden. Diese Übertragung umfasst sowohl die benutzerdefinierten Header als auch den standardmäßigen UUI-SIP-Header (User-to-User Information). Wenn ein eingehender Anruf von Ihrem Telefonfestnetz weitergeleitet wird, werden die Daten vom SBC (Session Border Controller) in den benutzerdefinierten Headern und UUI-Daten auch in die IncomingCall-Ereignisnutzdaten aufgenommen.
Es ist wichtig zu beachten, dass alle benutzerdefinierten Kontextdaten für das Calling SDK transparent bleiben und sich nicht auf die grundlegenden Funktionen des SDK beziehen, wenn sie in SIP-Protokollen verwendet werden. Im Folgenden finden Sie ein Tutorial, das Sie beim Hinzufügen von benutzerdefinierten Kontextheadern bei Verwendung des WebJS SDK unterstützt.
Wichtig
Um die Option zum Übergeben von UUI-Dateien mithilfe des Calling SDK nutzen zu können, müssen Sie das allgemein verfügbare Calling WebJS SDK oder die Public Preview-Version 1.29.1 oder höher verwenden.
Technische Parameter
Das Calling SDK unterstützt das Hinzufügen von bis zu 5 benutzerdefinierten SIP-Headern und 1.000 benutzerdefinierten VoIP-Headern. Darüber hinaus können Entwickler einen dedizierten User-To-User-Header als Teil der SIP-Headerliste einschließen.
Die maximale Länge eines SIP-Headerschlüssels beträgt 64 Zeichen, einschließlich des Präfix „X-MS-Custom“. Beachten Sie, dass beim Hinzufügen des SIP-Headers vom Calling SDK automatisch das Präfix „X-MS-Custom“ hinzugefügt wird. (Es kann angezeigt werden, wenn Sie den SIP-Header mit dem Paketinspektor überprüfen.)
Der SIP-Headerschlüssel kann aus alphanumerischen Zeichen und einigen ausgewählten Symbolen bestehen. Hierzu zählen ., !, %, *, _, +, ~, -. Die maximale Länge eines SIP-Headerwerts beträgt 256 Zeichen. Die gleichen Einschränkungen gelten beim Konfigurieren der SIP-Header auf Ihrem SBC. Der SIP-Headerwert kann aus alphanumerischen Zeichen und einigen ausgewählten Symbolen bestehen. Hierzu zählen =, ;, ., !, %, *, _, +, ~, -.
Die maximale Länge eines VOIP-Headerschlüssels beträgt 64 Zeichen. Die maximale Länge eines VOIP-Headerwerts beträgt 1024 Zeichen.
Wenn Sie diese benutzerdefinierten Header als Entwickler hinzufügen, können Sie wählen, ob Sie nur SIP-Header, nur VoIP-Header oder beide hinzufügen möchten.
Hinweis
Das Hinzufügen benutzerdefinierter UUI-Header wird derzeit nur unterstützt, wenn ein 1:1-Anruf initiiert wird. Das Übergeben von UUI-Headern in Gruppenaufrufen wird derzeit nicht unterstützt. Um dies nach dem Starten eines 1:1-Anrufs zu umgehen, können Sie zusätzliche Teilnehmer aufnehmen und gleichzeitig die UUI-Daten innerhalb der Anrufe beibehalten.
Ausführliche Informationen zur API für benutzerdefinierte Kontextschnittstellen finden Sie auf der Seite Benutzerdefinierte Kontext-API-Ressource.
Tätigen eines Anrufs mit UUI-Daten (User-to-User Information)
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
Lesen und Analysieren von UUI-Headern in einem Anruf
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:
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});