在呼叫之間傳遞關係型數據

呼叫自動化可讓開發人員在路由呼叫時傳遞自定義內容資訊。 開發人員可以傳遞有關呼叫、呼叫者或任何其他與其應用程式或商業規則相關信息的元數據。 然後，企業可以跨網路管理和路由通話，而不必擔心失去內容。

透過指定自定義標頭來支援傳遞上下文。 這個選用的索引鍵/值組清單會包含作為 AddParticipant 或 Transfer 動作的一部分。 稍後會隨著IncomingCall 事件裝載的一部分擷取內容。

自定義呼叫內容也會轉送至會話初始協定 (SIP)，其中包含自由格式的自定義標頭和標準使用者對使用者資訊 (UUI) 的 SIP 標頭。 從您的電話語音網路路由輸入通話時，自訂標頭中來自您的工作階段邊界控制器 (SBC) 的資料集和 UUI 也同樣會包含在 IncomingCall 事件裝載中。

所有自定義情境數據對於呼叫自動化或 SIP 通訊協定來說都是不透明的，其內容與任何基本功能無關。

下列範例示範如何在呼叫自動化中使用自定義內容標頭來開始使用。

Prerequisites

  • 閱讀呼叫自動化 概念一文 ，說明動作事件程序設計模型和事件回呼。
  • 瞭解本文中使用的 使用者識別碼 ，例如 CommunicationUserIdentifier 和 PhoneNumberIdentifier' 。

針對所有程式代碼範例， client 是 CallAutomationClient 您可以建立的物件，而 callConnection 是您 CallConnection 從 Answer 或 CreateCall 回應取得的物件。 您也可以從應用程式接收的回呼事件取得它。

技術參數

通話自動化最多可支援五個自定義 SIP 標頭和 1,000 個自定義語音轉播 （VoIP） 標頭。 開發人員可以在 SIP 標頭清單包含專用的使用者對使用者標頭。

自訂 SIP 標頭金鑰現在可以以 X-* 前綴或 X-MS-Custom-* 前綴開頭。

  • X-* 現在支援。
  • X-MS-Custom-* 仍支援向下相容。
  • 任何其他 X-MS-* 前綴皆為保留，不得使用。

SIP 標頭金鑰的最大長度為 64 個字元（含前綴），而 SIP 標頭值的最大長度為 256 個字元。 該鍵可包含字母數字及以下符號：

`.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`

SIP 標頭值也包含字母數字和少數選定的符號，包括：

`=`, `;`, `.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`.

備註

在你的 SBC 上設定 SIP 標頭時，也有同樣的限制。

對於 VoIP 標頭，VoIP 標頭金鑰的最大長度為 64 個字元 ，而 VoIP 標頭值的最大長度為 1,024 個字元。 這些標頭可以不使用自訂前綴傳送。

邀請參與者時新增自定義內容

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

在通話轉移期間新增自定義內容

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

從傳入呼叫事件讀取自定義內容

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

相關內容

  • Last updated on