快速入门：创建 webhook

本指南介绍如何使用 webhook，让您的代理更具动态性。Cloud Functions 因其简单易用而用于托管 webhook，但您还可以通过许多其他方式托管 webhook 服务。该示例也使用 Go 编程语言，但您可以使用 Cloud Functions 支持的语言。您无需修改本指南的代码。

示例 webhook 代码会执行以下操作：

  • 从 webhook 请求中读取参数值。
  • 将参数值写入 webhook 响应。
  • 在 webhook 响应中提供文本响应。

准备工作

如果您不打算使用 webhook，可以跳过此快速入门。

在阅读本指南之前，请先完成以下事项：

  1. 阅读 Dialogflow CX 基础知识。
  2. 执行设置步骤。
  3. 执行构建代理快速入门指南中的步骤。以下步骤将继续处理同一代理。如果您不再拥有该代理，可以下载该代理并恢复该代理。

创建 Cloud Function

您可以通过 Google Cloud 控制台创建 Cloud Functions 函数（查看文档，打开控制台）。如需针对本指南创建函数，请执行以下操作：

  1. 您的 Dialogflow 代理和函数必须位于同一项目中，这一点非常重要。这是 Dialogflow 要安全访问函数的最简单方法。如需选择项目，请转到项目选择器。
  2. 转到 Cloud Functions 概览页面。
  3. 点击创建函数，然后设置以下字段：
    • 环境：第 1 代
    • 函数名称：shirts-agent-webhook
    • 区域：如果您为代理指定了区域，请使用同一区域。
    • HTTP Trigger type：HTTP
    • 网址：点击此处的复制按钮并保存相应的值。 配置 webhook 时需要使用此网址。
    • Authentication：需要身份验证
    • Require HTTPS（需要 HTTPS）：选中
  4. 点击保存。
  5. 点击下一步（您不需要特殊的运行时、构建、连接或安全设置）。
  6. 设置以下字段：
    • Runtime：选择最新的 Go 运行时。
    • 源代码：内嵌编辑器
    • 入口点：HandleWebhookRequest
  7. 将代码替换为以下代码： 
    // Package cxwh contains an example Dialogflow CX webhook
package cxwh

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

type fulfillmentInfo struct {
	Tag string `json:"tag"`
}

type sessionInfo struct {
	Session    string                 `json:"session"`
	Parameters map[string]interface{} `json:"parameters"`
}

type text struct {
	Text []string `json:"text"`
}

type responseMessage struct {
	Text text `json:"text"`
}

type fulfillmentResponse struct {
	Messages []responseMessage `json:"messages"`
}

// webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by the Dialogflow protocol buffers:
// https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookRequest
type webhookRequest struct {
	FulfillmentInfo fulfillmentInfo `json:"fulfillmentInfo"`
	SessionInfo     sessionInfo     `json:"sessionInfo"`
}

// webhookResponse is used to marshal a WebhookResponse JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by the Dialogflow protocol buffers:
// https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookResponse
type webhookResponse struct {
	FulfillmentResponse fulfillmentResponse `json:"fulfillmentResponse"`
	SessionInfo         sessionInfo         `json:"sessionInfo"`
}

// confirm handles webhook calls using the "confirm" tag.
func confirm(request webhookRequest) (webhookResponse, error) {
	// Create a text message that utilizes the "size" and "color"
	// parameters provided by the end-user.
	// This text message is used in the response below.
	t := fmt.Sprintf("You can pick up your order for a %s %s shirt in 5 days.",
		request.SessionInfo.Parameters["size"],
		request.SessionInfo.Parameters["color"])

	// Create session parameters that are populated in the response.
	// The "cancel-period" parameter is referenced by the agent.
	// This example hard codes the value 2, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{"cancel-period": "2"}

	// Build and return the response.
	response := webhookResponse{
		FulfillmentResponse: fulfillmentResponse{
			Messages: []responseMessage{
				{
					Text: text{
						Text: []string{t},
					},
				},
			},
		},
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
	w.WriteHeader(http.StatusInternalServerError)
	fmt.Fprintf(w, "ERROR: %v", err)
}

// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
	var request webhookRequest
	var response webhookResponse
	var err error

	// Read input JSON
	if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
		handleError(w, err)
		return
	}
	log.Printf("Request: %+v", request)

	// Get the tag from the request, and call the corresponding
	// function that handles that tag.
	// This example only has one possible tag,
	// but most agents would have many.
	switch tag := request.FulfillmentInfo.Tag; tag {
	case "confirm":
		response, err = confirm(request)
	default:
		err = fmt.Errorf("Unknown tag: %s", tag)
	}
	if err != nil {
		handleError(w, err)
		return
	}
	log.Printf("Response: %+v", response)

	// Send response
	if err = json.NewEncoder(w).Encode(&response); err != nil {
		handleError(w, err)
		return
	}
}
  8. 点击部署。
  9. 等待状态指示器显示函数已成功部署。在等待期间，请检查您刚刚部署的代码。代码注释描述了重要细节。

创建网络钩子

现在，Webhook 已经作为 Cloud Functions 函数存在，接下来您可以将此 Webhook 与您的代理相关联。如需为代理创建 webhook，请执行以下操作：

  1. 打开 Dialogflow CX 控制台。
  2. 选择您的 Google Cloud 项目。
  3. 选择您的代理。
  4. 选择管理标签页。
  5. 点击网络钩子。
  6. 点击创建。
  7. 填写以下字段：
    • 显示名：shirts-agent-webhook
    • 网络钩子网址：提供您在创建函数时保存的网络钩子网址。
    • 子类型：标准。
    • 所有其他字段均使用默认值。
  8. 点击保存。

使用网络钩子

现在，Webhook 可供代理使用，您可以在 fulfillment 中使用该 webhook。Order Confirmation 页面具有条目执行方式，该条目执行方式当前具有静态文本响应。如需将 fulfillment 更新为使用 webhook，请执行以下操作：

  1. 选择 Build 标签页。
  2. 点击订单确认页面，以展开代理构建器图表上的该页面。
  3. 点击页面上的 Entry Fulfillment 字段以打开执行方式面板。
  4. 删除 Agent say 标题下的现有文本响应。当您将鼠标悬停在文本上时，系统会显示删除 按钮。
  5. 点击启用 webhook。
  6. 从 Webhook 下拉菜单中选择 shirts-agent-webhook 选项。
  7. 在代码字段中输入 confirm。
  8. 点击保存。
  9. 关闭履单面板。

代理图屏幕截图

已部署的网络钩子代码会发送一个响应，该响应会创建一个名为 cancel-period 的参数。更新代理以在同一订单确认页面的最终代理响应中引用此参数：

  1. 点击显示 true 条件的条件路由以打开路由面板。
  2. 向下滚动到路由面板的 Fulfillment 部分，然后在 Agent say 标题下添加以下文本响应：You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. 点击保存。
  4. 关闭路线面板。

代理图屏幕截图

在模拟器中测试代理

您现在可以使用模拟器测试代理和 webhook：

  1. 点击测试代理。
  2. 输入 I want to buy a large red shirt，然后按 Enter 键。

由于您同时提供了尺寸和颜色，因此您为代理提供了创建衬衫订单所需的一切，因此它直接过渡到订单确认页面。

代理图屏幕截图

下面介绍了代理响应：

响应 说明
好的，我们新建一个订单。 New Order 页面变为活动状态后，系统会调用条目 fulfillment。响应是从此执行方式触发的。
您选择了一件大码的红色衬衫。 为 New Order 页面提供所有表单参数后，系统会调用条件路由检查表单是否已完成。响应是从此路线的执行方式触发的。此路由也会转换到 Order Confirmation 页面。
你可以在 5 天内自提大号红色衬衫的订单。 Order Confirmation 页面的条目 fulfillment 调用 webhook。请参阅网络钩子代码中的 confirm 函数。该函数会创建此文本响应，并使用 webhook 请求中提供的参数。
您可以在 2 天内取消订单。再见。 Order Confirmation 页面有一个条件路由，其条件始终为 true。此响应由该路线的执行方式触发。请注意，该响应会使用 webhook 响应中 webhook 设置的参数。
上一页
构建代理
下一页
通过集成进行互动