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

csharp

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

Java

// Invite a communication services user and include one VOIP header
CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
callInvite.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite);
Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();

// Invite a PSTN user and set UUI and custom SIP headers
PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+16044561234");
CallInvite callInvite = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);
callInvite.getCustomCallingContext().addSipUui("value");
callInvite.getCustomCallingContext().addSipX("header1", "customSipHeaderValue1");
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite);
Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();

JavaScript

// Invite a communication services user and include one VOIP header
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({ kind: "voip", key: "voipHeaderName", value: "voipHeaderValue" })
const addThisPerson = {
    targetParticipant: { communicationUserId: "<acs_user_id>" },
    customCallingContext: customCallingContext,
};
const addParticipantResult = await callConnection.addParticipant(addThisPerson);

// Invite a PSTN user and set UUI and custom SIP headers
const callerIdNumber = { phoneNumber: "+16044561234" };
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({ kind: "sipuui", key: "", value: "value" });
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
const addThisPerson = {
    targetParticipant: { phoneNumber: "+16041234567" }, 
    sourceCallIdNumber: callerIdNumber,
    customCallingContext: customCallingContext,
};
const addParticipantResult = await callConnection.addParticipant(addThisPerson);

Python

#Invite a communication services user and include one VOIP header
voip_headers = {"voipHeaderName", "voipHeaderValue"}
target = CommunicationUserIdentifier("<acs_user_id>")
result = call_connection_client.add_participant(
    target,
    voip_headers=voip_headers
)

#Invite a PSTN user and set UUI and custom SIP headers
caller_id_number = PhoneNumberIdentifier("+16044561234")
sip_headers = {}
sip_headers["User-To-User"] = "value"
sip_headers["X-MS-Custom-headerName"] = "headerValue"
target = PhoneNumberIdentifier("+16041234567")
result = call_connection_client.add_participant(
    target,
    sip_headers=sip_headers,
    source_caller_id_number=caller_id_number
)

Hinzufügen eines benutzerdefinierten Kontexts während der Anrufdurchstellung

csharp

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

Java

//Transfer to communication services user and include one VOIP header
CommunicationIdentifier transferDestination = new CommunicationUserIdentifier("<user_id>");
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
options.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");
Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();

//Transfer a PSTN call to phone number and set UUI and custom SIP headers
CommunicationIdentifier transferDestination = new PhoneNumberIdentifier("<taget_phoneNumber>");
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
options.getCustomCallingContext().addSipUui("UUIvalue");
options.getCustomCallingContext().addSipX("sipHeaderName", "value");
Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();

JavaScript

//Transfer to communication services user and include one VOIP header
const transferDestination = { communicationUserId: "<user_id>" };
const transferee = { communicationUserId: "<transferee_user_id>" };
const options = { transferee: transferee, operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({ kind: "voip", key: "customVoipHeader1", value: "customVoipHeaderValue1" })
options.customCallingContext = customCallingContext;
const result = await callConnection.transferCallToParticipant(transferDestination, options);

//Transfer a PSTN call to phone number and set UUI and custom SIP headers
const transferDestination = { phoneNumber: "<taget_phoneNumber>" };
const transferee = { phoneNumber: "<transferee_phoneNumber>" };
const options = { transferee: transferee, operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({ kind: "sipuui", key: "", value: "uuivalue" });
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
options.customCallingContext = customCallingContext;
const result = await callConnection.transferCallToParticipant(transferDestination, options);

Python

#Transfer to communication services user and include one VOIP header
transfer_destination = CommunicationUserIdentifier("<user_id>")
transferee = CommnunicationUserIdentifer("transferee_user_id")
voip_headers = {"customVoipHeader1", "customVoipHeaderValue1"}
result = call_connection_client.transfer_call_to_participant(
    target_participant=transfer_destination,
    transferee=transferee,
    voip_headers=voip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

#Transfer a PSTN call to phone number and set UUI and custom SIP headers
transfer_destination = PhoneNumberIdentifer("<target_phoneNumber>")
transferee = PhoneNumberIdentifer("transferee_phoneNumber")
sip_headers={}
sip_headers["X-MS-Custom-headerName"] = "headerValue"
sip_headers["User-To-User"] = "uuivalue"
result = call_connection_client.transfer_call_to_participant(
    target_participant=transfer_destination,
    transferee=transferee,
    sip_headers=sip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

Das Durchstellen eines VoIP-Anrufs an eine Telefonnummer wird derzeit nicht unterstützt.

Lesen eines benutzerdefinierten Kontexts aus einem eingehenden Anrufereignis

csharp

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

Java

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

// Inspect dictionary with key/value pairs
Map<String, String> voipHeaders = callCustomContext.getVoipHeaders();
Map<String, String> sipHeaders = callCustomContext.getSipHeaders();

// Get SIP UUI header value
String userToUser = sipHeaders.get("user-To-User");

// Proceed to answer or reject call as usual

JavaScript

// Retrieve incoming call custom context
const callCustomContext = incomingEvent.customContext;

// Inspect dictionary with key/value pairs
const voipHeaders = callCustomContext.voipHeaders;
const sipHeaders = callCustomContext.sipHeaders;

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

// Proceed to answer or reject call as usual

Python

# Retrieve incoming call custom context
callCustomContext = incomingEvent.customContext

# Inspect dictionary with key/value pairs
voipHeaders = callCustomContext.voipHeaders
sipHeaders = callCustomContext.sipHeaders

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

# Proceed to answer or reject call as usual

Zusätzliche Ressourcen

• Eine Beispielnutzlast des eingehenden Anrufs finden Sie in diesem Leitfaden.

• Erfahren Sie mehr über SIP-Protokolldetails für das direkte Routing.