本節說明當 Actions on Google 透過 Dialogflow v2 叫用您的執行項目時，JSON 酬載的格式。
如果您使用 Dialogflow 建立動作，您的執行要求會透過其標準的 Webhook 格式 (而非 Actions on Google 對話 Webhook 格式) 與 Dialogflow 相互通訊。Dialogflow Webhook 格式包含對話 Webhook 格式的所有資訊，以及其他情境的 Dialogflow 專屬資料，例如背景資訊和參數的相關資訊。
如要查看 Dialogflow Webhook 的 JSON 訊息範例，您可以參考這個 GitHub 專案。
要求主體
Dialogflow 的 request 訊息包含 Dialogflow Webhook 格式的資料。這個物件包含 Actions on Google 專屬資訊，摘要如下：
originalDetectIntentRequest.source值為「google」。originalDetectIntentRequest.version表示要求的 Actions on Google 版本。originalDetectIntentRequest.payload包含 Actions on Google 特定資訊的關鍵資訊，包括來自 Google 助理的對話要求 JSON。- Dialogflow Webhook 要求不支援
Conversation.conversationToken欄位。因此，您的履行要求可以使用 Dialogflow 結構定義，在對話的生命週期內保存資料。
簡易叫用要求範例
下列程式碼片段顯示 Dialogflow Webhook 格式的叫用要求範例。
{
"responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
"queryResult": {
"queryText": "GOOGLE_ASSISTANT_WELCOME",
"action": "input.welcome",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
"displayName": "Default Welcome Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "Talk to my test app",
"inputType": "VOICE"
}
],
"intent": "actions.intent.MAIN"
}
],
"user": {
"lastSeen": "2018-03-16T22:08:48Z",
"permissions": [
"UPDATE"
],
"locale": "en-US",
"userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
},
"conversation": {
"conversationId": "${SESSIONID}",
"type": "NEW"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
簡易對話要求範例
下列程式碼片段顯示 Dialogflow Webhook 格式的對話要求範例，其中使用者輸入內容為文字字串。
{
"responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
"queryResult": {
"queryText": "query from the user",
"action": "action.name.of.matched.dialogflow.intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
"displayName": "Name of Dialogflow Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "query from the user",
"inputType": "KEYBOARD"
}
],
"arguments": [
{
"rawText": "query from the user",
"textValue": "query from the user",
"name": "text"
}
],
"intent": "actions.intent.TEXT"
}
],
"user": {
"lastSeen": "2017-10-06T01:06:56Z",
"locale": "en-US",
"userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
},
"conversation": {
"conversationId": "1522951193000",
"type": "ACTIVE",
"conversationToken": "[]"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
小幫手結果範例
下列程式碼片段顯示採用 Dialogflow Webhook 格式的輔助結果範例。本範例顯示 Webhook 向 Google 助理指出使用者需要取得使用者確認後的回應。
{
"responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
"queryResult": {
"queryText": "actions_intent_CONFIRMATION",
"action": "Dialogflow action name of matched intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
"parameters": {
"CONFIRMATION": true
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow action name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {},
"inputs": [
{
"rawInputs": [
{
"query": "yes",
"inputType": "VOICE"
}
],
"arguments": [
{
"name": "CONFIRMATION",
"boolValue": true
}
],
"intent": "actions.intent.CONFIRMATION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
回應主體
從出貨端點到 Google 助理的 HTTP 訊息標頭中的 Content-Type 必須為 application/json。
您的出貨要求傳送給 Dialogflow 的回應訊息必須使用 Dialogflow Webhook 格式。
與 Google 助理通訊時，回應通常會包含封裝「google」物件的 payload 物件。「google」酬載物件包含 Actions on Google 特定資訊。這個檔案至少要包含一個 expectUserResponse 欄位以及 richResponse 或 systemIntent 欄位。
「google」酬載物件的主要欄位摘要如下：
| 欄位 | 說明 |
|---|---|
expectUserResponse |
指出出貨資訊是否需要使用者回覆。將值設為 true 以保持對話的狀態，並將 false 設為結束對話。 |
userStorage |
儲存與特定使用者連結的持續性資料。儲存空間總容量為 10,000 個位元組。 |
richResponse |
這個欄位包含語音、文字、資訊卡、建議或結構化資料，以便 Google 助理進行算繪。如要進一步瞭解如何在 Actions on Google 中使用複合式回應，請參閱複合式回應一文 |
systemIntent |
這個欄位的結構與 ExpectedInput.possibleIntents 相同。如果回應使用了輔助意圖，則回應通常會包含 systemIntent。systemIntent 中的 possibleIntents 欄位必須設為 ExpectedIntent 物件，並將 inputValueData 欄位名稱變更為 data。 |
在 ExpectedIntent 物件中指定下列值：
- intent：輔助意圖的意圖名稱，指出您想提供使用者的資訊類型。
- data：值規格，該字串用於說明 Google 助理執行輔助工具所需的資料，
例如，如果您要要求使用者的權限，請將 intent 設為 actions.intent.PERMISSSION，並將 data 設為值規格為 "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"，以及該類型的欄位。
下列清單概略列出可協助您在 systemIntent 中為 Dialogflow Webhook 回應設定的輔助值值規格字串。如需 Actions on Google 意圖進行對話控制的完整清單，請參閱 Intents 參考資料。
| 意圖名稱 | Dialogflow 事件名稱 | 值規格 | 說明 |
|---|---|---|---|
actions.intent.CONFIRMATION
|
actions_intent_CONFIRMATION |
"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"
|
獲得使用者確認 (例如回答「是」或「否」)。 |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
取得使用者輸入的日期和時間。 |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
取得使用者的寄送地址。 |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
要求進入 Android 應用程式的深層連結流程。 |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
從清單或輪轉介面 UI 取得所選項目。 |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
取得使用者的資訊，包括全名、概略位置或精確位置。 |
actions.intent.SIGN_IN
|
actions_intent_SIGN_IN |
"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"
|
提出帳戶連結流程以連結使用者帳戶。 |
簡易回應範例
下列程式碼片段顯示 Dialogflow Webhook 格式的簡易回應範例。
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
協助工具範例
下列程式碼片段示範了以 Dialogflow Webhook 格式使用輔助意圖的範例。在這個範例中，Webhook 會使用 actions.intent.OPTIONS 輔助意圖指示 Google 助理在兩個選項之間取得使用者選項。
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Choose a item"
}
}
]
},
"systemIntent": {
"intent": "actions.intent.OPTION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"listSelect": {
"title": "Hello",
"items": [
{
"optionInfo": {
"key": "first title key"
},
"description": "first description",
"image": {
"url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
"accessibilityText": "first alt"
},
"title": "first title"
},
{
"optionInfo": {
"key": "second"
},
"description": "second description",
"image": {
"url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
"accessibilityText": "second alt"
},
"title": "second title"
}
]
}
}
}
}
}
}
收到上一個範例的訊息時，Google 助理會暫時接管對話，並提示使用者根據指定選項進行選擇。收集所有必要的使用者輸入內容時，Google 助理會將這個輔助結果傳回您在 Dialogflow Webhook 要求中的履行要求。
下列程式碼片段顯示了使用者選項選項的輔助結果範例。
{
"responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
"queryResult": {
"queryText": "actions_intent_OPTION",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
"parameters": {
"OPTION": "key of selected item"
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow intent name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": []
},
"inputs": [
{
"rawInputs": [
{
"query": "Title of selected item",
"inputType": "TOUCH"
}
],
"arguments": [
{
"textValue": "Key of selected item",
"name": "OPTION"
}
],
"intent": "actions.intent.OPTION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
結束對話範例
以下程式碼片段是以 Dialogflow Webhook 格式結束對話工作階段的簡單回應範例。回應訊息中的 false 的 expectUserResponse 值會指示 Google 助理預期使用者不再輸入任何內容，且應該結束目前的對話。
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
如要瞭解如何在使用者叫用標準詞組以與 Google 助理結束對話時覆寫預設行為，請參閱對話結束指南。