對話 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 助理」對話,請參閱 對話結束