创建网络钩子

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

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

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

准备工作

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

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

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

创建 Cloud Function

您可以使用 Google Cloud 控制台（访问文档，打开控制台）创建 Cloud Functions 函数。如需为本指南创建函数，请执行以下操作：

  1. 请务必确保 Dialogflow CX 智能体和函数位于同一项目中。这是 Dialogflow CX 安全访问函数的最简单方法。如需选择项目，请前往项目选择器。
  2. 前往 Cloud Functions 概览页面。
  3. 点击创建函数，然后设置以下字段：
    • 环境：第 1 代
    • 函数名称：shirts-agent-webhook
    • 区域：如果您为代理指定了区域，请使用同一区域。
    • HTTP 触发器类型：HTTP
    • 网址：点击此处的复制按钮，然后保存该值。 配置 webhook 时，您需要用到此网址。
    • 身份验证：需要进行身份验证
    • 需要 HTTPS：已选中
  4. 点击保存。
  5. 点击下一步（您不需要特殊的运行时、构建、连接或安全设置）。
  6. 设置以下字段：
    • 运行时：选择最新的 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]any `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]any{"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

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

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

使用 webhook

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

  1. 选择构建标签页。
  2. 点击 Order Confirmation 页面，在智能体构建器图表中展开该页面。
  3. 点击页面上的条目 fulfillment 字段，打开 fulfillment 面板。
  4. 删除 Agent says 标题下的现有文字回答。 将鼠标悬停在文本上时，系统会显示删除 按钮。
  5. 点击启用 webhook。
  6. 从 Webhook 下拉菜单中选择 shirts-agent-webhook 选项。
  7. 在标记字段中输入 confirm。
  8. 点击保存。
  9. 关闭执行方式面板。

代理图屏幕截图

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

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

代理图屏幕截图

在模拟器中测试智能体

您的代理和网络钩子已准备好使用模拟器进行测试：

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

由于您同时提供了尺码和颜色，因此您向代理提供了创建衬衫订单所需的所有信息，因此它会直接转换到 Order Confirmation 页面。

代理图屏幕截图

以下内容介绍了代理回答：

响应 说明
好的，我们开始新订单。 当 New Order 页面变为活跃状态时，系统调用了条目 fulfillment。此回答由该 fulfillment 触发。
您选择了一件红色大号衬衫。 当新订单页面的所有表单参数都已提供时，系统会调用检查表单是否填写完毕的条件路由。此回答是由此路由的 fulfillment 触发的。此路线还会过渡到订单确认页面。
您可以在 5 天后取走您订购的大号红色衬衫。 Order Confirmation 页面的条目 fulfillment 会调用 webhook。查看 webhook 代码中的 confirm 函数。该函数会创建此文本回答，并使用 webhook 请求中提供的参数。
您可以在 2 天内取消订单。再见。 Order Confirmation 页面有一个条件路由，其条件始终为 true。此响应由该路由的 fulfillment 触发。请注意，该回答使用了网络钩子在网络钩子响应中设置的参数。
上一页
使用流程构建代理
下一页
通过集成进行互动