零售驗證預先建構元件

零售驗證預先建構元件會收集使用者資訊，以便驗證他們是否符合所需的驗證層級。本元件涵蓋零售業常見的驗證規定，但不限於零售業。這個元件會使用電話號碼收集預先建構的元件，收集並驗證使用者詳細資料。

驗證層級

不同的預先建構元件需要多種驗證層級，較高層級需要更多使用者資訊才能驗證使用者。零售驗證元件可讓使用者進行第 0 級 (ANI 比對) 或第 1 級 (基本) 驗證，如「驗證層級」表格所述。

驗證等級	需求條件
等級 0：ANI 比對	使用者可以透過撥打電話或提供與註冊帳戶相對應的電話號碼來驗證。 使用者可以使用預先建構的問候語元件，將驗證層級提升至 Level 0。
第 1 級：基本	使用者透過驗證傳送至電子郵件或電話號碼的一次性密碼 (OTP) 碼來驗證身分。

支援的使用者類型

零售驗證元件可支援已註冊電話號碼和電子郵件的使用者。

限制

除了常見的預先建構元件限制外，這個預先建構元件還有以下限制：

• 動態密碼只會傳送至使用者先前註冊的手機號碼或電子郵件地址。元件不會使用 OTP 驗證使用未註冊於帳戶的其他電話號碼撥打電話的客戶。使用者使用其他電話號碼撥打電話時，系統會使用安全性問題驗證來電者。
• 這個元件不會加密任何資料。

對話方塊範例

以下對話方塊範例說明這個預先建構元件處理的常見情境。以下對話方塊範例說明使用電話服務呼叫元件時的行為，這會在對話開始時觸發「Default Welcome」意圖，並由服務專員提供第一個回應。

0 級驗證成功：ANI 相符

使用者透過已註冊至現有帳戶的電話號碼撥打電話，確認帳戶，並成功通過 Level 0 驗證。

使用者輸入內容	服務專員回應
	你好，你撥打的號碼已連結至 John 的帳戶。你是否想詢問他人的訂單？如果是這樣，請說「是」，否則請說「否」。
否
	謝謝你，John。系統已成功辨識您的身分。

第 1 級驗證成功：動態密碼

使用者透過無法識別的電話號碼撥打電話。元件會收集使用者註冊的電話號碼，然後傳送動態密碼並要求使用者確認傳送至使用者所選管道的動態密碼。使用者可以提供有效的 OTP，並成功通過第 1 級驗證。

使用者輸入內容	服務專員回應
我們找不到與這組電話號碼相關聯的帳戶。請提供註冊的電話號碼。
	服務專員使用電話號碼收集預先建構的元件收集電話號碼
	很好，我們已收集電話號碼。 為了安全起見，我們需要驗證您的身分，因此會傳送一組代碼給您。你想透過電話還是電子郵件接收驗證碼？
手機
	確認一下，你想在手機上收到動態密碼嗎？請說「是」或「否」。
是
	我們已將驗證碼傳送到末四碼為 0000 的註冊電話號碼。這項作業可能需要幾秒鐘的時間。請確認代碼。
123457
	謝謝你，John。系統已成功辨識您的身分。

命名慣例

這個預先建構的元件採用下列命名慣例：

功能	格式	範例
心流狀態	[元件名稱]	零售驗證
元件專屬意圖	prebuilt_components_[component_name]_[intent_name]	prebuilt_components_retail_authentication_incorrect_phone_number
實體類型	prebuilt_components_[component_name]_[entity_type]	prebuilt_components_channel_email_phone
Webhook	prebuilt_components_[component_name]:[webhook_action]	prebuilt_components_retail_authentication:verify_user_details

輸入參數

輸入參數是用來設定元件特定行為的參數。參數會由工作流程中的一或多個條件使用，用於決定元件的行為方式。流程範圍參數必須在元件的起始頁面中設定，如下所述。您可以透過呼叫流程或此元件的起始頁面，設定會話範圍參數。

這個預先建構的元件可接受下列輸入參數：

參數名稱	說明	輸入格式
$session.params.auth_level_req	定義要對使用者進行驗證的驗證層級。有效值為 0 或 1。	整數
$session.params.auth_level	(選用) 表示使用者的目前驗證層級。	整數
$session.params.phone_number	(選用) 使用者的電話號碼。如果未提供這項參數，元件會向使用者收集電話號碼。	字串
$flow.max_retry_phone_number	指定收集使用者電話號碼時允許的重試次數。預設值為 3。	整數
$flow.max_retry_otp	指定收集動態密碼 (OTP) 時允許的重試次數。預設值為 3。	整數
$flow.max_retry_otp_not_received	指定未收到動態密碼 (OTP) 時，允許的重試次數。預設值為 1。	整數
$flow.max_retry_otp_confirm_channel	指定收集接收動態密碼 (OTP) 管道的重試次數。預設值為 3。	整數

輸出參數

輸出參數是會在退出元件後仍保持啟用的會話參數。這些參數包含元件收集的重要資訊。這個預先建構的元件會為下列輸出參數提供值：

參數名稱	說明	輸出格式
auth_level	表示使用者目前的驗證層級。	整數
all_recent_order_id	這個參數會列出與已驗證使用者相關聯的訂單 ID，並依訂單下單日期由高至低排序。陣列的第一個元素代表最近的訂單。如果使用者沒有訂單，這個參數的值會是 null。	清單 (字串)
phone_number	使用者的當地電話號碼 (不含國家/地區代碼)，用於識別使用者。	字串
電子郵件	帳戶註冊的電子郵件地址。	字串
user_first_name	使用者的名字，用於向使用者問候及確認帳戶擁有權。	字串
transfer_reason	如果流程未成功執行，這個參數會指出流程結束的原因。回傳的值為下列其中一個： agent：使用者在對話過程中某個時間點要求真人服務專員。 denial_of_information：使用者拒絕分享元件要求的資訊。 max_no_input：對話已達到無輸入事件的最大重試次數。請參閱無輸入內建事件。 max_no_match：對話已達到不相符事件的重試次數上限。請參閱不相符的內建事件。 webhook_error：發生 webhook 錯誤。請參閱「webhook.error 內建事件」。 webhook_not_found：無法連上 webhook 網址。請參閱 webhook.error.not-found 內建事件。	字串

基本設定

如要設定這個預先建構的元件，請按照下列步驟操作：

1. 匯入預先建構的元件。
2. 使用描述外部服務的設定，設定提供的彈性 webhook，請參閱下方的 webhook 設定。

設定 Webhook

如要使用這個元件，您必須設定隨附的彈性 webhook，才能從外部服務擷取所需資訊。

驗證使用者詳細資料

元件會使用 prebuilt_components_retail_authentication:verify_user_details webhook，根據提供的電話號碼擷取使用者帳戶詳細資料。

API 要求參數

元件會將下列參數提供為 API 要求的輸入內容。

參數名稱	說明	輸入格式
$session.params.phone_number	使用者的當地電話號碼 (不含國家/地區代碼)，用於識別使用者。	字串

API 回應參數

下列參數會從 API 回應中擷取，供元件使用。

參數名稱	說明	輸出格式
電子郵件	帳戶註冊的電子郵件地址。	字串
all_recent_order_id	與已驗證使用者相關聯的訂單 ID 清單，以訂單下單日期由新到舊的順序排序。陣列的第一個元素代表最近的訂單。如果使用者沒有訂單，這個參數的值會是 null。	清單 (字串)
user_first_name	使用者的名字，用於向使用者問候及確認帳戶擁有權。	字串

傳送動態密碼

元件會使用 prebuilt_components_retail_authentication:send_otp webhook，將動態密碼 (OTP) 傳送至使用者所選的已註冊管道。

API 要求參數

元件會將下列參數提供為 API 要求的輸入內容。

參數名稱	說明	輸入格式
$session.params.phone_number	使用者的當地電話號碼 (不含國家/地區代碼)，用於識別使用者。	字串
$flow.channel	使用者選取的接收 OTP 的管道。有效值由 prebuilt_components_channel_email_phone 自訂實體定義。預設支援 email 和 phone。	字串

API 回應參數

下列參數會從 API 回應中擷取，供元件使用。

參數名稱	說明	輸出格式
generated_otp	使用所選管道產生並傳送給使用者的 OTP 值。	字串

完成

代理程式和相關的 webhook 應已設定完成，可以開始測試。