创建网络钩子

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

示例 webhook 代码执行以下操作:

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

准备工作

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

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

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

创建 Cloud Functions 函数

您可以使用 Google Cloud 控制台创建 Cloud Functions 函数(访问文档打开控制台)。 要为本指南创建一个函数,请执行以下操作:

  1. 对话代理 (Dialogflow CX) 代理和功能 它们属于同一个项目 这是对话代理 (Dialogflow CX) 将 安全地访问函数。 如需选择项目,请前往项目选择器
  2. 前往 Cloud Functions 概览页面
  3. 点击创建函数,并设置以下字段:
    • 环境:第 1 代
    • 函数名称:shirts-agent-webhook
    • 区域:如果您为代理指定了区域, 使用同一区域
    • HTTP 触发器类型:HTTP
    • 网址:点击此处的复制按钮并保存相应值。 配置 webhook 时需要用到此网址。
    • Authentication:需要进行身份验证
    • 需要 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 函数存在,您需要将此网络钩子与您的代理相关联。如需为代理创建网络钩子,请执行以下操作:

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

使用该 Webhook

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

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

代理图屏幕截图

部署的网络钩子代码会发送响应,以创建名为 cancel-period参数。更新代理以在最终代理响应中引用此参数 同一 Order Confirmation 页面:

  1. 点击显示 true 条件的路线条件,以打开路线面板。
  2. 向下滚动到路线面板的 Fulfillment 部分。 然后在 Agent say 标题下添加以下文本响应: 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 键。

由于您同时提供了尺寸和颜色 您向客服人员提供了创建衬衫订单所需的一切, 因此会直接转到订单确认页面。

代理图屏幕截图

下面介绍了代理响应:

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