Freigeben über


So übergeben Sie Kontextdaten zwischen Aufrufen

Mit der Anrufautomatisierung können Entwickler beim Weiterleiten von Anrufen benutzerdefinierte Kontextinformationen weitergeben. Entwickler können Metadaten über den Anruf, den Angerufenen oder andere Informationen übergeben, die für ihre Anwendung oder Geschäftslogik relevant sind. Auf diese Weise können Unternehmen Anrufe über Netzwerke hinweg verwalten und weiterleiten, ohne sich Gedanken über den Verlust des Kontexts machen zu müssen.

Das Übergeben von Kontext wird durch Angeben von benutzerdefinierten Headern unterstützt. Hierbei handelt es sich um eine optionale Liste von Schlüssel-Wert-Paaren, die als Teil von AddParticipant- oder Transfer-Aktionen eingeschlossen werden können. Der Kontext kann später als Teil der IncomingCall-Ereignisnutzlast abgerufen werden.

Benutzerdefinierter Anrufkontext wird auch an das SIP-Protokoll weitergeleitet, dies umfasst sowohl die benutzerdefinierten Freeform-Header als auch den standardmäßigen User-to-User Information (UUI)-SIP-Header. Beim Routing eines eingehenden Anrufs aus Ihrem Telefonienetzwerk wird der Datensatz aus Ihrem SBC in den benutzerdefinierten Headern und UUI ähnlich in der IncomingCall-Ereignisnutzlast enthalten.

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

Im Folgenden finden Sie Beispiele für die ersten Schritte mit benutzerdefinierten Kontextheadern in der Anrufautomatisierung.

Als Voraussetzung wird empfohlen, diese Artikel zu lesen, um diesen Leitfaden optimal nutzen zu können:

  • Im Leitfaden mit Konzepten der Anrufautomatisierung werden das Programmiermodell für Aktionen und Ereignisse sowie Ereignisrückrufe beschrieben.
  • Erfahren Sie mehr über Benutzerbezeichner wie CommunicationUserIdentifier und PhoneNumberIdentifier, die in diesem Leitfaden verwendet werden.

Für alle Codebeispiele ist client das CallAutomationClient-Objekt, das wie gezeigt erstellt werden kann, und callConnection ist das CallConnection-Objekt, das aus der Antwort oder der CreateCall-Antwort abgerufen wird. Sie können es auch aus Rückrufereignissen abrufen, die von Ihrer Anwendung empfangen wurden.

Technische Parameter

Die Anrufautomatisierung unterstützt bis zu 5 benutzerdefinierte SIP-Header und 1000 benutzerdefinierte VOIP-Header. Darüber hinaus können Entwickler einen dedizierten User-To-User-Header als Teil der SIP-Headerliste einschließen.

Der benutzerdefinierte SIP-Headerschlüssel muss mit dem obligatorischen Präfix „X-MS-Custom-“ beginnen. Die maximale Länge eines SIP-Headerschlüssels beträgt 64 Zeichen, einschließlich des Präfix „X-MS-Custom“. 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. Diese Header können ohne den Präfix „x-MS-Custom“ gesendet werden. Die maximale Länge eines VOIP-Headerwerts beträgt 1024 Zeichen.

Hinzufügen eines benutzerdefinierten Kontexts beim Einladen eines Teilnehmers

// Invite a communication services user and include one VOIP header
var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
addThisPerson.CustomCallingContext.AddVoip("myHeader", "myValue");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);
// Invite a PSTN user and set UUI and custom SIP headers
var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); 
var addThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);

// Set custom UUI header. This key is sent on SIP protocol as User-to-User
addThisPerson.CustomCallingContext.AddSipUui("value");

// This provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
addThisPerson.CustomCallingContext.AddSipX("header1", "customSipHeaderValue1");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);

Hinzufügen eines benutzerdefinierten Kontexts während der Anrufdurchstellung

//Transfer to communication services user and include one VOIP header
var transferDestination = new CommunicationUserIdentifier("<user_id>"); 
var transferOption = new TransferToParticipantOptions(transferDestination);   
var transferOption = new TransferToParticipantOptions(transferDestination) {
    OperationContext = "<Your_context>",
    OperationCallbackUri = new Uri("<uri_endpoint>") // Sending event to a non-default endpoint.
};
transferOption.CustomCallingContext.AddVoip("customVoipHeader1", "customVoipHeaderValue1");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

//Transfer a PSTN call to phone number and set UUI and custom SIP headers
var transferDestination = new PhoneNumberIdentifier("<target_phoneNumber>");
var transferOption = new TransferToParticipantOptions(transferDestination);
transferOption.CustomCallingContext.AddSipUui("uuivalue");
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption)

Lesen eines benutzerdefinierten Kontexts aus einem eingehenden Anrufereignis

AcsIncomingCallEventData incomingEvent = <incoming call event from Event Grid>;
// Retrieve incoming call custom context
AcsIncomingCallCustomContext callCustomContext = incomingEvent.CustomContext;

// Inspect dictionary with key/value pairs
var voipHeaders = callCustomContext.VoipHeaders;
var sipHeaders = callCustomContext.SipHeaders;

// Get SIP UUI header value
var userToUser = sipHeaders["user-To-User"]

// Proceed to answer or reject call as usual

Zusätzliche Ressourcen