Kurzanleitung: Webhook erstellen

In dieser Anleitung erfahren Sie, wie Sie einen Webhook verwenden, um einen dynamischeren Agent zu ermöglichen. Der Einfachheit halber wird der Webhook in Cloud Functions gehostet. Es gibt jedoch noch viele andere Möglichkeiten, einen Webhook-Dienst zu hosten. In diesem Beispiel wird auch die Programmiersprache Go verwendet. Sie können jedoch jede von Cloud Functions unterstützte Sprache verwenden. Sie müssen den Code für diese Anleitung nicht bearbeiten.

Mit dem Webhook-Beispielcode wird Folgendes ausgeführt:

  • Liest Parameterwerte aus der Webhook-Anfrage.
  • Schreibt einen Parameterwert in die Webhook-Antwort.
  • Liefert eine Textantwort in der Webhook-Antwort.

Hinweise

Wenn Sie keine Webhooks verwenden möchten, können Sie diese Kurzanleitung überspringen.

Bevor Sie diese Anleitung lesen, sollten Sie mit Folgendem vertraut sein:

  1. Dialogflow CX-Grundlagen
  2. Einrichtungsschritte ausführen
  3. Die Schritte in der Kurzanleitung Agent erstellen ausführen. In den folgenden Schritten wird derselbe Agent weiterverwendet. Wenn Sie diesen Agent nicht mehr haben, können Sie den Agent herunterladen und wiederherstellen.

Cloud Functions-Funktion erstellen

Cloud Functions-Funktionen können mit der Google Cloud Console erstellt werden (Dokumentation ansehen, Konsole öffnen). So erstellen Sie eine Funktion für diesen Leitfaden:

  1. Der Dialogflow-Agent und die Funktion müssen sich im selben Projekt befinden. Dies ist die einfachste Möglichkeit für Dialogflow, einen sicheren Zugriff auf die Funktion zu erhalten. Rufen Sie die Projektauswahl auf, um Ihr Projekt auszuwählen.
  2. Rufen Sie die Cloud Functions-Übersichtsseite auf.
  3. Klicken Sie auf Funktion erstellen und legen Sie die folgenden Felder fest:
    • Umgebung: 1. Generation
    • Funktionsname: shirts-agent-webhook
    • Region: Wenn Sie eine Region für Ihren Agent angegeben haben, verwenden Sie dieselbe Region.
    • HTTP-Triggertyp: HTTP
    • URL: Klicken Sie hier auf die Schaltfläche zum Kopieren und speichern Sie den Wert. Sie benötigen diese URL zum Konfigurieren des Webhooks.
    • Authentifizierung: Authentifizierung erforderlich
    • Require HTTPS (HTTPS erforderlich): aktiviert
  4. Klicken Sie auf Speichern.
  5. Klicken Sie auf Weiter. Sie benötigen keine spezielle Laufzeit, keinen Build, keine Verbindungen oder Sicherheitseinstellungen.
  6. Legen Sie die folgenden Felder fest:
    • Laufzeit: Wählen Sie die neueste Go-Laufzeit aus.
    • Quellcode: Inline-Editor
    • Einstiegspunkt: HandleWebhookRequest
  7. Ersetzen Sie den Code durch Folgendes: 
    // 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. Klicken Sie auf Bereitstellen.
  9. Warten Sie, bis die Statusanzeige anzeigt, dass die Funktion erfolgreich bereitgestellt wurde. Während Sie warten, sehen Sie sich den gerade bereitgestellten Code an. Codekommentare enthalten wichtige Details.

Webhook erstellen

Da der Webhook jetzt als Cloud Functions-Funktion vorhanden ist, verknüpfen Sie ihn mit Ihrem Agent. So erstellen Sie den Webhook für Ihren Agent:

  1. Öffnen Sie die Dialogflow CX Console.
  2. Wählen Sie Ihr Google Cloud-Projekt aus.
  3. Wählen Sie den Agent aus.
  4. Wählen Sie den Tab Verwalten.
  5. Klicken Sie auf Webhooks.
  6. Klicken Sie auf Erstellen.
  7. Füllen Sie die folgenden Felder aus:
    • Anzeigename: shirts-agent-webhook
    • Webhook-URL: Geben Sie die Webhook-URL an, die Sie beim Erstellen der Funktion gespeichert haben.
    • Subtyp: Standard.
    • Für alle anderen Felder werden Standardwerte verwendet.
  8. Klicken Sie auf Speichern.

Webhook verwenden

Da der Webhook jetzt für den Agent verfügbar ist, können Sie ihn in der Auftragsausführung verwenden. Die Seite Bestellbestätigung enthält eine Eingabeausführung, die derzeit eine statische Textantwort enthält. So aktualisieren Sie die Auftragsausführung für die Verwendung Ihres Webhooks:

  1. Wählen Sie den Tab Build aus.
  2. Klicken Sie auf die Seite Bestellbestätigung, um die Seite in der Agent-Builder-Grafik zu maximieren.
  3. Klicken Sie auf der Seite auf das Feld Entry Fulfillment (Auftragsausführung), um den Bereich für die Auftragsausführung zu öffnen.
  4. Löschen Sie die vorhandene Textantwort unter der Überschrift Agent sagt. Wenn Sie den Mauszeiger auf den Text bewegen, wird die Schaltfläche zum Löschen angezeigt.
  5. Klicken Sie auf Webhook aktivieren.
  6. Wählen Sie im Drop-down-Menü Webhook die Option shirts-agent-webhook aus.
  7. Geben Sie in das Feld Tag den Wert confirm ein.
  8. Klicken Sie auf Speichern.
  9. Schließen Sie den Bereich für die Auftragsausführung.

Screenshot von der Agent-Grafik

Der bereitgestellte Webhook-Code sendet eine Antwort, die einen Parameter mit dem Namen cancel-period erstellt. Aktualisieren Sie den Agent so, dass er in der endgültigen Antwort des Agents auf derselben Seite Bestellbestätigung auf diesen Parameter verweist:

  1. Klicken Sie auf die Bedingung Route mit der Bedingung true, um den Bereich „Routen“ zu öffnen.
  2. Scrollen Sie im Feld „Route“ nach unten zum Abschnitt Fulfillment (Auftragsausführung) und fügen Sie unter der Überschrift Agent sagt die folgende Textantwort hinzu: You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Klicken Sie auf Speichern.
  4. Schließen Sie das Routenfeld.

Screenshot von der Agent-Grafik

Agent im Simulator testen

Ihr Agent und der Webhook können jetzt mit dem Simulator getestet werden:

  1. Klicken Sie auf Test Agent (Agent testen).
  2. Geben Sie I want to buy a large red shirt ein und drücken Sie die Eingabetaste.

Da Sie sowohl eine Größe als auch eine Farbe angegeben haben, haben Sie dem Agenten alles gegeben, was er zum Erstellen einer T-Shirt-Bestellung benötigt. Daher wechselt er direkt zur Seite Bestellbestätigung.

Screenshot von der Agent-Grafik

Im Folgenden werden die Agent-Antworten beschrieben:

Antwort Erklärung
Ok, lass uns eine neue Bestellung aufgeben. Als die Seite Neuer Auftrag aktiviert wurde, wurde die Auftragsausführung aufgerufen. Die Antwort wurde von dieser Auftragsausführung ausgelöst.
Sie haben ein rotes T-Shirt Größe L ausgewählt. Wenn alle Formularparameter für die Seite Neuer Auftrag angegeben wurden, wird die Prüfung der Bedingungsroute für das Ausfüllen des Formulars aufgerufen. Die Antwort wurde von der Auftragsausführung für diese Route ausgelöst. Diese Weiterleitung wechselt auch zur Seite Bestellbestätigung.
Du kannst deine Bestellung für ein rotes Hemd in 5 Tagen abholen. Die Auftragsausführung auf der Seite Bestellbestätigung ruft den Webhook auf. Siehe die Funktion confirm im Webhook-Code. Diese Funktion erstellt die Textantwort und verwendet die in der Webhook-Anfrage angegebenen Parameter.
Sie können Ihre Bestellung innerhalb von zwei Tagen stornieren. Auf Wiedersehen. Auf der Seite Bestellbestätigung finden Sie eine Bedingungsroute mit einer Bedingung, die immer wahr ist. Diese Antwort wird von der Auftragsausführung für diese Route ausgelöst. Die Antwort verwendet den Parameter, der vom Webhook in der Webhook-Antwort festgelegt wurde.
Zurück
Agent erstellen
Weiter
Interaktionen mit einer Einbindung