本指南介绍了如何使用 webhook,以便让您的聊天机器人更加灵活。由于 Cloud Functions 简单易用,因此我们将其用作托管 webhook 的平台,但您还可以通过许多其他方式托管 webhook 服务。该示例还使用了 Go 编程语言,但您可以使用 Cloud Functions 支持的任何语言。您无需修改本指南的代码。
示例 webhook 代码执行以下操作:
- 从网络钩子请求中读取参数值。
- 将参数值写入 Webhook 响应。
- 在 webhook 响应中提供文本响应。
准备工作
如果您不打算使用 webhook,则可以跳过此快速入门。
在阅读本指南之前,请先完成以下事项:
创建 Cloud Functions 函数
您可以使用 Google Cloud 控制台创建 Cloud Functions 函数(访问文档,打开控制台)。 要为本指南创建一个函数,请执行以下操作:
- 对话代理 (Dialogflow CX) 代理和功能 它们属于同一个项目 这是对话代理 (Dialogflow CX) 将 安全地访问函数。 如需选择项目,请前往项目选择器。
- 前往 Cloud Functions 概览页面。
- 点击创建函数,并设置以下字段:
- 环境:第 1 代
- 函数名称:shirts-agent-webhook
- 区域:如果您为代理指定了区域, 使用同一区域
- HTTP 触发器类型:HTTP
- 网址:点击此处的复制按钮并保存相应值。 配置 webhook 时需要用到此网址。
- Authentication:需要进行身份验证
- 需要 HTTPS:已选中
- 点击保存。
- 点击下一步(您无需特殊的运行时、构建、连接或安全设置)。
- 设置以下字段:
- 运行时:选择最新的 Go 运行时。
- 源代码:内嵌编辑器
- 入口点:HandleWebhookRequest
将代码替换为以下代码:
// 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 } }
点击部署。
等待状态指示器显示函数已成功部署。等待期间,检查您刚刚部署的代码。 代码注释用于描述重要细节。
创建 webhook
现在,网络钩子已作为 Cloud Functions 函数存在,您需要将此网络钩子与您的代理相关联。如需为代理创建网络钩子,请执行以下操作:
- 打开 Dialogflow CX 控制台。
- 选择您的 Google Cloud 项目。
- 选择您的代理。
- 选择管理标签页。
- 点击网络钩子。
- 点击创建。
- 填写以下字段:
<ph type="x-smartling-placeholder">
- </ph>
- 显示名称:shirts-agent-webhook
- 网络钩子网址:提供您保存的网络钩子网址 指定名称。
- 子类型:标准。
- 所有其他字段均使用默认值。
- 点击保存。
使用该 Webhook
现在 webhook 可供代理使用, 您将在 Cloud Shell 中 fulfillment。 订单确认页面包含一个 fulfillment 条目,目前该条目使用的是静态文本响应。如需更新 fulfillment 以使用您的 webhook,请执行以下操作:
- 选择构建标签页。
- 点击订单确认页面以展开该页面 。
- 点击页面上的 Entry Fulfillment 字段 以打开 fulfillment 面板。
- 删除“客服人员的回答”标题下方的现有文本响应。 将鼠标悬停在文字上时, 删除delete 按钮。
- 点击启用 Webhook。
- 选择
shirts-agent-webhook
选项 Webhook 下拉菜单中。 - 在代码字段中输入
confirm
。 - 点击保存。
- 关闭“执行”面板。
部署的网络钩子代码会发送响应,以创建名为 cancel-period
的参数。更新代理以在最终代理响应中引用此参数
同一 Order Confirmation 页面:
- 点击显示
true
条件的路线条件,以打开路线面板。 - 向下滚动到路线面板的 Fulfillment 部分。
然后在 Agent say 标题下添加以下文本响应:
You can cancel your order within $session.params.cancel-period days. Goodbye.
- 点击保存。
- 关闭路线面板。
在模拟器中测试代理
您的聊天机器人和网络钩子已准备好使用模拟器进行测试:
- 点击测试代理。
- 输入
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 响应中设置的参数。 |