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