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

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

对话开始后,将由唯一的 conversationId 进行标识。对于 Google 助理的每次用户后续查询,您的执行方式都会收到一个 intent,您的网络钩子必须处理并响应该 intent。此 conversationId 会保留在每个请求和响应对中,直到对话结束。

请求正文

当用户进行初始查询或提供一些后续输入时,Google 助理会向您的执行方式发送请求。来自 Google 助理的对话网络钩子请求包含一些数据,例如触发的 intent、用户输入的原始文本,以及用户设备的 Surface 功能。

下面总结了对话网络钩子格式的请求的关键字段:

字段 说明
isInSandbox 此布尔值变量主要用于 交易功能,以指示您的网络钩子是否应在沙盒模式下处理此请求。在沙盒模式下,您的网络钩子不应扣款或履行用户的任何采购订单。默认情况下,它设置为“true”。
surface 用户与之互动的 Google 助理 surface 及其功能的相关信息。
Inputs 有关调用请求的信息。对于触发调用,这包括映射到操作的 intent。对于对话中的后续请求,此对象可能还包含与执行方式指定的预期输入相对应的参数。
User 发起请求的用户的相关信息。这些信息包括用户授予的权限以及用户的语言区域。
Conversation 对话上下文的相关信息,包括对话 ID、类型(例如,此请求是否正在发起新对话)以及用于在对话生命周期内存储持久性数据的对话令牌。
availableSurfaces 此信息可用于 多平台对话

简单调用请求示例

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

{
  "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"
        }
      ]
    }
  ]
}

简单对话请求示例

以下代码段显示对话网络钩子格式的对话请求示例,其中用户输入的是文本字符串(例如“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"
        }
      ]
    }
  ]
}

响应正文

从执行方式端点到 Google 助理的 HTTP 帖子标头中的 Content-Type 必须为 application/json

对话网络钩子格式的响应包含一些数据,例如向用户显示的实际界面(包括音频和视觉组件),以及可以在后续请求中触发的 intent(称为预期 intent)。预期 intent 可以是 Google 助理可以理解的任何 intent,如 intent API 参考文档中所述。

如需详细了解如何设置响应显示在 Google 助理中的界面的格式,请参阅响应文档。

简单响应示例

以下代码段展示了对话网络钩子格式的简单响应示例。

{
  "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 使用 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"
            }
          ]
        }
      }
    }
  ]
}

结束对话示例

以下代码段展示了一个采用对话网络钩子响应格式的结束对话会话的简单响应示例。

响应消息中 falseexpectedUserResponse 值会向 Google 助理表明,预计不会再有用户输入,且 Google 助理应结束当前对话。finalResponse 值指示 Google 助理在对话结束之前应向用户显示或输出的内容。

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

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