Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesem Artikel wird beschrieben, wie Benutzer-zu-Benutzer-Informationen (UUI) in einer Kopfzeile übergeben werden, wenn Anrufe mit Azure Communication Services Calling SDKs weitergeleitet werden. Mit dieser Funktion können Benutzer Metadaten über den Anruf, den Angerufenen oder andere Informationen übergeben, die für ihre Anwendung oder Geschäftslogik relevant sind.
Mit dem Azure Communication Services WebJS SDK können Entwickler benutzerdefinierte Kontextdaten einbinden, die als Header im Anrufobjekt enthalten sind, wenn Anrufe von einer Person an eine andere weitergeleitet werden. Diese Informationen, auch als Benutzer-zu-Benutzer-Informationen (UUI)-Daten oder UUI-Daten der Anrufsteuerung 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.
Kontextbezogene Informationen, die unterstützt werden, umfassen sowohl benutzerdefinierte Freeform-Header als auch den standardmäßigen UUI-SIP-Header. Wenn Sie einen eingehenden Anruf erhalten, werden außerdem die benutzerdefinierten Header und UUI in die incomingCall Nutzlast einbezogen.
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 AddParticipant oder Transfer Aktionen im aufrufenden SDK eingeschlossen 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. 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 UUI-Daten mit dem Anruf-SDK zu übergeben, müssen Sie das WebJS SDK in der GA- oder öffentlichen Vorschauversion 1.29.1 oder höher verwenden.
Technische Parameter
Das aufrufende SDK unterstützt das Hinzufügen von bis zu fünf (5) benutzerdefinierten SIP-Headern und 1000 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“. Wenn Sie den SIP-Header zum aufrufenden SDK hinzufügen, wird automatisch das X-MS-Custom- Präfix hinzugefügt, das Sie sehen können, indem Sie den SIP-Header mit Paketinspektor prüfen.
Die SIP-Kopfschlüssel kann aus alphanumerischen Zeichen und einigen ausgewählten Symbolen bestehen, darunter ., !, %, *, _, +, ~, -. Die maximale Länge eines SIP-Headerwerts beträgt 256 Zeichen. Die gleichen Einschränkungen gelten beim Konfigurieren der SIP-Header auf Dem Session Border Controller (SBC). Der SIP-Headerwert kann aus alphanumerischen Zeichen und einigen ausgewählten Symbolen bestehen, einschließlich =, ;, ., !, %, *, _, +, ~, -.
Die maximale Länge eines VOIP-Headerschlüssels beträgt 64 Zeichen. Die maximale Länge des 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
Beim Senden von SIP-Headern empfehlen wir, die Headerwerte mit URL-Codierung zu kodieren. Selbst wenn die Werte nur gültige Zeichen enthalten, können zwischengeschaltete Netzbetreiber sie möglicherweise nicht richtig analysieren, es sei denn, sie sind URL-codiert.
Hinweis
Das Hinzufügen benutzerdefinierter UUI-Header wird derzeit nur unterstützt, wenn ein 1:1-Anruf initiiert wird. Das Übergeben von Benutzer-zu-Benutzer-Informationsheadern in Gruppenaufrufen wird derzeit nicht unterstützt. Um diese Einschränkung nach dem Starten des 1:1-Anrufs zu umgehen, können Sie Teilnehmer hinzufügen und gleichzeitig die Benutzer-zu-Benutzer-Informationen innerhalb der Anrufe verwalten.
Ausführliche Informationen zur benutzerdefinierten Kontextschnittstellen-API finden Sie in der benutzerdefinierten 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`);
}
}
});