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

本部分介绍 Actions on Google 调用您的通过 Dialogflow v2 完成。

如果你使用 Dialogflow 创建 Action，你的 fulfillment 通过其自己的标准 webhook 格式与 Dialogflow 通信， Actions on Google 对话网络钩子格式。Dialogflow webhook 格式包含所有信息会话网络钩子格式以及其他特定于 Dialogflow 的数据，上下文和参数。

如需查看 Dialogflow webhook 的 JSON 消息的更多示例，您可以添加到此 GitHub 项目中。

请求正文

request 消息来自 Dialogflow 包含 Dialogflow 网络钩子格式的数据。该对象包括 Actions on Google 特定信息，总结如下：

originalDetectIntentRequest.source 的值为“google”。
originalDetectIntentRequest.version 表示 Actions on Google 版本
originalDetectIntentRequest.payload包含特定于 Actions on Google 的关键操作信息，包括对话请求来自 Google 助理的 JSON。
Dialogflow webhook 不支持 Conversation.conversationToken 字段请求。你的 fulfillment 可以使用 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 中网络钩子格式，其中用户输入是文本字符串。

{
  "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 网络钩子格式的帮助程序结果示例。此示例显示了在网络钩子向 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 post 的标头中的 Content-Type 发送到 Google 助理的状态必须为 application/json。

您的 fulfillment 向 Dialogflow 发送的响应消息必须采用 Dialogflow webhook 格式。

与 Google 助理通信时，你的响应通常会包含 payload 用于封装“google”的对象对象。“google”载荷对象包括 Actions on Google 专用信息。它必须至少包含一个 expectUserResponse 字段，以及 richResponse 或 systemIntent 字段。

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

字段	说明
`expectUserResponse`	指明您的执行方式是否需要用户响应。将值设置为 `true` 何时持续对话，`false` 结束对话。
`userStorage`	存储与特定用户关联的持久性数据。总存储空间大小为 10,000 个字节。
`richResponse`	此字段包含音频、文本、卡片、建议或结构化数据，供 Google 助理呈现。了解关于为以下内容使用富响应的详情： Actions on Google，请参阅丰富的响应
`systemIntent`	此字段的结构与 `ExpectedInput.possibleIntents`。您的回复通常包含 `systemIntent`（如果您的执行方式使用的是辅助 intent。通过 `possibleIntents` `systemIntent` 中的字段必须设置为 `ExpectedIntent` 对象，且 `inputValueData` 字段名称已更改为 `data`。

在 ExpectedIntent内对象，您可以指定以下值：

intent：帮助程序的 intent 名称，用于指示您希望用户提供的信息，以及
data：值规范，即一个字符串，用于描述要让 Google 助理执行所需的操作

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

以下列表总结了可在 systemIntent，用于 Dialogflow 网络钩子响应。有关 Actions on Google intent 的完整列表有关对话控制，请参阅 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 Webhook 格式的简单响应的示例。

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

帮助程序示例

以下代码段展示了在 Dialogflow 中使用帮助程序 intent 的示例 webhook 格式。在此示例中，网络钩子使用的是 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 网络钩子请求将此帮助程序结果发送回您的执行方式。

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

{
  "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 格式导出会话。通过 expectUserResponse 响应消息中的 false 值向 Google 助理发出信号预计不需要进一步的用户输入，并且应该结束当前的对话。

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

了解如何在用户调用标准来结束与 Google 助理的对话，请查看对话退出指南。