本節說明當 Actions on Google 透過 Actions SDK 叫用您要求時的 JSON 酬載格式。
對話開始後，系統會使用不重複的 conversationId 來識別對話內容。之後每次對 Google 助理發出使用者查詢時，執行要求都會收到 Webhook 必須處理及回應的意圖。此 conversationId 會在每個要求和回應組合中保留，直到對話結束為止。
要求主體
當使用者進行初始查詢或提供一些後續的輸入項目時，Google 助理就會將要求傳送至您的執行要求。來自 Google 助理的對話 Webhook 要求含有各種資料，例如已觸發的意圖、使用者輸入內容的原始文字，以及使用者裝置的表面功能。
以下提供對話 Webhook 格式的要求主要欄位：
| 欄位 | 說明 |
|---|---|
isInSandbox |
這個布林值變數主要用於處理「交易」功能，以指示您的 Webhook 是否應在沙箱模式中處理這項要求。在沙箱模式中，使用者不應透過使用者收費或執行任何訂購單。
預設設定為「true」。 |
surface |
使用者互動的 Google 助理介面及其功能相關資訊。 |
Inputs |
叫用要求的相關資訊。針對觸發叫用，其中包含對應至操作的意圖。針對對話中的後續要求，這個物件可能也包含與要求指定的預期輸入相對應的引數。 |
User |
提出要求的使用者資訊。包括使用者授予的權限，以及使用者的語言代碼。 |
Conversation |
對話內容的相關資訊，包括對話 ID、類型 (例如這項要求是否發起新的對話) 以及用於在對話生命週期中儲存永久資料的對話符記。 |
availableSurfaces |
這項資訊可用於多介面對話。 |
簡易叫用要求範例
以下程式碼片段是對話 Webhook 格式的叫用要求範例。
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.MAIN",
"rawInputs": [
{
"inputType": "VOICE",
"query": "Talk to my test app"
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
簡易對話要求範例
以下程式碼片段是對話 Webhook 格式的對話要求範例，其中使用者輸入內容是文字字串 (例如 「我的幸運數字是 88」)：
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.TEXT",
"rawInputs": [
{
"inputType": "VOICE",
"query": "My lucky number is 88."
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
回應主體
從出貨端點到 Google 助理的 HTTP 訊息標頭中的 Content-Type 必須為 application/json。
對話 Webhook 格式中的回應包含實際使用者介面等資料，以向使用者顯示使用者 (包括音訊和視覺元件)，以及可在後續要求中觸發的意圖 (稱為「預期意圖」)。預期意圖可以是 Google 助理能解讀的任何意圖，如 Intents API 參考資料中所述。
如要進一步瞭解如何在 Google 助理中顯示回應的格式設定使用者介面，請參閱回應說明文件。
簡易回應範例
以下程式碼片段是對話 Webhook 格式的簡易回應範例。
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TEXT"
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
}
}
]
}
}
}
]
}
協助工具範例
下列程式碼片段示範在對話 Webhook 格式中使用輔助意圖的範例。在這個範例中，Webhook 會使用 actions.intent.OPTIONS 輔助意圖來指示 Google 助理在多個選項之間取得使用者選項。
如要進一步瞭解如何使用輔助意圖，請參閱輔助程式指南。
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.OPTION",
"inputValueData": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"carouselSelect": {
"items": [
{
"optionInfo": {
"key": "one",
"synonyms": [
"synonym of KEY_ONE 1",
"synonym of KEY_ONE 2"
]
},
"description": "Description of number one",
"title": "Number one"
},
{
"optionInfo": {
"key": "two",
"synonyms": [
"synonym of KEY_TWO 1",
"synonym of KEY_TWO 2"
]
},
"description": "Description of number two",
"title": "Number two"
}
]
}
}
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this shows an example of a carousel"
}
}
],
"suggestions": [
{
"title": "1"
},
{
"title": "2"
}
]
}
}
}
]
}
結束對話範例
以下程式碼片段是以對話、Webhook 回應格式結束對話工作階段的簡單回應範例。
回應訊息中的 false 的 expectedUserResponse 值會指示 Google 助理預期使用者不再輸入任何內容，且應該結束目前的對話。finalResponse 值表示在對話結束之前，Google 助理應該向使用者顯示或輸出的內容。
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
如要瞭解如何在使用者叫用標準詞組以與 Google 助理結束對話時覆寫預設行為，請參閱對話結束一文。