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 助理」對話，請參閱 對話離開指南。