本節說明 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 意圖完整清單,請參閱「意圖」參考資料。
意圖名稱 | 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 格式結束對話工作階段的簡單回應範例。回應訊息中的 expectUserResponse
值 false
會向 Google 助理發出預期沒有使用者輸入的內容,且應結束目前的對話。
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
如要瞭解當使用者叫用標準詞組以結束與 Google 助理的對話時的預設行為,請參閱「對話結束指南」。