Передача контекстных данных между вызовами

Автоматизация вызовов позволяет разработчикам передавать пользовательские контекстные сведения при маршрутизации вызовов. Разработчики могут передавать метаданные о вызове, вызывающем объекте или любой другой информации, относящуюся к их приложению или бизнес-логике. Это позволяет предприятиям управлять и маршрутизировать вызовы между сетями, не беспокоясь о потере контекста.

Контекст передачи поддерживается путем указания пользовательских заголовков. Это необязательный список пар "ключ-значение", которые могут быть включены в состав AddParticipant или Transfer действия. Контекст можно получить позже в рамках полезных IncomingCall данных события.

Контекст пользовательского вызова также перенаправлен в протокол SIP, в том числе пользовательские заголовки freeform, а также стандартный заголовок SIP для пользователей и пользователей (UUI). При маршрутизации входящего вызова из телефонной сети набор данных из SBC в пользовательских заголовках и UUI также включается в IncomingCall полезные данные события.

Все пользовательские данные контекста непрозрачны для протоколов автоматизации вызовов или SIP, а его содержимое не связано с основными функциями.

Ниже приведены примеры по началу работы с пользовательскими заголовками контекста в службе автоматизации вызовов.

В качестве необходимых условий мы рекомендуем ознакомиться с этими статьями, чтобы получить большую часть этого руководства:

• Основные понятия службы автоматизации вызовов, описывающие модель программирования действий и обратные вызовы событий.
• Сведения об идентификаторах пользователей, таких как CommunicationUserIdentifier и Телефон NumberIdentifier, используемых в этом руководстве.

Для всех примеров client кода используется объект CallAutomationClient, который можно создать как показано и callConnection является объектом Call Подключение ion, полученным из ответа Answer или CreateCall. Вы также можете получить его из событий обратного вызова, полученных приложением.

Технические параметры

Служба автоматизации вызовов поддерживает до 5 пользовательских заголовков SIP и 1000 пользовательских заголовков VOIP. Кроме того, разработчики могут включать выделенный заголовок user-to-User в составе списка заголовков SIP.

Пользовательский ключ заголовка SIP должен начинаться с обязательного префикса X-MS-Custom-. Максимальная длина ключа заголовка SIP составляет 64 символов, включая префикс X-MS-Custom. Ключ заголовка SIP может состоять из буквенно-цифровых символов и нескольких выбранных символов, которые включают ., !, +%. ~-*_ Максимальная длина значения заголовка SIP составляет 256 символов. Те же ограничения применяются при настройке заголовков SIP в SBC. Значение заголовка SIP может состоять из буквенно-цифровых символов и нескольких выбранных символов, включая =, !;.%*_+~-

Максимальная длина ключа заголовка VOIP составляет 64 символов. Эти заголовки можно отправлять без префикса x-MS-Custom. Максимальная длина значения заголовка VOIP составляет 1024 символов.

Добавление пользовательского контекста при приглашении участника

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
)

Добавление пользовательского контекста во время передачи вызовов

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

Перенос звонка VoIP на номер телефона в настоящее время не поддерживается.

Чтение пользовательского контекста из входящего события вызова

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

Дополнительные ресурсы

• Пример полезных данных входящего вызова см. в этом руководстве.

• Дополнительные сведения о протоколе SIP для прямой маршрутизации.