Guide de démarrage rapide: Créer un webhook

Ce guide vous explique comment utiliser un webhook afin que votre agent puisse être plus dynamique. Cloud Functions permet d'héberger le webhook en raison de sa simplicité, mais il existe de nombreuses autres façons d'héberger un service de webhook. L'exemple fait également appel au langage de programmation Go, mais vous pouvez utiliser n'importe quel langage compatible avec Cloud Functions. Il n'est pas nécessaire de modifier le code de ce guide.

L'exemple de code de webhook effectue les opérations suivantes:

  • Lit les valeurs des paramètres à partir de la requête de webhook.
  • Écrit une valeur de paramètre dans la réponse du webhook.
  • Fournit une réponse textuelle dans la réponse du webhook.

Avant de commencer

Si vous ne prévoyez pas d'utiliser de webhooks, vous pouvez ignorer ce guide de démarrage rapide.

Avant de lire ce guide, procédez comme suit :

  1. Consultez les principes de base de Dialogflow CX.
  2. Effectuez la procédure de configuration.
  3. Suivez la procédure décrite dans le guide de démarrage rapide Créer un agent. Les étapes ci-dessous continuent d'utiliser le même agent. Si vous n'avez plus cet agent, vous pouvez le télécharger et le restaurer.

Créer la fonction Cloud

Vous pouvez créer des fonctions Cloud Functions à l'aide de la console Google Cloud (consulter la documentation, ouvrir la console). Pour créer une fonction pour ce guide:

  1. Il est important que votre agent Dialogflow et la fonction se trouvent dans le même projet. Il s'agit du moyen le plus simple pour Dialogflow d'avoir un accès sécurisé à votre fonction. Pour sélectionner votre projet, accédez au sélecteur de projet.
  2. Accédez à la page de présentation de Cloud Functions.
  3. Cliquez sur Créer une fonction et définissez les champs suivants :
    • Environnement: 1re génération
    • Nom de la fonction: chemises-agent-webhook
    • Region (Région) : si vous avez spécifié une région pour votre agent, utilisez la même région.
    • HTTP Trigger type (Type de déclencheur HTTP) : HTTP
    • URL: cliquez sur le bouton "Copier" et enregistrez la valeur. Vous aurez besoin de cette URL pour configurer le webhook.
    • Authentification: requiert une authentification.
    • HTTPS requis: coché
  4. Cliquez sur Enregistrer.
  5. Cliquez sur Suivant. Vous n'avez pas besoin de paramètres d'exécution, de compilation, de connexions ou de sécurité spéciaux.
  6. Définissez les champs suivants :
    • Runtime (Environnement d'exécution) : sélectionnez le dernier environnement d'exécution Go.
    • Code source: éditeur intégré
    • Point d'entrée: HandleWebhookRequest
  7. Remplacez le code par ce qui suit: 
    // 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. Cliquez sur Déployer.
  9. Attendez que l'indicateur d'état indique que la fonction a bien été déployée. En attendant, examinez le code que vous venez de déployer. Les commentaires dans le code décrivent des détails importants.

Créer le webhook

Maintenant que le webhook existe en tant que fonction Cloud, vous allez l'associer à votre agent. Pour créer le webhook pour votre agent, procédez comme suit:

  1. Ouvrez la console Dialogflow CX.
  2. Choisissez votre projet Google Cloud.
  3. Sélectionnez votre agent.
  4. Sélectionnez l'onglet Gérer.
  5. Cliquez sur Webhooks.
  6. Cliquez sur Créer.
  7. Renseignez les champs suivants :
    • Nom à afficher: chemises-agent-webhook
    • Webhook URL (URL de webhook) : indiquez l'URL de webhook que vous avez enregistrée lors de la création de la fonction.
    • Sous-type: Standard.
    • Tous les autres champs utilisent les valeurs par défaut.
  8. Cliquez sur Enregistrer.

Utiliser le webhook

Maintenant que le webhook est disponible pour l'agent, vous allez l'utiliser dans le fulfillment. La page Confirmation de la commande comporte un traitement d'entrée, qui comporte actuellement une réponse textuelle statique. Pour mettre à jour le fulfillment afin qu'il utilise votre webhook:

  1. Sélectionnez l'onglet Build (Compilation).
  2. Cliquez sur la page Confirmation de la commande pour développer la page dans le graphique du générateur d'agents.
  3. Cliquez sur le champ Entry Fulfillment (Fulfillment d'entrée) sur la page pour ouvrir le panneau de traitement.
  4. Supprimez la réponse textuelle existante sous l'en-tête L'agent dit. Lorsque vous pointez sur le texte, le bouton de suppression apparaît.
  5. Cliquez sur Activer le webhook.
  6. Sélectionnez l'option shirts-agent-webhook dans le menu déroulant Webhook.
  7. Saisissez confirm dans le champ Tag.
  8. Cliquez sur Enregistrer.
  9. Fermez le panneau de traitement.

Capture d'écran du graphique de l'agent

Le code de webhook déployé envoie une réponse qui crée un paramètre nommé cancel-period. Mettez à jour l'agent pour référencer ce paramètre dans la réponse finale de l'agent pour la même page Confirmation de la commande:

  1. Cliquez sur la condition route affichée avec la condition true pour ouvrir le panneau de routage.
  2. Faites défiler la page jusqu'à la section Fulfillment du panneau de routage, puis ajoutez la réponse textuelle suivante sous l'en-tête L'agent dit : You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Cliquez sur Enregistrer.
  4. Fermez le panneau de navigation.

Capture d'écran du graphique de l'agent

Tester l'agent dans le simulateur

Votre agent et votre webhook sont prêts à être testés avec le simulateur:

  1. Cliquez sur Tester l'agent.
  2. Saisissez I want to buy a large red shirt et appuyez sur Entrée.

Comme vous avez indiqué à la fois une taille et une couleur, vous avez fourni à l'agent tout ce dont il a besoin pour créer une commande de chemises. Il passe donc directement à la page Confirmation de commande.

Capture d'écran du graphique de l'agent

Voici la description des réponses de l'agent:

Réponse Explication
Très bien, commençons une nouvelle commande. Lorsque la page Nouvelle commande est devenue active, le traitement de l'entrée a été appelé. La réponse a été déclenchée à partir de ce traitement.
Vous avez sélectionné une chemise rouge en taille L. Lorsque tous les paramètres du formulaire ont été fournis pour la page Nouvelle commande, la vérification de l'itinéraire de condition pour le remplissage du formulaire est appelée. La réponse a été déclenchée par le fulfillment pour cette route. Cette procédure permet également d'accéder à la page de confirmation de commande.
Vous pourrez retirer votre commande d'une chemise rouge de grande taille dans cinq jours. Le traitement des entrées de la page Confirmation de la commande appelle le webhook. Consultez la fonction confirm dans le code du webhook. Cette fonction crée cette réponse textuelle et utilise les paramètres fournis dans la requête de webhook.
Vous pouvez annuler votre commande dans un délai de deux jours. Au revoir. La page Confirmation de commande présente une route de condition dont la condition est toujours "true". Cette réponse est déclenchée par le fulfillment pour cette route. Notez que la réponse utilise le paramètre défini par le webhook dans la réponse du webhook.
Précédent
Créer un agent
Suivant
Interactions avec une intégration