Créer un service de webhook

L'agent prédéfini que vous avez créé à l'étape précédente nécessite un webhook. Dans ce tutoriel, nous utilisons des fonctions Cloud Run pour héberger le webhook en raison de leur 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 les fonctions Cloud Run.

Créer la fonction

Vous pouvez créer des fonctions Cloud Run avec la console Google Cloud (consulter la documentation, ouvrir la console). Pour créer une fonction pour ce tutoriel:

  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'accéder de manière sécurisée à votre fonction. Avant de créer la fonction, sélectionnez votre projet dans la console Google Cloud .

    Accéder au sélecteur de projet

  2. Ouvrez la page de présentation de Cloud Run Functions.

    Accéder à la présentation des fonctions Cloud Run

  3. Cliquez sur Créer une fonction, puis définissez les champs suivants:

    • Environnement: 1re génération
    • Nom de la fonction: tutorial-telecommunications-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 et enregistrez la valeur. Vous en aurez besoin lors de la configuration du webhook.
    • Authentification: exigez l'authentification.
    • Nécessite le protocole HTTPS: cochez cette case.

  4. Cliquez sur Enregistrer.

  5. Cliquez sur Suivant (vous n'avez pas besoin de paramètres d'exécution, de compilation, de connexion ni de sécurité spéciaux).

  6. Attribuez aux champs suivants les valeurs correspondantes :

    • 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 cxtwh

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"

	"cloud.google.com/go/spanner"
  "google.golang.org/grpc/codes"
)

// client is a Spanner client, created only once to avoid creation
// for every request.
// See: https://cloud.google.com/functions/docs/concepts/go-runtime#one-time_initialization
var client *spanner.Client

func init() {
	// If using a database, these environment variables will be set.
	pid := os.Getenv("PROJECT_ID")
	iid := os.Getenv("SPANNER_INSTANCE_ID")
	did := os.Getenv("SPANNER_DATABASE_ID")
	if pid != "" && iid != "" && did != "" {
		db := fmt.Sprintf("projects/%s/instances/%s/databases/%s",
			pid, iid, did)
		log.Printf("Creating Spanner client for %s", db)
		var err error
		// Use the background context when creating the client,
		// but use the request context for calls to the client.
		// See: https://cloud.google.com/functions/docs/concepts/go-runtime#contextcontext
		client, err = spanner.NewClient(context.Background(), db)
		if err != nil {
			log.Fatalf("spanner.NewClient: %v", err)
		}
	}
}

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"`
}

// detectCustomerAnomaly handles same-named tag.
func detectCustomerAnomaly(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"anomaly_detect":        "false",
		"purchase":              "device protection",
		"purchase_amount":       "12.25",
		"bill_without_purchase": "54.34",
		"total_bill":            "66.59",
		"first_month":           "January 1",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// validatePhoneLine handles same-named tag.
func validatePhoneLine(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"domestic_coverage":   "true",
		"phone_line_verified": "true",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// cruisePlanCoverage handles same-named tag.
func cruisePlanCoverage(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Get the existing parameter values
	port := request.SessionInfo.Parameters["destination"].(string)
	port = strings.ToLower(port)
	// Check if the port is covered
	covered := "false"
	if client != nil {
		// A Spanner client exists, so access the database.
		// See: https://pkg.go.dev/cloud.google.com/go/spanner#ReadOnlyTransaction.ReadRow
		row, err := client.Single().ReadRow(ctx,
			"Destinations",
			spanner.Key{port},
			[]string{"Covered"})
		if err != nil {
			if spanner.ErrCode(err) == codes.NotFound {
				log.Printf("Port %s not found", port)
			} else {
				return webhookResponse{}, err
			}
		} else {
			// A row was returned, so check the value
			var c bool
			err := row.Column(0, &c)
			if err != nil {
				return webhookResponse{}, err
			}
			if c {
				covered = "true"
			}
		}
	} else {
		// No Spanner client exists, so use hardcoded list of ports.
		coveredPorts := map[string]bool{
			"anguilla": true,
			"canada":   true,
			"mexico":   true,
		}
		_, ok := coveredPorts[port]
		if ok {
			covered = "true"
		}
	}
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"port_is_covered": covered,
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// internationalCoverage handles same-named tag.
func internationalCoverage(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Get the existing parameter values
	destination := request.SessionInfo.Parameters["destination"].(string)
	destination = strings.ToLower(destination)
	// Hardcoded list of covered international monthly destinations
	coveredMonthly := map[string]bool{
		"anguilla":  true,
		"australia": true,
		"brazil":    true,
		"canada":    true,
		"chile":     true,
		"england":   true,
		"france":    true,
		"india":     true,
		"japan":     true,
		"mexico":    true,
		"singapore": true,
	}
	// Hardcoded list of covered international daily destinations
	coveredDaily := map[string]bool{
		"brazil":    true,
		"canada":    true,
		"chile":     true,
		"england":   true,
		"france":    true,
		"india":     true,
		"japan":     true,
		"mexico":    true,
		"singapore": true,
	}
	// Check coverage
	coverage := "neither"
	_, monthly := coveredMonthly[destination]
	_, daily := coveredDaily[destination]
	if monthly && daily {
		coverage = "both"
	} else if monthly {
		coverage = "monthly_only"
	} else if daily {
		coverage = "daily_only"
	}
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"coverage": coverage,
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// cheapestPlan handles same-named tag.
func cheapestPlan(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"monthly_cost":   70,
		"daily_cost":     100,
		"suggested_plan": "monthly",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// Define a type for handler functions.
type handlerFn func(ctx context.Context, request webhookRequest) (
	webhookResponse, error)

// Create a map from tag to handler function.
var handlers map[string]handlerFn = map[string]handlerFn{
	"detectCustomerAnomaly": detectCustomerAnomaly,
	"validatePhoneLine":     validatePhoneLine,
	"cruisePlanCoverage":    cruisePlanCoverage,
	"internationalCoverage": internationalCoverage,
	"cheapestPlan":          cheapestPlan,
}

// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
	log.Printf("ERROR: %v", err)
	http.Error(w,
		fmt.Sprintf("ERROR: %v", err),
		http.StatusInternalServerError)
}

// 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.
	tag := request.FulfillmentInfo.Tag
	if fn, ok := handlers[tag]; ok {
		response, err = fn(r.Context(), request)
	} else {
		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. Pendant que vous attendez, examinez le code que vous venez de déployer.

Configurer le webhook de votre agent

Maintenant que le webhook existe en tant que service, vous allez l'associer à votre agent. Pour configurer 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 le webhook existant (créé par l'agent prédéfini).
  7. Remplacez l'URL du webhook par l'URL du webhook que vous avez enregistrée lors de la création de la fonction.
  8. Définissez Sous-type sur "Standard".
  9. Cliquez sur Enregistrer.

Essayer l'agent

Votre agent est maintenant prêt à être testé. Cliquez sur le bouton Tester l'agent pour ouvrir le simulateur. Essayez de tenir la conversation suivante avec l'agent:

Tour de parole Vous Agent
1 Bonjour, Bonjour ! Je suis l'agent virtuel des télécommunications. Je peux vous aider à résoudre vos problèmes de facturation et de forfait, à résoudre des problèmes et à ajouter des projets de voyage et de croisière. Que puis-je faire pour vous ?
2 Je souhaite ajouter un plan de croisière Laissez-moi y jeter un œil. Quel est votre numéro de téléphone chez nous ?
3 123-123-1234 Combien de jours dure votre croisière ?
4 7 L'option 1 inclut les appels et les SMS. Le prix est de [XX] $ par jour. Pour en savoir plus, consultez [URL]. L'option 2 inclut les appels, les SMS et les données. Le prix est de [XX] $ par jour. Pour en savoir plus, consultez [URL]. Quel forfait de croisière souhaitez-vous ajouter ?
5 Option 1 OK. J'ai ajouté ce forfait à votre compte. Pendant votre croisière, vous aurez peut-être également besoin d'une couverture à terre. Dans quel port allez-vous vous arrêter ?
6 Mexique Combien de jours y passerez-vous ?
7 3 Bonne nouvelle ! Le Mexique bénéficie d'une couverture gratuite sur le territoire. C’est terminé ! Y a-t-il autre chose que je puisse faire pour vous aujourd'hui ?

Cette conversation a été gérée par le flux Cruise Plan.

Au cours du sixième tour de conversation, vous avez indiqué "Mexique" comme port de destination. Le port de destination et le nombre de jours y sont capturés en tant que paramètres de formulaire destination et trip_duration de la page Collect Port. Parcourez votre agent pour trouver ces définitions de paramètres.

Capture d'écran de la page "Collect Port" (Port de collecte) dans la console Dialogflow

Sur la page Collect Port, il existe une route de condition pour le remplissage du formulaire : $page.params.status = "FINAL". Une fois les deux paramètres de formulaire fournis, cette route est appelée. Ce parcours appelle votre webhook et fournit la balise cruisePlanCoverage à votre webhook. Si vous examinez le code du webhook ci-dessus, vous constaterez que cette balise déclenche l'appel de la fonction du même nom.

Cette fonction détermine si la destination fournie est couverte par le plan. La fonction vérifie si des variables d'environnement spécifiques sont définies avec des informations permettant de se connecter à la base de données. Si ces variables d'environnement ne sont pas définies, la fonction utilise une liste de destinations codée en dur. Dans les étapes suivantes, vous allez modifier l'environnement de la fonction afin qu'elle récupère des données à partir d'une base de données afin de valider la couverture du plan pour les destinations.

Dépannage

Le code du webhook inclut des instructions de journalisation. En cas de problème, essayez d'afficher les journaux de votre fonction.

En savoir plus

Pour en savoir plus sur les étapes ci-dessus, consultez les ressources suivantes:

Précédent
Créer un agent prédéfini
Suivant
Interroger une base de données