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

Dialogflow Webhook 格式 {:#dialogflow-Webhook-format} (Dialogflow)

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

本節說明當 Actions on Google 透過 Dialogflow v2 叫用您的執行項目時,JSON 酬載的格式。

如果您使用 Dialogflow 建立動作,您的執行要求會透過其標準的 Webhook 格式 (而非 Actions on Google 對話 Webhook 格式) 與 Dialogflow 相互通訊。Dialogflow Webhook 格式包含對話 Webhook 格式的所有資訊,以及其他情境的 Dialogflow 專屬資料,例如背景資訊和參數的相關資訊。

如要查看 Dialogflow Webhook 的 JSON 訊息範例,您可以參考這個 GitHub 專案

要求主體

Dialogflow 的 request 訊息包含 Dialogflow Webhook 格式的資料。這個物件包含 Actions on Google 專屬資訊,摘要如下:

  • originalDetectIntentRequest.source 值為「google」。
  • originalDetectIntentRequest.version 表示要求的 Actions on Google 版本。
  • originalDetectIntentRequest.payload 包含 Actions on Google 特定資訊的關鍵資訊,包括來自 Google 助理的對話要求 JSON。
  • Dialogflow Webhook 要求不支援 Conversation.conversationToken 欄位。因此,您的履行要求可以使用 Dialogflow 結構定義,在對話的生命週期內保存資料。

簡易叫用要求範例

下列程式碼片段顯示 Dialogflow Webhook 格式的叫用要求範例。

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

簡易對話要求範例

下列程式碼片段顯示 Dialogflow Webhook 格式的對話要求範例,其中使用者輸入內容為文字字串。

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

小幫手結果範例

下列程式碼片段顯示採用 Dialogflow Webhook 格式的輔助結果範例。本範例顯示 Webhook 向 Google 助理指出使用者需要取得使用者確認後的回應。

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

回應主體

從出貨端點到 Google 助理的 HTTP 訊息標頭中的 Content-Type 必須為 application/json

您的出貨要求傳送給 Dialogflow 的回應訊息必須使用 Dialogflow Webhook 格式

與 Google 助理通訊時,回應通常會包含封裝「google」物件的 payload 物件。「google」酬載物件包含 Actions on Google 特定資訊。這個檔案至少要包含一個 expectUserResponse 欄位以及 richResponsesystemIntent 欄位。

google」酬載物件的主要欄位摘要如下:

欄位 說明
expectUserResponse 指出出貨資訊是否需要使用者回覆。將值設為 true 以保持對話的狀態,並將 false 設為結束對話。
userStorage 儲存與特定使用者連結的持續性資料。儲存空間總容量為 10,000 個位元組。
richResponse 這個欄位包含語音、文字、資訊卡、建議或結構化資料,以便 Google 助理進行算繪。如要進一步瞭解如何在 Actions on Google 中使用複合式回應,請參閱複合式回應一文
systemIntent 這個欄位的結構與 ExpectedInput.possibleIntents 相同。如果回應使用了輔助意圖,則回應通常會包含 systemIntentsystemIntent 中的 possibleIntents 欄位必須設為 ExpectedIntent 物件,並將 inputValueData 欄位名稱變更為 data

ExpectedIntent 物件中指定下列值:

  • intent:輔助意圖的意圖名稱,指出您想提供使用者的資訊類型。
  • data:值規格,該字串用於說明 Google 助理執行輔助工具所需的資料,

例如,如果您要要求使用者的權限,請將 intent 設為 actions.intent.PERMISSSION,並將 data 設為值規格為 "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec",以及該類型的欄位。

下列清單概略列出可協助您在 systemIntent 中為 Dialogflow Webhook 回應設定的輔助值值規格字串。如需 Actions on Google 意圖進行對話控制的完整清單,請參閱 Intents 參考資料。

意圖名稱 Dialogflow 事件名稱 值規格 說明
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" 獲得使用者確認 (例如回答「是」或「否」)。
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" 取得使用者輸入的日期和時間。
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" 取得使用者的寄送地址。
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" 要求進入 Android 應用程式的深層連結流程。
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" 從清單或輪轉介面 UI 取得所選項目。
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" 取得使用者的資訊,包括全名、概略位置或精確位置。
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" 提出帳戶連結流程以連結使用者帳戶。

簡易回應範例

下列程式碼片段顯示 Dialogflow Webhook 格式的簡易回應範例。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

協助工具範例

下列程式碼片段示範了以 Dialogflow Webhook 格式使用輔助意圖的範例。在這個範例中,Webhook 會使用 actions.intent.OPTIONS 輔助意圖指示 Google 助理在兩個選項之間取得使用者選項。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

收到上一個範例的訊息時,Google 助理會暫時接管對話,並提示使用者根據指定選項進行選擇。收集所有必要的使用者輸入內容時,Google 助理會將這個輔助結果傳回您在 Dialogflow Webhook 要求中的履行要求。

下列程式碼片段顯示了使用者選項選項的輔助結果範例。

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

結束對話範例

以下程式碼片段是以 Dialogflow Webhook 格式結束對話工作階段的簡單回應範例。回應訊息中的 falseexpectUserResponse 值會指示 Google 助理預期使用者不再輸入任何內容,且應該結束目前的對話。

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

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