本節說明當 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 助理結束對話時覆寫預設行為,請參閱對話結束指南。