Webhook

webhook 可以是标准 webhook，也可以是灵活 webhook。对于标准的网络钩子，请求和响应字段由 Conversational Agents (Dialogflow CX) 定义。使用灵活的 webhook，您可以定义请求和响应字段。

标准 webhook

使用标准 webhook，您可以使用由对话式 AI (Dialogflow CX) 定义的请求和响应消息。请求消息会提供有关会话的许多详细信息。例如，当前活跃页面、最近匹配的意图、会话参数值和代理定义的响应都包含在内。

标准 webhook 请求

调用具有网络钩子的 fulfillment 时，对话式代理 (Dialogflow CX) 会向您的网络钩子服务发送 HTTPS POST 网络钩子请求。此请求的正文是一个 WebhookRequest JSON 对象，其中包含有关会话的信息。

某些集成会使用其他信息填充 WebhookRequest.payload 字段。例如，Dialogflow CX 电话网关集成可提供最终用户的来电显示。

如需了解详情，请参阅 WebhookRequest(V3) 或 WebhookRequest(V3Beta1) 参考文档。

标准 webhook 响应

一旦网络钩子服务收到网络钩子请求，其需要发送一个网络钩子响应。您的响应会受到以下限制：

• 响应必须在您创建网络钩子资源时配置的超时时间内发生，否则请求将超时。
• 响应大小不得超过 64 KiB。

如需了解详情，请参阅 WebhookResponse(V3) 或 WebhookResponse(V3Beta1) 参考文档。

标准的网络钩子资源设置

以下介绍了标准 webhook 的 webhook 资源设置：

灵活的 webhook

借助灵活的 webhook，您可以定义请求 HTTP 方法、请求网址参数以及请求和响应消息的字段。请求只能提供所选的参数值，而响应只能提供参数替换值。实际上，这种限制是有益的，因为它简化了代理与 webhook 之间的接口。代理和 webhook 之间很少需要传递会话参数值以外的任何内容。这还简化了网络钩子的实现，因为请求和响应消息仅包含您需要的内容，并且您可以针对各种场景提供唯一的网络钩子消息。

灵活的 webhook 请求

为代理创建网络钩子资源时，您可以为网络钩子请求指定以下内容：

• 用于发送到您的网络钩子服务的网络钩子请求的 HTTP 方法。
• 对话式客服人员 (Dialogflow CX) 应使用该网址发送到您的网络钩子服务的会话参数值。
• 如果您选择 POST、PUT 或 PATCH 作为方法，则可以指定对话式代理 (Dialogflow CX) 应通过请求 JSON 正文发送到您的 Webhook 服务的会话参数值。

如需使用请求网址或 JSON 正文发送会话参数值，请像往常一样使用参数引用。您无需对参数引用进行网址转义，也不需要将引用括在引号中。在运行时，Conversational Agents (Dialogflow CX) 会根据需要对参数值进行网址转义。列表或复合值将以 JSON 格式提供。

在 JSON 正文中使用参数引用时，无论参数的类型如何，都必须将引用括在引号中。如果参数实际上是数值标量、列表或复合值，对话式 AI 助理 (Dialogflow CX) 会在运行时发送请求时移除引号，以保留参数的数据类型。字符串标量类型将保持引号。 如果字符串值中引用了数值标量、列表或复合值（例如“This is a number: $session.params.size”），则该参数将被视为字符串（“This is a number: 3”）。

例如，您可以向请求网址提供 fruit 和 size 会话参数值，如下所示：

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

并将其添加到请求 JSON 正文中，如下所示：

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

灵活的 webhook 响应

为代理创建网络钩子资源时，您可以指定会话参数，对话式客服 (Dialogflow CX) 应在运行时将其设置为网络钩子响应的特定字段。

您的响应会受到以下限制：

• 响应必须在您创建网络钩子资源时配置的超时时间内发生，否则请求将超时。
• 响应大小不得超过 64 KiB。

请使用以下格式指定标量、列表或复合字段：

$.fully.qualified.path.to.field

例如，考虑以下 JSON 响应：

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

如需指定“value”字段，请使用以下代码：

$.routes[0].legs[0].distance.value

灵活的网络钩子资源设置

以下介绍了灵活 webhook 的 webhook 资源设置：

使用预定义的自定义模板

Dialogflow 提供预定义的自定义模板，您可以使用这些模板将灵活的网络钩子与 Salesforce CRM 集成。

1. 在管理标签页下，依次点击 Webhook 和 + 创建。

2. 在子类型下，选择灵活。

3. 点击使用预定义模板进行配置以启用此功能。

4. 在集成类型下拉菜单中，选择 Salesforce。

5. 在 API 名称下拉菜单中，选择一个 API 名称。模板会根据您选择的 API 名称自动填写该 Webhook 表单。

   1. 根据您的参数，您可以手动配置以下字段（如果适用）：

      • 网络钩子网址
      • 方法
      • 请求正文 JSON
      • 响应配置

   2. 必需的 OAuth 字段将在身份验证部分中突出显示。

6. 点击保存以创建该 Webhook。

网络钩子服务要求

您的网络钩子服务必须满足以下要求：

• 它必须处理 HTTPS 请求。不支持 HTTP。如果您使用计算或无服务器计算解决方案在 Google Cloud Platform 上托管网络钩子服务，请参阅使用 HTTPS 服务的产品文档。对于其他托管项，请参阅获取您网域的 SSL 证书。
• 其请求的网址须可公开访问，除非它是作为 Cloud Run 函数托管的，或者是作为服务目录 webhook 访问的。
• 它必须按照标准网络钩子或灵活网络钩子部分中所述的方式处理请求和响应。
• 如果您的代理未与 Service Directory 专用网络访问通道集成，则网络钩子调用会被视为服务边界外，并在启用 VPC Service Controls 时被阻止。Service Directory 支持有限的端点，请参阅 Service Directory 了解详情。

身份验证

请务必保护您的网络钩子服务，确保只有您或您的对话式客服 (Dialogflow CX) 代理才有权发出请求。这是在创建网络钩子资源时进行配置。对话式 AI 助理 (Dialogflow CX) 支持以下身份验证机制：

第三方 OAuth

对话式 AI 助理 (Dialogflow CX) 可以从第三方 OAuth 提供方收集访问令牌，并在发出网络钩子请求时将其添加到授权 HTTP 标头中。

以下介绍了第三方 OAuth 的资源设置：

发送到 OAuth 端点网址以接收令牌的请求不包含为网络钩子请求配置的自定义请求标头。您可以将自定义信息作为 OAuth 端点网址查询字符串中的参数传递给 OAuth 服务器。

服务代理访问令牌

对话式 AI 客服 (Dialogflow CX) 可以使用对话式 AI 客服 (Dialogflow CX) 服务代理生成ID 令牌或访问令牌。

当对话式代理 (Dialogflow CX) 调用 webhook 时，系统会在授权 HTTP 标头中添加令牌。

ID 令牌

向

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

用于生成 ID 令牌的受众群体将是整个网络钩子网址（不包括任何查询参数）。如果您使用的是 Cloud Run，请确保 Cloud Run 受众群体支持此网址。例如，如果网络钩子网址为

https://myproject.cloudfunctions.net/my-function/method1?query=value

自定义受众群体中需要包含以下网址。

https://myproject.cloudfunctions.net/my-function/method1

任何网络钩子也可以选择性地使用 Google 客户端库或 github.com/googleapis/google-auth-library-nodejs 等开源库验证令牌。

访问令牌

向以下实体授予所需角色后，访问令牌便可用于访问其他 Google Cloud API：

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

HTTPS 证书验证

默认情况下，Conversational Agents (Dialogflow CX) 使用 Google 的默认信任库来验证 HTTPS 证书。如果您打算为 HTTPS 服务器使用 Google 的默认信任库无法识别的证书（例如自签名证书或自定义根证书），请参阅自定义 CA 证书。

特定于环境的 webhook

如果您使用环境将生产系统与开发系统隔离开来（推荐），则可以将 webhook 配置为特定于环境。对于您定义的每个 webhook 资源，您都可以为为代理定义的每个环境提供唯一的网址和身份验证设置。

这样，您就可以在将 webhook 代码更新部署到生产环境之前，安全地开发和测试这些更新。

创建或修改网络钩子资源

运行网络钩子服务后，您需要在代理中创建具有连接和身份验证信息的网络钩子资源。创建后，您还可以随时修改 webhook 资源设置。

如需创建或修改网络钩子资源，请执行以下操作：

网络钩子错误

如果您的网络钩子服务在处理网络钩子请求时发生错误，则网络钩子代码应返回以下某个 HTTP 状态代码：

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not found
• 500 Server fault
• 503 Service Unavailable

在以下任何一种错误情况下，Conversational Agents (Dialogflow CX) 都会调用网络钩子错误或超时内置事件，并继续照常处理：

• 响应已超时。
• 收到错误状态代码。
• 无效响应。
• 网络钩子服务不可用。

此外，如果网络钩子服务调用是由检测意图 API 调用触发的，则检测意图响应中的 queryResult.webhookStatuses 字段包含网络钩子状态信息。

自动重试

Conversational Agents (Dialogflow CX) 包含内部机制，可在发生特定网络钩子错误时自动重试，以提高稳健性。系统只会重试非终端错误（例如超时或连接错误）。

为了降低重复调用的可能性，请执行以下操作：

• 设置更长的 webhook 超时阈值。
• 支持 webhook 逻辑中的幂等性或去重。

使用 Cloud Run functions

对话式 AI 助理 (Dialogflow CX) 与 Cloud Run 函数集成，因此您可以轻松创建安全的无服务器网络钩子。如果您创建了一个与您的代理位于同一项目的函数，只需在身份验证配置中选择 Service Agent Auth -> ID Token，您的代理便可安全地调用您的网络钩子。

但是，在下面两种情况下，您必须手动设置此集成：

1. 您的代理项目必须存在具有以下地址的 Conversational Agents (Dialogflow CX) Service Agent service account：

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   当您为项目创建第一个代理时，系统通常会自动创建这个特殊的服务账号及关联的密钥。如果您的代理是在 2020 年 11 月 1 日之前创建的，则您可以触发这个特殊的服务账号的创建：
   1. 为项目创建新的代理。
   2. 执行以下命令：

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. 如果网络钩子函数位于与代理不同的项目中，则必须向函数项目中的 Conversational Agents (Dialogflow CX) Service Agent 服务账号提供 Cloud Functions Invoker IAM 角色。
3. 在“身份验证配置”部分中，依次选择 Service Agent Auth -> ID Token。

使用容器化 webhook 和 Go ezcx 框架

如果您想使用 Go 实现容器化 webhook，请参阅 Go ezcx 框架。此框架可以简化创建 webhook 时所需的许多步骤。

将 Cloud Run functions 与仅限内部流量搭配使用

只要代理位于同一项目或同一 VPC SC 边界中，设置为接受来自同一项目或同一 VPC SC 边界内的 VPC 网络的内部流量的 Cloud Run 函数就可以用作 webhook。

使用 Service Directory 进行专用网络访问

对话式 AI 助理 (Dialogflow CX) 与 Service Directory 专用网络访问集成，因此可以连接到 VPC 网络内的网络钩子目标。这样便可保留在 Google Cloud 网络内部的流量，并强制执行 IAM 和 VPC Service Controls。

如需设置以专用网络为目标的网络钩子，请执行以下操作：

1. 按照 Service Directory 专用网络配置中的说明来配置 VPC 网络和 Service Directory 端点。

2. 您的代理项目必须存在具有以下地址的 Conversational Agents (Dialogflow CX) Service Agent service account：

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   向 Conversational Agents (Dialogflow CX) Service Agent 服务账号授予以下 IAM 角色：
   • Service Directory 项目的 servicedirectory.viewer
   • 网络项目的 servicedirectory.pscAuthorizedService

3. 创建网络钩子时，提供 Service Directory 服务以及网址和可选的身份验证信息。

   控制台

   

   API

   请参阅 Webhook 类型的 serviceDirectory 字段。转到 Webhook API 参考文档

   为网络钩子参考选择协议和版本：

   协议	V3	V3beta1
   REST	网络钩子资源	网络钩子资源
   RPC	网络钩子接口	网络钩子接口
   C++	WebhooksClient	不可用
   C#	WebhooksClient	不可用
   Go	WebhooksClient	不可用
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	不可用	不可用
   Python	WebhooksClient	WebhooksClient
   Ruby	不可用	不可用

   关闭

如需排查问题，您可以设置非公开拨测，以检查 Service Directory 是否配置正确。

示例和问题排查

请参阅网络钩子方法指南。