Med Samtalsautomatisering kan utvecklare skicka anpassad kontextbaserad information vid routning av anrop. Utvecklare kan skicka metadata om samtalet, anroparen eller annan information som är relevant för deras program eller affärslogik. Företag kan sedan hantera och dirigera samtal mellan nätverk utan att behöva oroa sig för att förlora kontexten.
Det går att skicka kontexten genom att ange anpassade rubriker. Den här valfria listan över nyckel/värde-par ingår som en del av AddParticipant eller Transfer åtgärder. Kontexten hämtas senare som en del av IncomingCall händelsenyttolasten.
Den anpassade samtalskontexten vidarebefordras också till SIP (Session Initiation Protocol), som innehåller både de fria anpassade rubrikerna och SIP-huvudet för användar-till-användare (UUI). När ett inkommande samtal från ditt telefoninätverk routas, inkluderas datauppsättningen från din sessionsgränskontroller (SBC) i de anpassade rubrikerna och UUI i händelselasten för IncomingCall.
Alla anpassade kontextdata är ogenomskinliga för Call Automation- eller SIP-protokoll och dess innehåll är inte relaterat till några grundläggande funktioner.
Följande exempel visar hur du kommer igång med hjälp av anpassade kontextrubriker i Samtalsautomatisering.
Prerequisites
För alla kodexempel client är det CallAutomationClient objekt som du kan skapa och callConnection är det CallConnection objekt som du hämtar från ett Answer eller CreateCall ett svar. Du kan också hämta den från återuppringningshändelser som din applikation tar emot.
Technical parameters
Call Automation stöder upp till fem anpassade SIP-huvuden och 1 000 anpassade VoIP-huvuden (voice-over-IP). Utvecklare kan inkludera ett dedikerat användar-till-användare-huvud som en del av en SIP-rubriklista.
Den anpassade SIP-huvudnyckeln måste börja med ett obligatoriskt X-MS-Custom- prefix. Den maximala längden på en SIP-huvudnyckel är 64 tecken, inklusive prefixet X-MS-Custom . SIP-huvudnyckeln består av alfanumeriska tecken och några markerade symboler, som inkluderar ., !, %, *, _, +, ~och -. Den maximala längden på ett SIP-huvudvärde är 256 tecken. Samma begränsningar gäller när du konfigurerar SIP-huvudena på din SBC. SIP-huvudvärdet består av alfanumeriska tecken och några markerade symboler, som inkluderar =, ;, ., !, %, *, _, +, ~och -.
Den maximala längden på en VoIP-huvudnyckel är 64 tecken. Dessa huvuden kan skickas utan prefixet x-MS-Custom . Den maximala längden på ett VoIP-rubrikvärde är 1 024 tecken.
Lägg till anpassad kontext när du bjuder in en deltagare
// 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");
// 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);
// 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");
callInvite.getCustomCallingContext().addSipX("header1", "customSipHeaderValue1");
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" });
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
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"
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
)
Lägga till en anpassad kontext under en samtalsöverföring
//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");
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");
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");
options.getCustomCallingContext().addSipX("sipHeaderName", "value");
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" });
customCallingContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
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["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,
operation_context="Your context",
operationCallbackUrl="<url_endpoint>"
)
För närvarande stöds inte överföring av ett VoIP-samtal till ett telefonnummer.
Läsa anpassad kontext från en inkommande samtalshändelse
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
Related content