本節說明 Actions on Google 透過 Actions SDK 叫用執行要求時,JSON 酬載的格式。
對話開始後,會以不重複的 conversationId
識別。針對後續向 Google 助理提出的使用者後續查詢,您的執行要求都會收到 Webhook 必須處理及回應的「意圖」。此 conversationId
會保留在每個要求和回應組合中,直到對話結束為止。
要求主體
使用者進行初始查詢或提供後續輸入內容時,Google 助理會傳送要求至執行要求。Google 助理的對話 Webhook 要求包含各種資料,例如觸發的意圖、使用者輸入內容的原始文字,以及裝置表面功能。
對話 Webhook 格式中要求的主要欄位摘要如下:
欄位 | 說明 |
---|---|
isInSandbox |
這個布林值變數主要用於
交易功能,以指出 Webhook 是否應在沙箱模式下處理這項要求。在沙箱模式中,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 格式的對話要求範例,其中使用者輸入內容為文字字串 (例如「My Lucy number is 88」(我的幸運數字是 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 格式的「回應」包含資料,例如用於顯示使用者的實際 UI (包括音訊和視覺元件),以及可在後續要求中觸發的意圖 (稱為「預期意圖」)。預期意圖可以是 Google 助理理解的任何意圖,詳情請參閱 Intent 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 助理的對話時,如何覆寫預設行為,請參閱「對話結束」。