Dialogflow 网络钩子格式 {:#dialogflow-webhook-format} (Dialogflow)

本部分介绍了 Actions on Google 通过 Dialogflow v2 调用您的执行方式时 JSON 载荷的格式。

如果您使用 Dialogflow 创建 Action,您的 fulfillment 将通过它自己的标准网络钩子格式(而不是 Actions on Google 对话网络钩子格式)与 Dialogflow 进行通信。Dialogflow 网络钩子格式包含对话网络钩子格式的所有信息以及特定于 Dialogflow 的其他数据(例如上下文和参数信息)。

如需查看 Dialogflow 网络钩子的 JSON 消息的更多示例,您可以参阅此 GitHub 项目

请求正文

来自 Dialogflow 的 request 消息包含 Dialogflow 网络钩子格式的数据。此对象包含 Actions on Google 的专有信息,总结如下:

  • originalDetectIntentRequest.source 值为“google”。
  • originalDetectIntentRequest.version 表示相应请求的 Actions on Google 版本。
  • originalDetectIntentRequest.payload 包含与 Actions on Google 相关的关键信息,包括来自 Google 助理的对话请求 JSON。
  • Dialogflow 网络钩子请求不支持 Conversation.conversationToken 字段。相反,您的执行方式可以使用 Dialogflow 上下文在整个对话生命周期内保留数据。

简单调用请求示例

以下代码段显示了一个 Dialogflow 网络钩子格式的调用请求示例。

{
  "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 网络钩子格式的对话请求示例,其中用户输入的是文本字符串。

{
  "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 向 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

您的 fulfillment 向 Dialogflow 发送的响应消息必须采用 Dialogflow 网络钩子格式

与 Google 助理通信时,您的响应通常包含一个封装“google”对象的 payload 对象。“google”载荷对象包含 Actions on Google 专有的信息。它必须至少包含一个 expectUserResponse 字段以及一个 richResponsesystemIntent 字段。

google”载荷对象的关键字段总结如下:

字段 说明
expectUserResponse 指明您的执行方式是否需要用户响应。将值设置为 true(表示保持对话)和 false(结束对话)。
userStorage 存储与特定用户关联的持久性数据。总存储量为 10000 字节。
richResponse 此字段包含供 Google 助理呈现的音频、文本、卡片、建议或结构化数据。如需详细了解如何为 Actions on Google 使用富响应,请参阅富响应
systemIntent 此字段的结构与 ExpectedInput.possibleIntents 相同。如果您的执行方式使用的是帮助程序 intent,那么您的响应通常会包含 systemIntentsystemIntent 中的 possibleIntents 字段必须设置为 ExpectedIntent 对象,并将 inputValueData 字段名称更改为 data

ExpectedIntent 对象中,指定以下值:

  • intent:帮助程序的 intent 名称,指示您希望用户提供的信息类型;
  • data:值规范,这是一个字符串,用于描述 Google 助理执行帮助程序所需的数据。

例如,如果您要请求用户授予权限,请将 intent 设置为 actions.intent.PERMISSSION,将 data 将值规范设置为 "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec",并设置该类型的字段。

以下列表总结了您可以在 Dialogflow 网络钩子响应的 systemIntent 中设置的帮助程序的值规范字符串。如需查看用于对话控制的 Actions on Google intent 的完整列表,请参阅意图参考文档。

intent 名称 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" 从列表或轮播界面获取选定项。
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 网络钩子格式的简单响应示例。

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

帮助程序示例

以下代码段举例说明了如何使用 Dialogflow 网络钩子格式的帮助程序 intent。在此示例中,您的网络钩子使用 actions.intent.OPTIONS 辅助 intent 来指示 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 请求中将此帮助程序结果发送回您的 fulfillment。

以下代码段展示了包含用户选择选项的帮助程序结果的示例。

{
  "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 网络钩子格式结束对话会话的简单响应示例。响应消息中 falseexpectUserResponse 值会向 Google 助理表明,预计不会再有用户输入,应该结束当前对话。

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

如需了解如何在用户调用标准短语结束与 Google 助理的对话时替换默认行为,请参阅对话退出指南