创建网络钩子

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

网络钩子代码示例会执行以下操作：

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

准备工作

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

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

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

创建 Cloud Function

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

  1. 请务必确保您的 Conversational Agents (Dialogflow CX) 客服和函数位于同一项目中。这是对话式 AI 客服 (Dialogflow CX) 安全访问您的函数的最简单方法。如需选择项目，请前往项目选择器。
  2. 前往 Cloud Functions 概览页面。
  3. 点击创建函数，然后设置以下字段：
    • 环境：第 1 代
    • 函数名称：shirts-agent-webhook
    • 区域：如果您为代理指定了区域，请使用相同的区域。
    • HTTP 触发器类型：HTTP
    • 网址：点击此处的复制按钮，然后保存该值。 您在配置该网络钩子时需要使用此网址。
    • 身份验证：需要进行身份验证
    • 需要 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]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，请执行以下操作：

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

使用该 Webhook

现在，代理可以使用 webhook，您将在执行方式中使用 webhook。订单确认页面包含一个 fulfillment 条目，目前该条目使用的是静态文本响应。如需更新 fulfillment 以使用您的 webhook，请执行以下操作：

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

代理图屏幕截图

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

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

代理图屏幕截图

在模拟器中测试代理

您的聊天机器人和网络钩子已准备好使用模拟器进行测试：

  1. 点击 Test Agent。
  2. 输入 I want to buy a large red shirt，然后按 Enter 键。

由于您同时提供了尺寸和颜色，因此您已向客服人员提供了创建衬衫订单所需的所有信息，因此系统会直接转到订单确认页面。

代理图屏幕截图

以下是客服人员的回复：

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