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

本節說明 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 助理」對話，請參閱對話結束。