对话 webhook 格式 {:#conversation-webhook-format} (Dialogflow)

本部分介绍 Actions on Google 调用您的通过 Actions SDK 执行。

对话开始后，即会获得一个唯一的 conversationId 进行标识。对于每个后续用户您的执行方式会收到一个 intent，网络钩子必须处理和响应。此 conversationId 将存在于每个请求中，响应对，直到对话结束。

请求正文

当用户进行初始询问或提供后续输入时，Google 助理会发送请求。对话 webhook 请求包含数据，例如触发的 intent、用户的原始文本输入和 Surface 功能。

对话 webhook 格式中请求的关键字段总结如下：

字段	说明
`isInSandbox`	该布尔变量主要用于事务功能，用于指明网络钩子是否应在沙盒中处理此请求模式。在沙盒模式下，网络钩子不应向用户收取任何采购订单的款项，也不应履行任何采购订单。默认设置为“`true`”。
`surface`	有关用户当前与之互动的 Google 助理 surface 及其功能的信息。
`Inputs`	调用请求的相关信息。对于触发调用，这包括一个 intent。对于后续的请求，此对象可能还包含与您的执行方式指定的预期输入。
`User`	发起请求的用户的相关信息。这些信息包括权限和用户的语言区域。
`Conversation`	有关对话上下文的信息，包括对话 ID、类型（例如，此请求是否正在发起新对话）以及对话令牌在整个对话生命周期内存储持久性数据。
`availableSurfaces`	这些信息会用于 <ph type="x-smartling-placeholder"></ph> 多表面对话。

简单调用请求示例

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

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to my test app"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

简单对话请求示例

以下代码段显示了一个对话 webhook 格式的对话请求示例，其中，用户输入是文本字符串（例如，“My lucky number is 88.”）：

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.TEXT",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "My lucky number is 88."
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

响应正文

来自执行方式端点的 HTTP post 的标头中的 Content-Type 发送到 Google 助理的状态必须为 application/json。

响应（位于对话 webhook 格式包含数据，例如显示用户（包括音频和视觉组件）以及可被在后续请求中触发（称为“预期意图”）。预期 intent 可以是 Google 助理可以理解的任何 intent，如前所述 Intents API 参考中给出的值。

详细了解如何在设置响应时它们会显示在 Google 助理中，请参阅响应文档。

简单响应示例

以下代码段显示了对话中的简单响应示例 webhook 格式。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
              }
            }
          ]
        }
      }
    }
  ]
}

帮助程序示例

以下代码段展示了在对话中使用帮助程序 intent 的示例 webhook 格式。在此示例中，webhook 使用 actions.intent.OPTIONS 辅助 intent，用于指示 Google 助理获取供用户在多个选项之间进行选择

如需详细了解如何使用辅助 intent，请参阅帮助程序指南。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.OPTION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
            "carouselSelect": {
              "items": [
                {
                  "optionInfo": {
                    "key": "one",
                    "synonyms": [
                      "synonym of KEY_ONE 1",
                      "synonym of KEY_ONE 2"
                    ]
                  },
                  "description": "Description of number one",
                  "title": "Number one"
                },
                {
                  "optionInfo": {
                    "key": "two",
                    "synonyms": [
                      "synonym of KEY_TWO 1",
                      "synonym of KEY_TWO 2"
                    ]
                  },
                  "description": "Description of number two",
                  "title": "Number two"
                }
              ]
            }
          }
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this shows an example of a carousel"
              }
            }
          ],
          "suggestions": [
            {
              "title": "1"
            },
            {
              "title": "2"
            }
          ]
        }
      }
    }
  ]
}

结束对话示例

以下代码段显示了一个用于结束对话的简单响应示例会话 webhook 响应格式。

expectedUserResponse 响应消息中的 false 值会向 Google 助理表明，没有进一步的用户正确输入，并结束当前对话。通过 finalResponse 值指示 Google 助理先显示或输出什么内容对话结束。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

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