Créer un webhook

Ce guide vous explique comment utiliser un webhook pour que votre agent soit 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 quelle le langage compatible avec Cloud Functions. Vous n'aurez pas besoin 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 des 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 Flow.
  2. Effectuez la procédure de configuration.
  3. Effectuez les étapes du Créer un agent à l'aide de flux de démarrage rapide. Les étapes ci-dessous continuent d'utiliser le même agent. Si vous n'avez plus cet agent, vous pouvez télécharger l'agent et le restaurer.

Créer la fonction Cloud

Vous pouvez créer des Cloud Functions avec 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 conversationnel (Dialogflow CX) et la fonction qui appartiennent tous deux au même projet. Il s'agit du moyen le plus simple pour les agents conversationnels (Dialogflow CX) d'avoir un accès sécurisé à votre fonction. Pour sélectionner votre projet, Accédez au sélecteur de projet.
  2. Accédez au Page de présentation de Cloud Functions
  3. Cliquez sur Créer une fonction et renseignez les champs suivants:
    • Environnement: 1re génération
    • Nom de la fonction : shirts-agent-webhook
    • Region (Région) : si vous avez spécifié une région pour votre agent, utilisent la même région.
    • Type de déclencheur HTTP : HTTP
    • URL : cliquez sur le bouton de copie ici et enregistrez la valeur. Vous aurez besoin de cette URL pour configurer le webhook.
    • Authentification : exigez l'authentification.
    • Exiger le protocole HTTPS: coché
  4. Cliquez sur Enregistrer.
  5. Cliquez sur Next (Suivant). Vous n'avez pas besoin d'un environnement d'exécution, d'une compilation connexions ou paramètres de sécurité).
  6. Renseignez les champs suivants: <ph type="x-smartling-placeholder">
      </ph>
    • 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 code 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]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 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 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. 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 des 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 traitement. La page Confirmation de la commande contient un traitement des entrées. qui contient actuellement une réponse textuelle statique. Pour modifier le traitement afin qu'il utilise votre webhook :

  1. Sélectionnez l'onglet Build (Compilation).
  2. Cliquez sur la page Confirmation de commande pour la développer dans le graphique du générateur d'agents.
  3. Cliquez sur le champ Entry Fulfillment (Traitement des entrées) 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  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.

Capture d&#39;écran du graphique de l&#39;agent

Le code du webhook déployé envoie une réponse qui crée un paramètre nommé cancel-period. Modifiez 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 Confirmation de commande :

  1. Cliquez sur la condition itinéraire affichée avec une condition true pour ouvrir le panneau "Itinéraire".
  2. Faites défiler la page jusqu'à la section Fulfillment du panneau de routage, 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 "Itinéraire".

Capture d&#39;écran du graphique de l&#39;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.

Puisque vous avez fourni à la fois une taille et une couleur, vous avez donné à l'agent tout ce dont il avait besoin pour créer une commande de chemises, La page de confirmation de commande s'affiche donc directement.

Capture d&#39;écran du graphique de l&#39;agent

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

Réponse Explication
OK, passons une nouvelle commande. Lorsque la page Nouvelle commande est devenue active, le traitement des entrées a été appelé. La réponse a été déclenchée à partir de ce fulfillment.
Vous avez sélectionné une grande chemise rouge. 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 à partir du fulfillment pour cette route. Cette route passe également à la page Confirmation de la commande.
Vous pouvez récupérer votre commande pour une chemise rouge en taille L dans cinq jours. Le fulfillment d'entrée pour la page Confirmation de commande appelle le webhook. Consultez la fonction confirm dans le code du webhook. La fonction crée cette réponse textuelle et utilise les paramètres fournis dans la requête webhook.
Vous pouvez annuler votre commande sous deux jours. Au revoir. La page Confirmation de la commande comporte une route de condition avec une condition toujours vraie. 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