使用 ACS 通話 SDK 在通話之間傳遞內容相關的使用者對使用者資訊 (UUI) 資料
在本文中，您會了解如何在使用 Azure 通訊服務通話 SDK 路由通話時，傳遞自訂內容相關的資訊。 這項功能可讓使用者傳遞有關通話、被通話者，或任何其他與其應用程式或商務邏輯相關資訊的中繼資料。
Azure 通訊服務 (ACS) WebJS SDK 可讓開發人員在將通話從一個人員導向及路由傳送通話至另一個人員時，包含自訂內容相關的資料 (包含做為通話物件上的標頭)。 這項資訊 (又稱為「使用者對使用者資訊」(UUI) 資料或通話控制 UUI 資料) 是由起始通話的應用程式所插入的一小部分資料。 UUI 資料對於撥打通話的使用者並不透明。
支援的內容資訊包括手繪多邊形自訂標頭和標準使用者對使用者資訊 (UUI) SIP 標頭。 此外，當您收到輸入通話時，自訂標頭和 UUI 會包含在 incomingCall 承載中。
所有自訂內容資料對於通話 SDK 或 SIP 通訊協定皆不透明，且其內容與任何基本函式無關。
開發人員可以使用自訂標頭傳遞此內容，其中包含選擇性索引鍵/值組。 這些組可以包含在通話 SDK 內的 'AddParticipant' 或 'Transfer' 動作中。 新增之後，您即可在通話於端點之間移動時讀取資料承載。 開發人員可以有效率地查閱此中繼資料並將其與通話產生關聯，以避免外部資料庫查閱，並在通話對象內隨時提供內容資訊。
您可以使用 SIP 通訊協定將自訂通話內容傳輸至 SIP 端點。 此傳輸包含自訂標頭和標準使用者對使用者資訊 (UUI) SIP 標頭。 從您的電話語音網路路由輸入通話時，自訂標頭中工作階段邊界控制器 (SBC) 的資料和 UUI 也會包含在 IncomingCall 事件裝載中。
請務必注意，所有自訂內容資料對於通話 SDK 皆保持透明，且在 SIP 通訊協定中使用時，與任何 SDK 的基本函式皆無關。 以下教學課程可協助您在使用 WebJS SDK 時新增自訂內容標頭。
重要
若要能夠使用通話 SDK 傳遞使用者對使用者資訊 (UUI) 資料，您必須使用通話 WebJS SDK GA 或公開預覽版本 1.29.1 或更新版本。
技術參數
通話 SDK 支援新增最多 5 個自訂 SIP 標頭和 1000 個自訂 VOIP 標頭。 此外，開發人員可以在 SIP 標頭清單包含專用的使用者對使用者標頭。
SIP 標頭索引鍵的最大長度為 64 個字元，包括 X-MS-Custom 前置詞。 請注意，新增 SIP 標頭時，通話 SDK 會自動新增 ‘X-MS-Custom-’ 前置詞 (如果您使用封包檢查器檢查 SIP 標頭就會看到)。
SIP 標頭索引鍵可包含英數字元和一些選取的符號，包括 .、!、%、*、_、+、~、-。 SIP 標頭值的最大長度為 256 個字元。 在 SBC 設定 SIP 標頭時適用相同的限制。 SIP 標頭值可包含英數字元和一些選取的符號，包括 =、;、.、!、%、*、_、+、~、-。
VOIP 標頭索引鍵的最大長度為 64 個字元。 VOIP 標頭值的最大長度為 1024 個字元。
以開發人員身分新增這些自訂標頭時，您可以選擇僅新增 SIP 標頭、僅新增 VoIP 標頭，或兩者皆可包含在內。
注意
目前，僅在起始一對一通話時，才支援新增自訂使用者對使用者資訊標頭。 目前不支援在群組通話中傳遞使用者對使用者資訊標頭。 若要在開始一對一通話之後解決此問題，您可以在包含其他參與者之際，同時在通話中維護使用者對使用者資訊。
如需自訂內容介面 API 的詳細資訊，請參閱自訂內容 API 資源頁面。
利用使用者對使用者資訊 (UUI) 資料撥打通話
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
在通話中讀取及剖析使用者對使用者資訊標頭
當登入的身分識別接聽來電時，callAgent 執行個體會發出 incomingCall 事件。 若要接聽此事件並擷取內容相關的資訊，請使用下列其中一個選項進行訂閱：
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});