通話間でコンテキストデータを渡す

呼び出し自動化を使用すると、開発者は呼び出しをルーティングするときにカスタムコンテキスト情報を渡すことができます。開発者は、呼び出し、呼び出し元、またはアプリケーションまたはビジネスロジックに関連するその他の情報に関するメタデータを渡すことができます。その後、企業は、コンテキストの損失を心配することなく、ネットワーク間で通話を管理およびルーティングできます。

コンテキストの受け渡しは、カスタムヘッダーを指定することでサポートされます。このオプションのキーと値のペアのリストは、 AddParticipant アクションまたは Transfer アクションの一部として含まれます。コンテキストは、後で IncomingCall イベントペイロードの一部として取得されます。

カスタム呼び出しコンテキストもセッション開始プロトコル (SIP) に転送されます。これには、フリーフォームカスタムヘッダーと標準ユーザー間情報 (UUI) SIP ヘッダーの両方が含まれます。テレフォニーネットワークからの着信呼び出しがルーティングされると、カスタムヘッダーと UUI のセッションボーダーコントローラー (SBC) からのデータセットも同様に、 IncomingCall イベントペイロードに含まれます。

すべてのカスタムコンテキストデータは、コールオートメーションまたは SIP プロトコルに対して不透明であり、その内容は基本的な機能とは無関係です。

次のサンプルは、Call Automation でカスタムコンテキストヘッダーを使用して開始する方法を示しています。

Prerequisites

アクションイベントプログラミングモデルとイベントコールバックについて説明した Call Automation の概念に関する記事を参照してください。
この記事で使用するや PhoneNumberIdentifier' などのCommunicationUserIdentifierについて説明します。

すべてのコードサンプルでは、clientは作成できるCallAutomationClient オブジェクトであり、callConnectionは、CallConnectionまたはAnswer応答から取得するCreateCall オブジェクトです。アプリケーションが受け取るコールバックイベントから取得することもできます。

技術パラメーター

Call Automation では、最大 5 つのカスタム SIP ヘッダーと 1,000 個のカスタム音声オーバー IP (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);

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

通話転送中にカスタムコンテキストを追加する

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

現在、電話番号への VoIP 通話の転送はサポートされていません。

着信呼び出しイベントからカスタムコンテキストを読み取る

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

着信呼び出しのサンプルペイロードについては、「 Azure Communication Services: 音声およびビデオ通話イベント」を参照してください。
ダイレクトルーティングの SIP プロトコルの詳細について説明します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-21

通話間でコンテキスト データを渡す

Prerequisites

技術パラメーター

参加者を招待するときにカスタム コンテキストを追加する

通話転送中にカスタム コンテキストを追加する

着信呼び出しイベントからカスタム コンテキストを読み取る

関連コンテンツ

フィードバック

その他のリソース

通話間でコンテキストデータを渡す

参加者を招待するときにカスタムコンテキストを追加する

通話転送中にカスタムコンテキストを追加する

着信呼び出しイベントからカスタムコンテキストを読み取る