參數

定義、參照、設定及取得參數

參數的使用方式主要有四種：

• 在設計階段定義：在設計階段，您可以使用主控台或 API 定義參數。舉例來說，您可以定義意圖參數，並在訓練詞組中使用該參數，指出應擷取的使用者輸入內容。
• 設計階段參照：參數參照是存放執行階段要擷取的參數值的變數。在設計階段，您可以使用控制台或 API 參照各種資料類型的參數。例如，您可以在路由的靜態執行回應中參照工作階段參數。
• 在執行階段設定：在執行階段，Conversational Agents (Dialogflow CX) 服務、呼叫 API 的服務，以及 webhook 服務都可以設定參數值。舉例來說，當使用者輸入內容與意圖相符，且輸入內容包含參數資料時，Conversational Agents (Dialogflow CX) 服務就會設定意圖參數的值。
• 在執行階段取得：在執行階段，參數參照會包含已設定的參數值，您可以使用 API 或 webhook 取得參數值。舉例來說，如果系統比對到意圖並呼叫 webhook，webhook 服務就會收到意圖的參數值。

參數命名

下列規則適用於參數命名：

• 使用下列字元：[A-Z]、[a-z]、[0-9]、.、-、_
• 參數名稱不區分大小寫，因此 Conversational Agents (Dialogflow CX) 會將 Apple 和 apple 視為相同的參數。Webhook 和 API 用戶端程式碼也應將參數名稱視為不區分大小寫，因為 Conversational Agents (Dialogflow CX) 傳回的參數名稱不保證大小寫。
• 在不同意圖或表單中建立具有相同 ID 或顯示名稱的參數時，請確認所有定義的實體類型和其他設定都相同。如果實體類型或其他參數設定不同，請為每個定義使用不重複的參數 ID 或顯示名稱。

參數值類型

參數值支援多種值類型。請參閱下方的「工作階段」章節，瞭解如何參照每個參數值類型。mapTypeId 支援的類型如下：

參數空字串和空值

您可以將字串參數值設為 ""，這樣就能將參數設為空字串。

您可以將任何參數值設為 null，表示尚未設定參數。

參數原始值

當系統在執行階段將文字比對至特定實體時，通常會將其解析為更易於處理的值。舉例來說，針對水果實體，系統可能會將使用者輸入內容中的「apples」(蘋果) 這個字解析為「apple」。

意圖參數參照的所有值類型都可以參照原始值或解析值。

只有工作階段參數參照的複合值類型才能參照原始值。

意圖參數

意圖會在意圖比對時使用參數來擷取使用者提供的資料。下列資料可用於定義意圖參數：

• 名稱 (也稱為「ID」或「顯示名稱」)：可用於識別參數的名稱。
• 實體類型：與參數相關聯的實體類型。
• Is List：如果為 true，系統會將參數視為值清單。
• 在記錄中遮蓋：如果為 true，使用者提供的參數資料會遮蓋。

定義意圖參數

意圖參數是在設計階段定義，也就是在建立意圖資料或加註訓練詞組時。

參照意圖參數

意圖參數參照可用於意圖路徑的靜態執行要求回應訊息。

您可以參照原始值或解析值。

如要參照目前已比對意圖的參數，請使用下列其中一種格式：

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

舉例來說，如果參數 ID 為 date，您可以使用 $intent.params.date.resolved 來參照已解析的值。

設定意圖參數

當使用者輸入內容在執行階段與意圖相符時，Conversational Agents (Dialogflow CX) 會設定註解用於相關訓練詞組的任何參數。

意圖路徑的執行要求可使用執行要求參數預設值，在執行階段設定意圖參數值。

取得意圖參數

在意圖比對的對話輪次中，程式碼可以存取意圖參數值。

與 API 互動時，系統會傳回意圖參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。前往「Session API」(時段 API) 參考資料

Webhook 會接收意圖參數值。請參閱 Webhook 要求中的 intentInfo.parameters 欄位。

表單參數

您可以為每個網頁定義表單，也就是從網頁的使用者收集的參數清單。代理程式會與使用者進行多次對話，直到收集到所有必要的表單參數 (也稱為頁面參數) 為止。代理程式會按照頁面上定義的順序收集這些參數。針對每個必要表單參數，您也必須提供提示，讓代理程式用於向使用者索取該資訊。這個過程稱為「表單填充」。

舉例來說，您可以建立表單，收集 Collect Customer Info 頁面上終端使用者的姓名和電話號碼。

以下資料用於定義表單參數：

定義及管理表單參數

建立頁面時，表單參數會在設計階段定義。

如要使用主控台變更表單參數順序，請按一下頁面上的「Parameters」區段標題，然後拖曳參數表中的參數列。

如要刪除表單參數，請按一下頁面上的「參數」部分標題，將滑鼠游標懸停在參數上，然後按一下刪除 delete 按鈕。

參照表單參數

表單參數參照不會直接使用。您只能檢查個別表單參數或整份表單的填寫狀態。您可以在條件路徑的條件規定中使用這些表單狀態參照。

如要檢查目前網頁是否已填妥表單，請使用下列條件：

$page.params.status = "FINAL"

如要檢查特定表單參數是否在最後一輪填入，請使用下列條件：

$page.params.parameter-id.status = "UPDATED"

設定表單參數

表單參數值可透過多種方式設定。下列子節將說明設定表單參數值的各項機制。

預設參數值

您可以為選用表單參數提供預設值。表單填寫作業開始時，所有未設定的選用表單參數都會設為預設值。這些值可透過下列部分機制進行初始化或覆寫。

如果參數為必填，系統會忽略其預設值。

填寫表單

Conversational Agents (Dialogflow CX) 會自動設定使用者在填寫表單時提供的參數值。服務專員會按照頁面上定義的順序收集必要參數。代理程式會使用您為每個必要參數提供的初始提示回應，向使用者提示必要值。選用參數不會觸發提示。

如果使用者在服務機器人提示後未提供必要的參數值，系統會重複初始提示，除非在重複提示處理常式中定義不同的行為。如果定義了多個初始文字提示，代理程式行為會與任何執行文字回應的行為相同。

意圖和工作階段參數傳播

在執行階段設定任何類型的參數時，系統會將參數寫入工作階段，並成為工作階段參數。

當網頁一開始啟用，以及在啟用期間，任何與工作階段參數同名的表單參數都會自動設為工作階段參數值。

這可能發生在意圖路徑或參數傳播中，與意圖參數相符的情況。

意圖和工作階段參數傳播是唯一可將選用表單參數設為使用者輸入值的機制，但這項機制也可以設定或覆寫必要表單參數值。

履行參數預設值

路由、事件處理常式或表單重複提示的執行階段可使用預設的執行階段參數，在執行階段設定表單參數值。執行參數預設值會覆寫參數值，包括參數預設值。

Webhook 參數設定

您的 webhook 可以在執行階段設定表單參數的值。請參閱 Webhook 回應中的 pageInfo.formInfo.parameterInfo 欄位。

取得表單參數

與 API 互動時，系統會傳回表單參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。前往「Session API」(時段 API) 參考資料

Webhook 接收表單參數值。請參閱 Webhook 要求中的 pageInfo.formInfo.parameterInfo 欄位。

表單填寫重複提示處理常式

重複提示處理常式 (也稱為參數層級事件處理常式) 可用於為必要參數定義複雜的參數提示行為。舉例來說，如果使用者在初始提示後未提供值，可使用重新提示處理程序變更提示，並在嘗試 N 次後轉換至其他頁面。

如果未定義重新提示處理常式，系統會視需要使用初始提示重新提示使用者。

如果使用者回應的輸入內容不符合預期，系統會叫用 sys.no-match-* 或 sys.no-input-* 事件，並呼叫為這些事件定義的任何重複提示處理常式。

與其他事件處理常式一樣，重複提示處理常式是一種狀態處理常式，可透過下列一或兩種方式進行設定：

• 提供使用者重複提示訊息和/或參數預設值的執行項目。
• 變更目前網頁的轉場目標。

工作階段參數

在執行階段設定任何類型的參數時，系統會將參數寫入工作階段，並成為工作階段參數。這些參數並未在設計階段明確定義。您可以在工作階段的任何時間參照這些工作階段參數。

參考工作階段參數

您可以在下列類型的執行要求中，使用工作階段參數參照的靜態回應訊息：

• 網頁輸入完成
• 路線運送
• 事件處理常式執行要求
• 表單提示回應
• 表單重複提示執行

參照資料也可以用於下列情況：

• Webhook 標頭值，用於驗證。
• 彈性 Webhook 要求，用於將參數值傳送至 Webhook。

如要參照工作階段參數，請使用下列格式：

$session.params.parameter-id

設定工作階段參數

填寫表單完成後，Conversational Agents (Dialogflow CX) 會將填入的參數寫入工作階段。

路由、事件處理常式或表單重複提示的執行階段可使用預設的執行階段參數，在執行階段設定會話參數值。

您的 webhook 可以在執行階段設定工作階段參數的值。請參閱標準 Webhook 回應中的 sessionInfo.parameters 欄位，或參閱彈性 Webhook 回應。

與 API 互動時，可以設定工作階段參數值。請參閱 detectIntent 方法的 queryParams.parameters 要求欄位，瞭解 Session 類型。前往「Session API」(時段 API) 參考資料

取得工作階段參數

與 API 互動時，系統會傳回工作階段參數值。請參閱 detectIntent 方法的 queryResult.parameters 回應欄位，瞭解 Session 類型。前往「Session API」(時段 API) 參考資料

Webhook 接收會話參數值。請參閱 Webhook 要求中的 sessionInfo.parameters 欄位。

參數傳播

當使用者輸入提供參數值時，參數可能會傳播至其他層級：

• 當意圖比對設定意圖參數時，有效網頁的類似名稱表單參數會設為相同值。參數的實體類型由意圖參數定義決定。
• 如果意圖比對會設定意圖參數，或是在填寫表單時設定表單參數，則參數會變成工作階段參數。

電話整合的多頻撥號

您可以為參數啟用及設定 DTMF (雙音多頻信號)。啟用後，使用電話整合的代理程式使用者就能使用電話鍵盤提供參數值。

為減少模糊性，DTMF 輸入內容可透過一般和 DTMF 專屬 (建議) 形式解讀：

• 一般來說，這類表單只會顯示使用者輸入的按鍵值。例如 123#。
• DTMF 專用表單會將輸入內容轉換為 dtmf_digits_[digits]，其中 [digits] 是原始 DTMF 數字，* 已替換為 star，# 已替換為 pound。舉例來說，123# 會解讀為 dtmf_digits_123pound。

比對參數的實體類型時，Conversational Agents (Dialogflow CX) 會嘗試比對一般和 DTMF 專屬的表單。當實體類型用於 DTMF 輸入時，建議您定義 dtmf_digits_123 等同義字，以改善 NLU 比對。

如果 DTMF 輸入內容不符合結束條件 (未達位數上限或未以結束位數結束)，Conversational Agents (Dialogflow CX) 代理程式會繼續等待更多輸入內容。在此期間，如果觸發無語音逾時，代理程式會改為叫用無輸入事件。如果只偵測到語音內容，代理程式會比對語音輸入內容。如果系統同時偵測到語音和 DTMF 輸入內容，系統會捨棄語音輸入內容，只考量 DTMF 輸入內容。

如要啟用並自訂參數的 DTMF，請按照下列步驟操作：

建構代理程式時，您可以在模擬工具中測試 DTMF 輸入內容。

智慧端點

如果為機器人啟用智慧端點設定，您可以為數值參數自訂智慧端點設定行為。

1. 設定「Minimum digits」，提示智慧端點偵測器等到所有位數都收集完畢。
2. 設定「修正轉錄稿」，修正常見的數字轉錄錯誤，以改善數字語音辨識功能。這項功能僅支援指定 en 或 en-* 語言代碼的要求。
3. 設定「等待逾時時間」，指定 Conversational Agents (Dialogflow CX) 等待使用者提供更多輸入內容的額外時間。

流程範圍參數

流程範圍參數可定義為訂單履行參數預設值或表單參數。這些參數只能在定義它們的流程處於活動狀態時參照，且不會保留至工作階段參數。

如要定義或參照流程範圍參數，請使用下列語法：

$flow.parameter-name

舉例來說，如果參數名稱為 date，您可以將參數定義或參照為 $flow.date。

請注意，在定義參數時使用 $ 前置字串，與不使用 $ 定義參數的其他參數類型不同。

範例：流程範圍參數定義：

流程範圍參數值的生命週期

雖然不常發生，但在某些進階情況下，您可能需要瞭解在流程失效後再重新啟用時，流程範圍參數值會如何保留 (或捨棄)。

當資料流變為非活動狀態，然後又重新啟用時，資料流範圍參數值是否會保留，取決於資料流堆疊和堆疊上的資料流例項。

• 當流程 A 使用特定轉換目標轉換為流程 B 時，流程 A (父項流程) 會保留在堆疊中，流程 A 會保留其流程範圍參數值，並將流程 B 的新執行個體 (子項流程) 新增至堆疊。
• 當子資料流使用符號轉場目標 (例如 END_FLOW) 轉回父項資料流時，子資料流會從堆疊中移除，所有子資料流層級參數值會遭到捨棄，而所有父項資料流層級參數值則會保留。
• 使用一系列具有特定轉場目標的轉場，流程堆疊可包含單一流程類型的多個執行個體。每個執行個體的流程類型都會具有專屬的流程範圍參數值。例如：A1 -> B1 -> C1 -> B2，其中 A、B 和 C 是流量類型，而數字則代表這些流量類型的例項。在這個範例中，B1 和 B2 是流程 B 的不同例項，且具有不同的流程範圍參數。

範例：

要求範圍參數

要求範圍參數是對話方塊服務 (Dialogflow CX) 建立的短效參數，只能在目前要求的生命週期中參照，不會保留在會話參數中。

針對下列功能，Conversational Agents (Dialogflow CX) 會產生要求範圍參數。

內建參數

您可以使用下列方法存取與要求相關的各種資料：

自訂酬載

設定 QueryParameters.payload 後，您可以透過 $request.payload.param-id 存取對應的參數。

情緒分析

啟用情緒分析後，您可以使用下列情緒參考資料：

參數遮蓋

您可以為任何意圖或表單參數啟用參數遮蓋功能，這項功能會從記錄和 Conversational Agents (Dialogflow CX) 內部儲存空間中遮蓋使用者執行階段參數資料。已遮蓋的參數會在記錄中顯示為 $parameter-name_redacted。

舉例來說，假設使用者輸入「我的地址是 1600 Amphitheatre Parkway」，系統就會將地址參數傳送至「1600 Amphitheatre Parkway」。記錄的文字會是「My address is $address_redacted」。

如要啟用參數遮蓋功能，請按照下列步驟操作：

或者，您也可以遮蓋特定實體類型的所有參數。