地址收集預先建構元件

地址收集預建元件會收集顧客的地址,並使用 Google Address Validation API 驗證地址。

限制

除了常見的預建元件限制,這個預建元件還有下列限制:

其他功能

這項預建元件提供下列額外功能:

對話範例

對話範例顯示這項預建元件處理的常見情境。當使用者透過電話呼叫元件時,系統會觸發預設歡迎意圖,並在對話開始時顯示第一個代理回覆。

完整地址驗證

使用者提供完整地址,地址收集元件會驗證地址。

使用者輸入內容 代理回覆
請先告訴我你的完整地址。
1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA
我已收集最終地址:門牌號碼是 1600,街道是 Amphitheatre Parkway,城市是 Mountain View,行政區是 CA,郵遞區號是 94043,國家/地區是 USA。對嗎?請回答「要」或「不要」。
是
太好了,我已取得地址。

部分有效地址,含有推論元素

  1. 使用者提供部分地址。
  2. 代理會猜測缺少的資訊,並在使用者確認後進行驗證。
使用者輸入內容 代理回覆
請先告訴我你的完整地址。
1600 Amphitheatre Parkway
我猜測了部分地址,城市是 Mountain View,郵遞區號是 94043,行政區是 CA,國家/地區是 USA。

我已收集最終地址,門牌號碼是 1600,路線是 Amphitheatre Parkway,城市是 Mountain View,行政區是 CA,郵遞區號是 94043,國家/地區是 USA。對嗎?請回答「要」或「不要」。
是
太好了,我已取得地址。

部分有效地址,含有使用者提供的元素

  1. 使用者提供部分地址。
  2. 使用者拒絕猜測的部分,並提供自己的輸入內容。
  3. 代理接受使用者提供的輸入內容,並再次提示確認。
  4. 使用者接受最終地址。
使用者輸入內容 代理回覆
請先告訴我你的完整地址。
1600 Amphitheatre Parkway
我猜測了部分地址,城市是 Mountain View,郵遞區號是 94043,行政區是 CA,國家/地區是 USA。

我已收集最終地址,門牌號碼是 1600,路線是 Amphitheatre Parkway,城市是 Mountain View,行政區是 CA,郵遞區號是 94043,國家/地區是 USA。對嗎?請回答「要」或「不要」。
否
好的,請告訴我需要變更地址的哪個部分。
郵遞區號
方便提供郵遞區號嗎?
94044
我已完成這項更新。還有其他要變更的地方嗎?請回答「要」或「不要」。
否
驗證後,我將郵遞區號替換為 94043。

我已收集最終地址;門牌號碼為 1600,路線為 Amphitheatre Parkway,城市為 Mountain View,行政區為 CA,郵遞區號為 94043,國家/地區為 USA。對嗎?請回答「要」或「不要」。
是
太好了,我已取得地址。

輸入內容無法辨識

使用者提供無法辨識的輸入內容三次後,元件會退出流程。

使用者輸入內容 代理回覆
請先告訴我你的完整地址。
沒關係
抱歉,我沒聽清楚。請先告訴我你的完整地址。
nice
嗯,我還是沒聽清楚。請先告訴我你的完整地址。
很棒
抱歉,我不懂你的意思。

不支援的地址

使用者提供的地址不受 Address Validation API 支援,因此元件退出流程。

使用者輸入內容 代理回覆
請先告訴我你的完整地址。
印度
很抱歉,我無法驗證該區域的地址。

地址驗證

如要進一步瞭解地址收集元件如何驗證地址,請參閱「Address Validation API 總覽」。

地址收集元件會使用 @sys.address 系統實體擷取使用者輸入內容,並將擷取的地址傳送至 Address Validation API,擷取地址元素以進一步處理。

Address Validation API 會傳回下列地址元素,可用於收集及驗證完整地址:

  • administrative_area_level_1
  • archipelago
  • country
  • locality
  • postal_code
  • route
  • street_number

您可以使用支援的地區的任何地址,試用 Google 地址驗證試用版。

命名慣例

這個預建元件採用下列命名慣例:

功能 格式 範例
Flow [Component Name] 地址收集
元件專屬意圖 prebuilt_components_[component_name]_[intent_name] prebuilt_components_address_collection_locality
參數 [param_name] user_provided_address
Webhook prebuilt_components_[component_name]:[webhook_action] prebuilt_components_address_collection:address_validation

輸入參數

輸入參數會設定元件的特定行為。流程中的一或多個條件會使用這些參數,決定元件的行為。您必須在元件的起始頁面上設定流程範圍參數。您可以使用呼叫流程,或在這個元件的開始頁面設定以工作階段為範圍的參數。

使用者可以修改流程起始頁面上的參數預設值,設定這個元件需要哪些地址元素。

這個預建元件接受下列輸入參數:

參數名稱 說明 輸入格式
$flow.zip_code 如果需要郵遞區號地址元素,請將其設為 true;否則,請將其設為 false。 布林值
$flow.city 如果城市地址元素為必填,請設為 true,否則請設為 false。 布林值
$flow.admin_area 如果行政區地址元素為必填,請設為 true,否則請設為 false。 布林值
$flow.street_number 如果需要門牌號碼地址元素,請將其設為 true;否則,請設為 false。 布林值
$flow.route 如果需要路線地址元素,請將其設為 true,否則請設為 false。 布林值
$flow.country 如果國家/地區地址元素為必填,請設為 true,否則請設為 false。 布林值
$flow.island 如果島嶼地址元素為必填,請設為 true,否則請設為 false。 布林值
$flow.retry_num 設定 Maps Address Validation API Webhook 呼叫的重試次數上限。 整數

如要設定這項元件的輸入參數,請展開查看操作說明。

  1. 開啟 Dialogflow CX 控制台。
  2. 選擇 Google Cloud 雲端專案。
  3. 選取代理。
  4. 選取「Build」(建構) 分頁標籤。
  5. 在「Flows」(流程) 部分,點選匯入的元件。
  6. 按一下「Pages」部分中的「Start Page」。
  7. 在「Start Page」中,點選「true」路徑。
  8. 在「Route」視窗中,視需要編輯「Parameter Presets」值。
  9. 按一下「儲存」。

輸出參數

輸出參數是工作階段參數,在退出元件後仍會保持有效。這些參數包含元件收集的重要資訊。

預建元件會提供下列輸出參數:

參數名稱 說明 輸出格式
address_collection_address 如果元件擷取到地址,這個參數會傳回地址物件
{
"admin-area": string,
"city": string,
"country": string,
"island": string,
"route": string,
"zip-code": string,
"street-number": string
}
address_collection_status 這個參數會傳回收集到的地址狀態。傳回的值為下列其中一項:

VALID_ADDRESS:地址已由 Address Validation API 收集並驗證。

INVALID_ADDRESS:地址已由使用者確認,但有一或多個元素未經驗證,或由 Address Validation API 標示為 UNCONFIRMED_BUT_PLAUSIBLE。

MAPS_API_ERROR:因 Address Validation API 錯誤,未收集地址。

COUNTRY_NOT_SUPPORTED:Address Validation API 不支援該區域,因此未收集地址。

NO_USER_CONFIRMATION:使用者未確認地址,因此未確認地址。
string

基本設定

如要設定這項預建元件,請按照下列步驟操作:

  1. 匯入預先建構的元件。
  2. 啟用 Address Validation API。
  3. 使用 Maps API 金鑰設定提供的彈性 Webhook。詳情請參閱「Webhook 設定」一節。

Webhook 設定

如要使用 Address Validation API 驗證地址,請使用正確的憑證設定提供的彈性 Webhook。

地址驗證 Webhook

這個 Webhook 會執行下列動作:

  1. 處理擷取的 Dialogflow CX 參數、建立要求,並使用 Address Validation API 驗證地址。
  2. 從 Address Validation API 回應中,擷取已確認、未確認、遺漏和推論的地址元素。

請使用正確的 Maps API 金鑰更新 Webhook 設定,為這個元件設定 Webhook。

如要擷取 API 金鑰,請前往 Google Cloud 控制台 > API 和服務 > 憑證,選取 Maps API 金鑰,然後複製 API 金鑰欄位。

如要設定 Webhook,請按照下列步驟操作:

  1. 前往 Dialogflow CX 控制台。
  2. 選擇 Google Cloud 專案。
  3. 選取代理程式。
  4. 選取「管理」分頁標籤。
  5. 按一下「Webhooks」。
  6. 選取 prebuilt_components_address_collection:address_validation Webhook。
  7. 將 Dialogflow CX「Webhook 網址」欄位中的網址,替換為包含 Maps API 金鑰的網址:https://addressvalidation.googleapis.com/v1:validateAddress?key=<var>MAPS_API_KEY</var>。
  8. 在「Authentication」(驗證) 設定中,將使用者名稱設為 key,並設定 Maps API 金鑰的密碼。
  9. 按一下「儲存」。

完成

預建元件和其 Webhook 已設定完成,可以開始測試。