本節說明 Actions on Google 叫用您的 JSON 酬載格式 並透過 Dialogflow v2 處理執行要求。
如果您使用 Dialogflow 建立動作,執行要求 會透過自己的標準 Webhook 格式與 Dialogflow 通訊 Actions on Google 對話 Webhook 格式。Dialogflow Webhook 格式包含 當中會列出 對話 Webhook 格式 以及其他 Dialogflow 專屬資料,例如 背景資訊和參數
如要查看更多 Dialogflow Webhook JSON 訊息範例,請參閱 加入 GitHub 專案。
要求主體
request 訊息來自 Dialogflow 包含採用 Dialogflow Webhook 格式的資料。這個物件包含 Actions on Google 專屬資訊,摘要如下:
originalDetectIntentRequest.source
的值為「google」。originalDetectIntentRequest.version
代表 Actions on Google 該字串。originalDetectIntentRequest.payload
包含 Google 專屬的重要 Actions on Google 資訊,包括對話內容 要求 由 Google 助理產生的 JSON- Dialogflow Webhook 不支援
Conversation.conversationToken
欄位 要求。您的執行要求可以使用 Dialogflow context,在整個 對話壽命
簡易叫用要求範例
下列程式碼片段顯示 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}"
}
回應主體
執行要求端點 HTTP 訊息標頭中的 Content-Type
必須使用 application/json
連線至 Google 助理。
您的執行要求傳送至 Dialogflow 的回應訊息必須位於 Dialogflow Webhook 格式。
與 Google 助理通訊時,回覆內容通常會包含payload
封裝「google
」的物件物件。「google
」酬載物件包含
Actions on Google 專屬資訊。當中至少必須包含
expectUserResponse
欄位,以及 richResponse
或 systemIntent
欄位。
「google
」的鍵欄位酬載物件的摘要如下:
欄位 | 說明 |
---|---|
expectUserResponse |
指出執行要求是否會預期使用者回應。將值設為 true 可繼續對話,設為 false 則可結束對話。 |
userStorage |
儲存與特定使用者相關聯的持續資料。總儲存空間 10,000 個位元組 |
richResponse |
這個欄位包含音訊、文字、資訊卡、建議或結構化資料 所需的資訊如要進一步瞭解如何針對 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}"
}
結束對話範例
下列程式碼片段顯示用來結束對話的簡單回應範例
產生一個工作階段
expectUserResponse
敬上
在傳送給 Google 助理的回應訊息中指出 false
的值
使用者不會進行任何後續動作
只要終止目前的
對話。
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
瞭解如何在使用者叫用標準時覆寫預設行為 詞組結束與「Google 助理」對話,請參閱 對話離開指南。