Créer un webhook

Ce guide vous explique comment utiliser un webhook pour rendre votre agent plus dynamique. Cloud Functions est utilisé pour 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 utilise également le langage de programmation Go, mais vous pouvez utiliser n'importe quel langage compatible avec Cloud Functions. Vous n'aurez pas besoin de modifier le code pour 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. Découvrez les principes de base des flux.
2. Effectuez la procédure de configuration.
3. Suivez les étapes du guide de démarrage rapide Créer un agent à l'aide de flux. 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 Cloud Functions avec la console Google Cloud (accéder à la documentation, ouvrir la console). Pour créer une fonction pour ce guide :

1. Il est important que votre agent Dialogflow CX et la fonction se trouvent dans le même projet. C'est le moyen le plus simple pour Dialogflow CX d'accéder de manière sécurisée à votre fonction. Pour sélectionner votre projet, accédez au sélecteur de projet.
2. Accédez à la page Présentation de Cloud Functions.
3. Cliquez sur Créer une fonction, puis définissez les champs suivants :
   • Environnement : 1re génération
   • Nom de la fonction : shirts-agent-webhook
   • Région : si vous avez spécifié une région pour votre agent, utilisez la même région.
   • Type de déclencheur HTTP : HTTP
   • URL : cliquez sur le bouton de copie, puis enregistrez la valeur. Vous en aurez besoin pour configurer le webhook.
   • Authentification : exiger l'authentification
   • Exiger HTTPS : coché
4. Cliquez sur Enregistrer.
5. Cliquez sur Suivant (vous n'avez pas besoin de paramètres d'exécution, de compilation, de connexion ou de sécurité spéciaux).
6. Renseignez les champs ci-dessous comme suit :
   • 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 le suivant :

   // 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]any `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]any{"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 de 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 de votre agent :

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. Remplissez les champs suivants :
   • Nom à afficher : shirts-agent-webhook
   • URL du webhook : indiquez l'URL du 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 Order Confirmation (Confirmation de commande) comporte un fulfillment d'entrée, qui dispose actuellement d'une réponse textuelle statique. Pour mettre à jour le fulfillment afin d'utiliser votre webhook :

1. Sélectionnez l'onglet Compilation.
2. Cliquez sur la page Order Confirmation pour la développer dans le graphique du générateur d'agent.
3. Cliquez sur le champ Fulfillment de la saisie sur la page pour ouvrir le panneau de fulfillment.
4. Supprimez la réponse textuelle existante sous l'en-tête Agent says (L'agent dit). Lorsque vous pointez sur le texte, le bouton Supprimer  s'affiche.
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.

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

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

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é une taille et une couleur, vous avez fourni à l'agent toutes les informations dont il a besoin pour créer une commande de t-shirt. Il passe donc directement à la page Order Confirmation (Confirmation de commande).

Voici les réponses de l'agent :

Réponse	Explication
OK, commençons une nouvelle commande.	Lorsque la page New Order (Nouvelle commande) est devenue active, le fulfillment d'entrée a été appelé. La réponse a été déclenchée à partir de ce fulfillment.
Vous avez sélectionné un t-shirt rouge en taille L.	Une fois que tous les paramètres de formulaire ont été fournis pour la page New Order (Nouvelle commande), la route de condition vérifiant que le formulaire est complet est appelée. La réponse a été déclenchée à partir du fulfillment pour ce routage. Cette route passe également à la page Order Confirmation (Confirmation de commande).
Vous pourrez récupérer votre commande de t-shirt rouge en taille L dans cinq jours.	Le fulfillment d'entrée de la page Order Confirmation (Confirmation de 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 Order Confirmation (Confirmation de commande) comporte une route de condition dont la condition est toujours vraie. Cette réponse est déclenchée par le fulfillment de cette route. Notez que la réponse utilise le paramètre défini par le webhook dans la réponse du webhook.