對話動作將於 2023 年 6 月 13 日淘汰。詳情請參閱對話動作停用

對話 Webhook 格式 {:#conversation-Webhook-format} (Dialogflow)

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本節說明當 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 回應格式結束對話工作階段的簡單回應範例。

回應訊息中的 falseexpectedUserResponse 值會指示 Google 助理預期使用者不再輸入任何內容,且應該結束目前的對話。finalResponse 值表示在對話結束之前,Google 助理應該向使用者顯示或輸出的內容。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

如要瞭解如何在使用者叫用標準詞組以與 Google 助理結束對話時覆寫預設行為,請參閱對話結束一文。