本節說明 Actions on Google 叫用您的 JSON 酬載格式 透過 Actions SDK 執行要求。
對話開始後,系統會以專屬的 conversationId
識別對話。每位後續使用者
向 Google 助理提出查詢時,您的執行要求會收到意圖,
Webhook 必須處理並回應此 conversationId
在每個要求中都會保留下來,
回應配對。
要求主體
當使用者進行初始查詢或後續輸入一些內容時,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 格式的對話要求範例。 其中,使用者輸入內容是文字字串 (例如「我的幸運數字是 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" } ] } ] }
回應主體
執行要求端點 HTTP 訊息標頭中的 Content-Type
必須使用 application/json
連線至 Google 助理。
回應中的回應 對話 Webhook 格式包含實際 UI 等資料 使用者 (包括音訊與視覺元件) 及可解釋的意圖 可在後續要求中觸發 (稱為預期意圖)。預期 「意圖」可以是 Google 助理理解的任何意圖, Intents API 參考資料中的指示操作。
想進一步瞭解如何設定使用者介面格式,以顯示回應 警示訊息中,請參閱 回應說明文件。
簡易回應範例
下列程式碼片段顯示對話中的簡單回應範例 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 回應格式
expectedUserResponse
回覆訊息中的 false
值會告知 Google 助理已無其他使用者
輸入值,並應結束目前的對話
finalResponse
敬上
的數值,代表 Google 助理在播放前應向使用者顯示或輸出的內容
對話就會結束
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
瞭解如何在使用者叫用標準時覆寫預設行為 詞組結束與「Google 助理」對話,請參閱 對話結束。