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 意圖完整清單,請參閱「意圖」參考資料。

意圖名稱 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 格式結束對話工作階段的簡單回應範例。回應訊息中的 expectUserResponsefalse 會向 Google 助理發出預期沒有使用者輸入的內容,且應結束目前的對話。

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

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