Guía de inicio rápido: Crea un webhook

En esta guía, se muestra cómo usar una webhook, para que tu agente sea más dinámico. Cloud Functions se usan para alojar el webhook debido a su simplicidad, pero hay muchas otras formas de alojar un servicio de webhook. En el ejemplo, también se usa el lenguaje de programación Go, pero puedes usar cualquier lenguaje compatible con Cloud Functions. No es necesario que edites el código para esta guía.

El código de webhook de ejemplo hace lo siguiente:

  • Lee valores de parámetros desde la solicitud de webhook.
  • Escribe un valor de parámetro en la respuesta del webhook.
  • Proporciona una respuesta de texto en la respuesta del webhook.

Antes de comenzar

Si no planeas usar webhooks, puedes omitir esta guía de inicio rápido.

Debes hacer lo siguiente antes de leer esta guía:

  1. Lee los conceptos básicos de Dialogflow CX.
  2. Realiza los pasos de configuración.
  3. Realiza los pasos de la guía de inicio rápido Compila un agente. Los siguientes pasos continúan el trabajo en el mismo agente. Si ya no tienes ese agente, puedes descargar el agente y restablecerlo.

Crea la Cloud Function

Puedes crear funciones de Cloud con la consola de Google Cloud (consultar la documentación, abrir la consola). Para crear una función para esta guía, sigue estos pasos:

  1. Es importante que el agente de Dialogflow CX y la función se encuentren en el mismo proyecto. Esta es la forma más sencilla de tener acceso seguro a tu función. Para seleccionar tu proyecto, ve al selector de proyectos.
  2. Ve a la página Descripción general de Cloud Functions.
  3. Haz clic en Crear función y establece los siguientes campos:
    • Entorno: 1a gen.
    • Nombre de la función: shirts-agent-webhook
    • Región: si especificaste una región para el agente, usan la misma región.
    • Tipo de activador HTTP: HTTP
    • URL: Haz clic en el botón Copiar aquí y guarda el valor. Necesitarás esta URL cuando configures el webhook.
    • Autenticación: requiere autenticación
    • Solicitar HTTPS: marcado
  4. Haz clic en Guardar.
  5. Haz clic en Siguiente (no necesitas un entorno de ejecución, una compilación, conexiones ni una configuración de seguridad especiales).
  6. Configura los siguientes campos:
    • Entorno de ejecución: Selecciona el entorno de ejecución de Go más reciente.
    • Código fuente: Editor intercalado
    • Punto de entrada: HandleWebhookRequest
  7. Reemplaza el código por lo siguiente:

    // 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. Haz clic en Implementar.

  9. Espera hasta que el indicador de estado muestre que la función se implementó correctamente. Mientras esperas, examina el código que acabas de implementar. Los comentarios de código describen detalles importantes.

Crea el webhook

Ahora que el webhook existe como una Cloud Function, asociarás este webhook con tu agente. A fin de crear el webhook para tu agente, sigue estos pasos:

  1. Abre la consola de Dialogflow CX.
  2. Elige tu proyecto de Google Cloud.
  3. Selecciona el agente.
  4. Selecciona la pestaña Administrar.
  5. Haz clic en Webhooks.
  6. Haz clic en Crear.
  7. Completa los siguientes campos:
    • Nombre visible: shirts-agent-webhook
    • URL de webhook: Proporciona la URL de webhook que guardaste. cuando crees la función.
    • Subtipo: Estándar.
    • Todos los demás campos usan valores predeterminados.
  8. Haz clic en Guardar.

Usa el webhook

Ahora que el webhook está disponible para el agente usarás el webhook en entrega. La página Confirmación de pedido tiene una entrega de entrada. que actualmente tiene una respuesta de texto estática. Para actualizar la entrega para usar tu webhook, sigue estos pasos:

  1. Selecciona la pestaña Build.
  2. Haz clic en la página Confirmación de pedido para expandirla. en el gráfico del compilador del agente.
  3. Haz clic en el campo Entry Fulfillment en la página. para abrir el panel de entrega.
  4. Borra la respuesta de texto existente debajo del encabezado El agente dice. Cuando colocas el cursor sobre el texto, aparece el botón para borrar .
  5. Haz clic en Habilitar webhook.
  6. Selecciona la opción shirts-agent-webhook. en el menú desplegable Webhook.
  7. Ingresa confirm en el campo Etiqueta.
  8. Haz clic en Guardar.
  9. Cierra el panel de entrega.

Captura de pantalla del gráfico del agente

El código del webhook implementado envía una respuesta que crea un parámetro llamado cancel-period. Actualiza el agente para hacer referencia a este parámetro en la respuesta final del agente. para la misma página de Confirmación de pedido:

  1. Haz clic en la condición. ruta se muestra con una condición true para abrir el panel de ruta.
  2. Desplázate hacia abajo hasta la sección Fulfillment en el panel de ruta. Luego, agrega la siguiente respuesta de texto debajo del encabezado El agente dice: You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Haz clic en Guardar.
  4. Cierra el panel de ruta.

Captura de pantalla del gráfico del agente

Prueba el agente en el simulador

Tu agente y webhook están listos para que los puedas probar con el simulador:

  1. Haz clic en Probar agente.
  2. Ingresa I want to buy a large red shirt y presiona Intro.

Como proporcionaste un tamaño y un color, le diste al agente todo lo necesario para crear un pedido de camisas, para que se transfiera directamente a la página de Confirmación de pedido.

Captura de pantalla del gráfico del agente

A continuación, se describen las respuestas del agente:

Respuesta Explicación
Comencemos un nuevo pedido. Cuando la página New Order se activó, se llamó a la entrega de entrada. La respuesta se activó desde esta entrega.
Seleccionaste una camisa roja grande. Cuando se proporcionan todos los parámetros del formulario para la página New Order, se llama a la verificación de la ruta de condición para el completado del formulario. La respuesta se activó desde la entrega de esta ruta. Esta ruta también pasa a la página Confirmación de pedido.
Puedes retirar tu pedido de una camisa roja grande en 5 días. La entrega de entrada de la página Confirmación del pedido llama al webhook. Consulta la función confirm en el código del webhook. Esa función crea esta respuesta de texto y usa los parámetros proporcionados en la solicitud de webhook.
Puedes cancelar el pedido en un plazo de 2 días. Adiós. La página Confirmación de pedido tiene una ruta de condición con una condición que siempre es verdadera. La entrega de esa ruta activa esta respuesta. Ten en cuenta que la respuesta usa el parámetro configurado por el webhook en la respuesta del webhook.