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

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

在回應訊息中,falseexpectedUserResponse 值會向 Google 助理發出預期沒有使用者輸入的內容,且應結束目前的對話。finalResponse 值表示 Google 助理應在對話結束前向使用者顯示或輸出的內容。

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

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