Met Call Automation kunnen ontwikkelaars aangepaste contextuele informatie doorgeven bij het routeren van oproepen. Ontwikkelaars kunnen metagegevens doorgeven over de aanroep, beller of andere informatie die relevant is voor hun toepassing of bedrijfslogica. Bedrijven kunnen oproepen vervolgens beheren en routeren in netwerken zonder dat ze zich zorgen hoeven te maken over het verliezen van context.
Het doorgeven van context wordt ondersteund door aangepaste headers op te geven. Deze optionele lijst met sleutel-waardeparen wordt opgenomen als onderdeel van AddParticipant of Transfer acties. De context wordt later als onderdeel van de IncomingCall event payload opgehaald.
Aangepaste oproepcontext wordt ook doorgestuurd naar het SIP (Session Initiation Protocol), dat zowel de aangepaste freeform-headers als de standaard UUI SIP-header (user-to-user information) bevat. Wanneer een inkomende oproep vanuit uw telefonienetwerk wordt gerouteerd, wordt de gegevensset van uw Session Border Controller (SBC) in de aangepaste headers en UUI op dezelfde manier opgenomen in de nettolading van de IncomingCall gebeurtenis.
Alle aangepaste contextgegevens zijn ondoorzichtig voor call automation- of SIP-protocollen en de inhoud ervan is niet gerelateerd aan alle basisfuncties.
In de volgende voorbeelden ziet u hoe u aan de slag kunt met behulp van aangepaste contextheaders in Gespreksautomatisering.
Prerequisites
- Lees het artikel over gespreksautomatiseringconcepten concepten waarin het actie-gebeurtenisprogrammeermodel en event callbacks worden beschreven.
- Meer informatie over de gebruikers-id's , zoals
CommunicationUserIdentifier PhoneNumberIdentifier, die in dit artikel worden gebruikt.
Voor alle codevoorbeelden is client het CallAutomationClient object dat u kunt maken, en callConnection is het CallConnection object dat u verkrijgt uit een Answer- of CreateCall-reactie. U kunt deze ook verkrijgen via callback-gebeurtenissen die door uw toepassing worden ontvangen.
Technische parameters
Call Automation ondersteunt maximaal vijf aangepaste SIP-headers en 1000 aangepaste VoIP-headers (Voice-over-IP). Ontwikkelaars kunnen een speciale header van gebruikers naar gebruiker opnemen als onderdeel van een SIP-headerlijst.
Aangepaste SIP-headersleutels kunnen nu beginnen met het voorvoegsel X-* of het voorvoegsel X-MS-Custom-* .
-
X-* wordt nieuw ondersteund.
-
X-MS-Custom-* blijft ondersteund voor achterwaartse compatibiliteit.
- Een ander X-MS-* voorvoegsel is gereserveerd en mag niet worden gebruikt.
De maximale lengte van een SIP-headersleutel is 64 tekens, inclusief het voorvoegsel, terwijl de maximale lengte van een SIP-headerwaarde 256 tekens is. De sleutel kan alfanumerieke tekens en de volgende symbolen bevatten:
`.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`
De SIP-headerwaarde bestaat ook uit alfanumerieke tekens en enkele geselecteerde symbolen, waaronder:
`=`, `;`, `.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`.
Opmerking
Dezelfde beperkingen gelden voor het configureren van SIP-headers op uw SBC.
Voor VoIP-header is de maximale lengte van een VoIP-headersleutel 64 tekens , terwijl de maximale lengte van een VoIP-headerwaarde 1024 tekens is. Deze headers kunnen zonder het aangepaste voorvoegsel worden verzonden.
Aangepaste context toevoegen wanneer u een deelnemer uitnodigt
// Invite an Azure 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");
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
addThisPerson.CustomCallingContext.AddSipX("header1", "customSipHeaderValue1");
// The provided key prefix is based on SipHeaderPrefix param: SipHeaderPrefix.X → 'X-{key}', SipHeaderPrefix.XmsCustom → 'X-MS-Custom-{key}'
addThisPerson.CustomCallingContext.AddSipX("header2", "customSipHeaderValue2", SipHeaderPrefix.X);
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);
// Invite an Azure 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");
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
callInvite.getCustomCallingContext().addSipX("header1", "customSipHeaderValue1");
// The provided key prefix is based on SipHeaderPrefix param: SipHeaderPrefix.X → 'X-{key}', SipHeaderPrefix.X_MS_CUSTOM → 'X-MS-Custom-{key}'
callInvite.getCustomCallingContext().addSipX("header2", "customSipHeaderValue2", SipHeaderPrefix.X);
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite);
Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();
// Invite an Azure 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" });
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" });
// The provided key prefix is based on sipHeaderPrefix param: X- → 'X-{key}', X-MS-Custom- → 'X-MS-Custom-{key}'
customCallingContext.push({ kind: "sipx", key: "headerName2", value: "headerValue2", sipHeaderPrefix: "X-" });
const addThisPerson = {
targetParticipant: { phoneNumber: "+16041234567" },
sourceCallIdNumber: callerIdNumber,
customCallingContext: customCallingContext,
};
const addParticipantResult = await callConnection.addParticipant(addThisPerson);
#Invite an Azure 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"
# Specify dict key with X-MS-Custom prefix
sip_headers["X-MS-Custom-headerName"] = "headerValue"
# Specify dict key with X- prefix
sip_headers["X-headerName2"] = "headerValue2"
target = PhoneNumberIdentifier("+16041234567")
result = call_connection_client.add_participant(
target,
sip_headers=sip_headers,
source_caller_id_number=caller_id_number
)
Een aangepaste context toevoegen tijdens een oproepoverdracht
//Transfer to an Azure 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");
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");
// The provided key prefix is based on SipHeaderPrefix param: SipHeaderPrefix.X → 'X-{key}', SipHeaderPrefix.XmsCustom → 'X-MS-Custom-{key}'
transferOption.CustomCallingContext.AddSipX("header2", "headerValue2", SipHeaderPrefix.X);
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption)
//Transfer to an Azure 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("<target_phoneNumber>");
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
options.getCustomCallingContext().addSipUui("UUIvalue");
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
options.getCustomCallingContext().addSipX("sipHeaderName", "value");
// The provided key prefix is based on SipHeaderPrefix param: SipHeaderPrefix.X → 'X-{key}', SipHeaderPrefix.X_MS_CUSTOM → 'X-MS-Custom-{key}'
options.getCustomCallingContext().addSipX("sipHeaderName2", "value2", SipHeaderPrefix.X);
Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();
//Transfer to an Azure 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: "<target_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" });
// The provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" });
// The provided key prefix is based on sipHeaderPrefix param: X- → 'X-{key}', X-MS-Custom- → 'X-MS-Custom-{key}'
customCallingContext.push({ kind: "sipx", key: "headerName2", value: "headerValue2", sipHeaderPrefix: "X-" });
options.customCallingContext = customCallingContext;
const result = await callConnection.transferCallToParticipant(transferDestination, options);
#Transfer to an Azure Communication Services user and include one VOIP header
transfer_destination = CommunicationUserIdentifier("<user_id>")
transferee = CommunicationUserIdentifier("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,
operation_context="Your context",
operationCallbackUrl="<url_endpoint>"
)
#Transfer a PSTN call to phone number and set UUI and custom SIP headers
transfer_destination = PhoneNumberIdentifier("<target_phoneNumber>")
transferee = PhoneNumberIdentifier("transferee_phoneNumber")
sip_headers={}
sip_headers["User-To-User"] = "uuivalue"
# Specify dict key with X-MS-Custom prefix
sip_headers["X-MS-Custom-headerName"] = "headerValue"
# Specify dict key with X- prefix
sip_headers["X-headerName2"] = "headerValue2"
result = call_connection_client.transfer_call_to_participant(
target_participant=transfer_destination,
transferee=transferee,
sip_headers=sip_headers,
operation_context="Your context",
operationCallbackUrl="<url_endpoint>"
)
Op dit moment wordt de overdracht van een VoIP-oproep naar een telefoonnummer niet ondersteund.
Aangepaste context lezen vanuit een binnenkomende oproepgebeurtenis
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
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
// 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
# 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
Verwante inhoud