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

本節說明 Actions on Google 叫用您的 JSON 酬載格式並透過 Dialogflow v2 處理執行要求。

如果您使用 Dialogflow 建立動作，執行要求會透過自己的標準 Webhook 格式與 Dialogflow 通訊 Actions on Google 對話 Webhook 格式。Dialogflow Webhook 格式包含當中會列出對話 Webhook 格式以及其他 Dialogflow 專屬資料，例如背景資訊和參數

如要查看更多 Dialogflow Webhook JSON 訊息範例，請參閱加入 GitHub 專案。

要求主體

request 訊息來自 Dialogflow 包含採用 Dialogflow Webhook 格式的資料。這個物件包含 Actions on Google 專屬資訊，摘要如下：

originalDetectIntentRequest.source 的值為「google」。
originalDetectIntentRequest.version 代表 Actions on Google 該字串。
originalDetectIntentRequest.payload 包含 Google 專屬的重要 Actions on Google 資訊，包括對話內容要求由 Google 助理產生的 JSON
Dialogflow Webhook 不支援 Conversation.conversationToken 欄位要求。您的執行要求可以使用 Dialogflow context，在整個對話壽命

簡易叫用要求範例

下列程式碼片段顯示 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}"
}

回應主體

執行要求端點 HTTP 訊息標頭中的 Content-Type 必須使用 application/json 連線至 Google 助理。

您的執行要求傳送至 Dialogflow 的回應訊息必須位於 Dialogflow Webhook 格式。

與 Google 助理通訊時，回覆內容通常會包含payload 封裝「google」的物件物件。「google」酬載物件包含 Actions on Google 專屬資訊。當中至少必須包含 expectUserResponse 欄位，以及 richResponse 或 systemIntent 欄位。

「google」的鍵欄位酬載物件的摘要如下：

欄位	說明
`expectUserResponse`	指出執行要求是否會預期使用者回應。將值設為 `true` 可繼續對話，設為 `false` 則可結束對話。
`userStorage`	儲存與特定使用者相關聯的持續資料。總儲存空間 10,000 個位元組
`richResponse`	這個欄位包含音訊、文字、資訊卡、建議或結構化資料所需的資訊如要進一步瞭解如何針對 Actions on Google，請參閱多元回應
`systemIntent`	這個欄位的結構與 `ExpectedInput.possibleIntents` 相同。您的回覆通常會包含如果執行要求使用的是`systemIntent` 輔助意圖。`systemIntent` 中的 `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}"
}

結束對話範例

下列程式碼片段顯示用來結束對話的簡單回應範例產生一個工作階段 expectUserResponse敬上在傳送給 Google 助理的回應訊息中指出 false 的值使用者不會進行任何後續動作只要終止目前的對話。

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

瞭解如何在使用者叫用標準時覆寫預設行為詞組結束與「Google 助理」對話，請參閱對話離開指南。