Crear un webhook

En esta guía se explica cómo usar un webhook para que tu agente sea más dinámico. Cloud Functions se usa para alojar el webhook debido a su sencillez, 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 tendrás que editar el código de esta guía.

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

  • Lee los valores de los parámetros de 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 empezar

Si no tienes previsto usar webhooks, puedes saltarte esta guía de inicio rápido.

Antes de leer esta guía, debes hacer lo siguiente:

  1. Consulta los conceptos básicos de los flujos.
  2. Sigue los pasos de configuración.
  3. Sigue los pasos de la guía de inicio rápido Crear un agente con flujos. Los pasos que se indican a continuación se refieren al mismo agente. Si ya no tienes ese agente, puedes descargarlo y restaurarlo.

Crear la función de Cloud

Las funciones de Cloud Functions se pueden crear con la consola de Google Cloud (consulta la documentación o abre la consola). Para crear una función para esta guía, sigue estos pasos:

  1. Es importante que tu agente de Conversational Agents (Dialogflow CX) y la función estén en el mismo proyecto. Esta es la forma más sencilla de que los agentes conversacionales (Dialogflow CX) tengan acceso seguro a tu función. Para seleccionar tu proyecto, ve al selector de proyectos.
  2. Ve a la página de información general de Cloud Functions.
  3. Haz clic en Crear función y define los siguientes campos:
    • Entorno: 1.ª gen.
    • Nombre de la función: shirts-agent-webhook
    • Región: si has especificado una región para tu agente, usa la misma.
    • Tipo de activador HTTP: HTTP
    • URL: haz clic en el botón de copiar y guarda el valor. Necesitarás esta URL al configurar el webhook.
    • Autenticación: requiere autenticación
    • Requerir HTTPS: marcada
  4. Haz clic en Guardar.
  5. Haz clic en Siguiente (no necesitas ajustes especiales de tiempo de ejecución, compilación, conexiones ni seguridad).
  6. Define los siguientes campos:
    • Tiempo de ejecución: selecciona el tiempo de ejecución de Go más reciente.
    • Código fuente: editor insertado
    • Punto de entrada: HandleWebhookRequest

  7. Sustituye el código por el 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 Desplegar.

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

Crear el webhook

Ahora que el webhook existe como función de Cloud, lo asociará a su agente. Para crear el webhook de tu agente, sigue estos pasos:

  1. Abre la consola de Dialogflow CX.
  2. Elige tu proyecto de Google Cloud.
  3. Selecciona tu agente.
  4. Selecciona la pestaña Gestionar.
  5. Haz clic en Webhooks.
  6. Haz clic en Crear.
  7. Rellena los siguientes campos:
    • Nombre visible: shirts-agent-webhook
    • URL del webhook: proporciona la URL del webhook que guardaste al crear la función.
    • Subtipo: estándar.
    • El resto de los campos usan valores predeterminados.
  8. Haz clic en Guardar.

Usar el webhook

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

  1. Selecciona la pestaña Crear.
  2. Haz clic en la página Confirmación del pedido para desplegarla en el gráfico del creador de agentes.
  3. Haz clic en el campo Entry Fulfillment (Procesamiento de la entrada) de la página para abrir el panel de procesamiento.
  4. Elimina la respuesta de texto que aparece en el encabezado El agente dice. Cuando coloques el cursor sobre el texto, aparecerá el botón eliminar .
  5. Haz clic en Habilitar webhook.
  6. Selecciona la opción shirts-agent-webhook en el menú desplegable Webhook.
  7. Escribe confirm en el campo Etiqueta.
  8. Haz clic en Guardar.
  9. Cierra el panel de procesamiento.

Captura de pantalla del gráfico de agentes

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

  1. Haga clic en la condición de la ruta que se muestra con una condición true para abrir el panel de ruta.
  2. Desplázate hacia abajo hasta la sección Cumplimiento del panel de ruta y añade la siguiente respuesta de texto en el 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 de agentes

Probar el agente en el simulador

Tu agente y tu webhook están listos para probarse con el simulador:

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

Como ha proporcionado tanto la talla como el color, el agente tiene todo lo que necesita para crear un pedido de una camiseta, por lo que pasa directamente a la página Confirmación del pedido.

Captura de pantalla del gráfico de agentes

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

Respuesta Explicación
Vale, vamos a iniciar un nuevo pedido. Cuando se activó la página Nuevo pedido, se llamó a la función de cumplimiento de la entrada. La respuesta se ha activado a partir de este cumplimiento.
Has seleccionado una camiseta roja de talla grande. Cuando se hayan proporcionado todos los parámetros del formulario de la página Nuevo pedido, se llamará a la ruta de condición que comprueba si se ha completado el formulario. La respuesta se ha activado desde el cumplimiento de esta ruta. Esta ruta también lleva a la página Confirmación del pedido.
Puedes recoger tu pedido de una camiseta roja grande en 5 días. La 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 tu pedido en un plazo de 2 días. Goodbye. La página Confirmación del pedido tiene una ruta de condición con una condición que siempre es verdadera. Esta respuesta se activa mediante el cumplimiento de esa ruta. Ten en cuenta que la respuesta usa el parámetro definido por el webhook en la respuesta del webhook.
Anterior
Crear un agente con flujos
Siguiente
Interacciones con una integración