Note
本文說明由標準執行架構驅動的 Agent 或 Agent 流程中所使用的功能。
本文說明如何為 Copilot Studio 中語音啟用 Agent 設定連入與連出通話的工作階段起始通訊協定 (SIP) X 標頭，以便在 Dynamics 365 Contact Center 中使用。
SIP X 標頭讓你能在電話系統與語音代理之間傳遞自訂的元資料。 Dynamics 365 Contact Center 語音啟用 Agent 支援輸入及輸出 X 標頭。 此配置允許通話轉接與路由時無縫傳輸資料。
Prerequisites
Dynamics 365 Contact Center，其中已啟用語音啟用 Agent
包含適當權限的 Copilot Studio 存取權
電信配置中的直接路由
Important
SIP X 標頭的名稱與值必須只包含支援的字元。 進一步了解在通話之間傳遞情境資料中支援的字元。
設定輸入 X 標頭
輸入 X 標頭包含從外部電話語音系統傳遞至語音啟用 Agent 的中繼資料。 要接收並使用這些資料，你必須設定一個 解析值 節點，從系統變數中擷取 X 標頭資訊 Conversation.SipXHeader 。
輸入 X 標頭需求
最大數量：每通來電最多可有五個 X 標頭。
命名要求：所有 X 標頭名稱必須以
x-開頭。Note
在 Copilot Studio 中，所有收到的 X 標頭必須以小寫
x-開頭，即使外部系統發送 X 標頭的是大寫X-。 Copilot Studio 中定義的輸出 X 標頭可以是小寫或大寫，這取決於外部系統對大小寫的要求。名稱長度：最多64字元。
數值長度：最多 256 個字元。
所有預期的 X 標頭都需要 JSON 架構。
當 X 標頭名稱變更時，更新 JSON 架構。
通道資料依賴性：X 標頭必須存在於
Conversation.SipXHeader。
新增變數管理 - 解析值節點
瀏覽至語音啟用 Agent 的主題。
新增一個主題節點。
選擇 變數管理 並選擇 解析值。
配置解析值節點
從 系統 選單中，將 解析值 欄位設為
Conversation.SipXHeader。將 資料型別 設為 來自樣本資料。
透過選擇 「從範例 JSON 取得結構」來定義預期的 X 標頭結構。
定義 X 標頭的 JSON 架構
在「 從範例 JSON 取得結構 」對話框中，提供包含你預期收到的 X 標頭名稱的 JSON 結構。 例如，如果你預期來電中有如 X-CallID 和 X-AAI-Incoming 這樣的標頭，就將它們加入你的 JSON 架構中。
選擇 確認 以套用該結構。
Important
無論外部系統如何傳送，Dynamics 365 Contact Center 平台一律將 X 標頭名稱標準化為使用小寫 x- 前置詞。 這意味著：
如果外部系統傳送
X-CallID，你必須在你的結構中將它定義為x-CallID。如果外部系統傳送
X-AAI-Incoming，你必須在你的結構中將它定義為x-AAI-Incoming。
即使外部系統使用大寫 X-，你的結構必須始終使用小寫 x- ，讓平台能正確對應並處理標頭。
X標頭的範例 JSON
{
"x-CallID": "",
"x-AAI-Incoming": ""
}
儲存解析後的資料
在 「另存為」 欄位中建立或選擇變數（例如，
IncomingSipXHeader）。
將變數的範圍設為 全域 變數，以便能在您的智能助理中跨多個主題存取。
存取主題中的 X 標頭值
設定完成後，您可以使用點符號來存取個別的 X 標頭值，類似以下範例：
Global.IncomingSipXHeader.'x-AAI-Incoming'IncomingSIPXHeaders.sipXHeader.'X-CallID'
執行時行為
Copilot Studio 只會接收外部系統寄出的前五個 X 標頭。
當名稱與結構相符時，Copilot Studio 會自動填充 X 標頭值。
缺少的 X 標頭具有空字串值。
當 X 標頭名稱變更或你想接收額外標頭時，必須進行結構更新。
設定輸出 X 標頭
您可以使用輸出 X 標頭在通話轉接至外部電話號碼時傳遞自訂資料。 在 傳輸對話 節點中設定這些標頭。
輸出 X 標頭需求
最大數量：每次傳輸可有五個 X 標頭。
命名要求：所有 X 標頭名稱可以
X-或x-開頭，視外部系統預期的情況而定。Note
在 Copilot Studio 中，所有收到的 X 標頭必須以小寫
x-開頭，即使外部系統發送 X 標頭的是大寫X-。 Copilot Studio 中定義的輸出 X 標頭可以是小寫或大寫，這取決於外部系統對大小寫的要求。名稱長度：最多64字元。
數值長度：最多 256 個字元。
轉移類型：僅可用於 外部電話號碼轉移。
設定傳輸對話節點
在你的主題流程中新增一個 轉移對話 節點。
在轉接類型底下，選取外部電話號碼轉接並輸入轉接號碼。 例如，+18005551212。
在傳輸會話節點屬性中設定 X 標頭
選取節點的更多圖示 (...)，然後選取屬性。
選擇 + Add 以新增 X 標頭鍵值對。
定義 X 標頭的項目。 外發送的 X 標頭名稱會按照你在 傳輸對話 節點中定義的方式傳送。 根據接收系統的預期選擇合適的案例。
-
關鍵字名稱：必須以
X-或x-開頭（例如，X-AAI-Outgoing或X-CallID） - 值：輸入靜態值或指派變數
-
關鍵字名稱：必須以
最佳做法
在使用語音代理程式中使用 SIP X 標頭時，請遵循以下指引，涵蓋架構設計、變數管理、錯誤處理及效能。
架構設計
使用明確指出其用途的描述性 X 標頭名稱。
當 X 標頭需求改變時，保持 JSON 架構更新。
請記錄你的 X 標頭架構文件，以便團隊參考和除錯。
變數管理
使用全域變數來處理需要跨主題存取的 X 標頭資料。
選擇有意義的變數名稱（例如，
IncomingSIPXHeaders或CustomerXHeaders）。在對話流程的早期就初始化變數。
錯誤處理
在邏輯中使用數值前，務必檢查 X 標頭的存在。
對於缺少或無效的 X 標頭資料，實作備援行為。
全面測試各種 X 標頭案例。
效能考量
在交談流程早期剖析 X 標頭。
視需要在不同的變數中快取經常使用的值。
避免重複解析同一通道資料。
輸入 X 標頭的常見問題
如果收到的 X 標頭無法如預期運作，請檢視這些常見問題及故障排除步驟。
未收到 X 標頭值
確認 JSON 結構是否完全符合預期的 X 標頭名稱。
檢查解析 值 節點是否設定為
Conversation.SipXHeader。如果你從多個主題存取變數，請確保該變數設為全域範圍。
確保預期接收的 X 標頭不超過五個，且這些 X 標頭是外部系統傳送的前五個 X 標頭。
空或為空值的 X 標頭值
確認外部系統正在傳送包含預期名稱的 X 標頭。
確認 JSON 架構包含所有必要的 X 標頭名稱，且帶有小寫
x-前綴。
輸出 X 標頭的常見問題
如果輸出 X 標頭無法依預期正常運作，請檢閱這些常見問題和疑難排解步驟。
傳輸過程中未傳送的 X 標頭
確認所有 X 標頭名稱皆以
X-或x-開頭。請確保 轉移類型 設為 外部電話號碼轉移。
確保在 傳輸對話 節點前正確分配 X 標頭值。
使用 X 標頭的傳輸失敗
確認 X 標頭名稱和值沒有超過長度限制。
確認接收系統能處理所傳送的 X 標頭。
檢查是否有特殊字元可能導致解析問題。
綱要管理
隨著需求變化，保持你的 X 標頭架構有條理且最新。
更新 X 標頭架構
在 「定義 X 標頭的 JSON 架構 」中更新 JSON 範例，以便接收新的 X 標頭。
確認並儲存更新後的架構。
使用新的 X 標頭配置測試結構模式。