Webhooks

Webhooks sind Dienste, die Ihre Geschäftslogik hosten oder andere Dienste anrufen. Während einer Sitzung können Sie mit Webhooks die Daten verwenden, die Dialogflow per Natural Language Processing extrahiert hat, um dynamische Antworten zu generieren, erfasste Daten zu validieren oder Aktionen im Backend auszulösen.

Ein Webhook kann entweder ein Standard-Webhook oder ein flexibler Webhook sein. Mit einem Standard-Webhook Die Anfrage- und Antwortfelder werden von Dialogflow definiert. Mit einem flexiblen Webhook die Anfrage- und Antwortfelder.

Standard-Webhooks

Bei Standard-Webhooks verwenden Sie von Dialogflow definierte Anfrage- und Antwortnachrichten. Die Anfragenachricht enthält viele Details zur Sitzung. z. B. „Aktuelle aktive Seite“, „Zuletzt zugeordnet“-Intent, Sitzungsparameterwerte und agent-definierte Antworten sind enthalten.

Standard-Webhook-Anfrage

Wenn eine Auftragsausführung mit einem Webhook aufgerufen wird, sendet Dialogflow eine HTTPS-POST-Webhook-Anfrage an Ihren Webhook-Dienst. Der Text dieser Anfrage ist ein WebhookRequest-JSON-Objekt mit Informationen zur Sitzung.

Einige Integrationen geben Sie in das Feld WebhookRequest.payload zusätzliche Informationen ein. Beispiel: Der Parameter Integration von Dialogflow CX-Telefonie-Gateway stellt die Anrufer-ID des Endnutzers bereit.

Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookRequest(V3) oder WebhookRequest(V3Beta1).

Standard-Webhook-Antwort

Sobald Ihr Webhook-Dienst eine Webhook-Anfrage empfängt, muss er eine Webhook-Antwort senden. Für die Antwort gelten die folgenden Einschränkungen:

  • Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
  • Die Antwort darf maximal 64 KiB groß sein.

Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookResponse(V3) oder WebhookResponse(V3Beta1).

Standardeinstellungen für Webhook-Ressourcen

Im Folgenden werden die Einstellungen für Webhook-Ressourcen für Standard-Webhooks beschrieben:

Begriff Definition
Anzeigename Der Name, der in der Konsole für den Webhook angezeigt wird.
Webhook-Zeitlimit Wenn Dialogflow eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es beim Warten auf eine Antwort zu einer Zeitüberschreitung kommen. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn eine Zeitüberschreitung auftritt, ruft Dialogflow ein webhook.error.timeout-Ereignis auf.
Typ Legen Sie Dienstverzeichnis fest, wenn Sie das Dienstverzeichnis für den privaten Netzwerkzugriff verwenden. Wählen Sie andernfalls Allgemeiner Webdienst aus.
Webhook-URL Geben Sie die URL-Adresse für den Webhook-Dienst an.
Subtyp Legen Sie Standard fest.
Umgebungsspezifischer Webhook Sie können umgebungsspezifische Webhooks bereitstellen.
Authentifizierung Weitere Informationen finden Sie im Abschnitt zur Authentifizierung.
Benutzerdefiniertes CA-Zertifikat Hiermit werden benutzerdefinierte CA-Zertifikate hochgeladen.

Flexible Webhooks

Mit flexiblen Webhooks definieren Sie die HTTP-Anfragemethode, die Anforderungs-URL-Parameter, der Anfrage- und Antwortnachrichten. Die Anfrage kann nur ausgewählte Parameterwerte bereitstellen, und in der Antwort können nur Werte für die Parameterüberschreibung angegeben werden. Diese Einschränkung ist tatsächlich vorteilhaft, da die Schnittstelle zwischen dem Agent und dem Webhook vereinfacht wird. Sie müssen nur selten etwas anderes kommunizieren, Sitzungsparameterwerten zwischen einem Agent und einem Webhook. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur das enthalten, was Sie brauchen, Außerdem können Sie für verschiedene Szenarien eindeutige Webhook-Nachrichten bereitstellen.

Flexible Webhook-Anfrage

Wenn Sie die Webhook-Ressource für den Agent erstellen, können Sie für Webhook-Anfragen Folgendes angeben:

  • Die für Webhook-Anfragen verwendete HTTP-Methode die an Ihren Webhook-Dienst gesendet wurden.
  • Sitzungsparameterwerte, die Dialogflow an den Webhook-Dienst senden soll mithilfe der URL.
  • Wenn Sie POST, PUT oder PATCH als Methode auswählen, können Sie Sitzungsparameterwerte angeben, über den JSON-Texttext der Anfrage an Ihren Webhook-Dienst senden sollte.

Um Sitzungsparameterwerte über die Anfrage-URL oder den JSON-Text zu senden, verwenden Sie Parameterverweise wie gewohnt. Für den Parameterverweis ist kein URL-Escapezeichen erforderlich. und der Verweis nicht in Anführungszeichen gesetzt wird. Während der Laufzeit Dialogflow maskiert den Parameterwert nach Bedarf mit einem URL-Escape. Eine Liste oder ein zusammengesetzter Wert wird im JSON-Format bereitgestellt.

Wenn Sie einen Parameterverweis im JSON-Text verwenden, müssen Sie den Verweis in Anführungszeichen setzen, unabhängig vom Typ des Parameters. Wenn der Parameter tatsächlich ein numerischer Skalarwert, Listenwert oder zusammengesetzter Wert ist, Dialogflow entfernt die Anführungszeichen, wenn die Anfrage zur Laufzeit gesendet wird um den Datentyp des Parameters beizubehalten. Skalartypen von Strings werden weiterhin in Anführungszeichen gesetzt. Wenn in einem Stringwert auf einen numerischen Skalar-, Listen- oder zusammengesetzten Wert verwiesen wird Beispiel: "Das ist eine Zahl: $session.params.size". wird der Parameter als String ("Dies ist eine Zahl: 3").

Beispiel: können Sie die Werte der Sitzungsparameter fruit und size an die Anfrage-URL anhängen:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

Fügen Sie in den JSON-Anfragetext Folgendes ein:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

Flexible Webhook-Antwort

Wenn Sie die Webhook-Ressource für den Agent erstellen, können Sie Sitzungsparameter angeben, die von Dialogflow festgelegt werden sollen. bestimmten Feldern der Webhook-Antwort zur Laufzeit hinzugefügt werden.

Für die Antwort gelten die folgenden Einschränkungen:

  • Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
  • Die Antwort darf maximal 64 KiB groß sein.

Verwenden Sie das folgende Format, um ein skalares, ein Listen- oder zusammengesetztes Feld anzugeben:

$.fully.qualified.path.to.field

Beispiel: Betrachten Sie die folgende JSON-Antwort:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Um den „Wert“ anzugeben, Feld, verwenden Sie Folgendes:

$.routes[0].legs[0].distance.value

Flexible Einstellungen für Webhook-Ressourcen

Im Folgenden werden die Einstellungen für Webhook-Ressourcen für flexible Webhooks beschrieben:

Begriff Definition
Anzeigename Der Name, der in der Konsole für den Webhook angezeigt wird.
Webhook-Zeitlimit Wenn Dialogflow eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es beim Warten auf eine Antwort zu einer Zeitüberschreitung kommen. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn eine Zeitüberschreitung auftritt, ruft Dialogflow ein webhook.error.timeout-Ereignis auf.
Typ Legen Sie Dienstverzeichnis fest, wenn Sie das Dienstverzeichnis für den privaten Netzwerkzugriff verwenden. Wählen Sie andernfalls Allgemeiner Webdienst aus.
Webhook-URL Geben Sie die URL-Adresse für Ihren Webhook-Dienst an, die Verweise auf Sitzungsparameter enthalten kann.
Subtyp Auf Flexibel festlegen
Methode Legen Sie die HTTP-Methode für die Webhook-Anfrage fest.
Anfragetext Geben Sie den JSON-Anfragetext wie oben beschrieben an.
Antwortkonfiguration Geben Sie die Sitzungsparameter an, die auf Antwortfelder festgelegt werden sollen, wie oben beschrieben.
Umgebungsspezifischer Webhook Sie können umgebungsspezifische Webhooks bereitstellen.
Authentifizierung Weitere Informationen finden Sie im Abschnitt zur Authentifizierung.
Benutzerdefiniertes CA-Zertifikat Hiermit werden benutzerdefinierte CA-Zertifikate hochgeladen.

Vordefinierte benutzerdefinierte Vorlage verwenden

Dialogflow bietet vordefinierte benutzerdefinierte Vorlagen, flexible Webhooks in Salesforce CRM integrieren.

  1. Klicken Sie auf dem Tab Manage (Verwalten) auf Webhooks (Webhooks) und dann auf + Create (+ Erstellen).

  2. Wählen Sie unter Untertyp die Option Flexibel aus.

  3. Klicken Sie auf Mit vordefinierter Vorlage konfigurieren, um die Funktion zu aktivieren.

  4. Wählen Sie im Drop-down-Menü Integrationstyp die Option Salesforce aus.

  5. Wählen Sie im Drop-down-Menü API-Name einen API-Namen aus. Vorlage automatisch das Webhook-Formular anhand des API-Namens aus, auswählen.

    1. Sie können die folgenden Felder bei Bedarf manuell konfigurieren, basierend auf Ihre Parameter:

      • Webhook-URL
      • Methode
      • JSON-Anfragetext
      • Antwortkonfiguration

    2. Die erforderlichen OAuth-Felder sind in der Authentifizierung hervorgehoben. .

  6. Klicken Sie auf Speichern, um den Webhook zu erstellen.

Webhook-Dienstanforderungen

Der Webhook-Dienst muss die folgenden Anforderungen erfüllen:

Authentifizierung

Es ist wichtig, den Webhook-Dienst so zu sichern, dass nur Sie oder Ihr Dialogflow-Agent berechtigt sind, Anfragen zu stellen. Dies wird beim Erstellen einer Webhook-Ressource konfiguriert. Dialogflow CX unterstützt die folgenden Authentifizierungsverfahren:

Begriff Definition
Authentifizierungsheader Für Webhook-Einstellungen können Sie optionale Schlüssel/Wert-Paare im HTTP-Header angeben. Wenn angegeben, fügt Dialogflow diese HTTP-Header Webhook-Anfragen hinzu. Üblicherweise wird ein einzelnes Paar mit dem Schlüssel authorization angegeben. Headerwerte unterstützen Verweise auf Sitzungsparameter und das Parsing von Systemfunktionen wie in statischen Antwortnachrichten.
Basisauthentifizierung mit Nutzername und Passwort Für die Webhook-Einstellungen können Sie optionale Werte für einen Nutzernamen und ein Passwort für die Anmeldung angeben. Wenn angegeben, fügt Dialogflow Webhook-Anfragen einen Autorisierungs-HTTP-Header hinzu. Dieser Header hat das Format "authorization: Basic <base 64 encoding of the string username:password>".
Drittanbieter-OAuth Sie können die OAuth-Konfiguration des Drittanbieters so festlegen, dass Dialogflow ein Zugriffstoken vom OAuth-Anbieter austauscht und im HTTP-Header für die Autorisierung hinzufügt. Es wird nur der Vorgang für Clientanmeldedaten unterstützt.
Zugriffstokens des Dienst-Agents Sie können in der Dienst-Agent-Authentifizierung ein Zugriffstoken auswählen, um Zugriffstokens für den Dienst-Agent für die Authentifizierung zu verwenden. Damit kann auf andere Google Cloud APIs zugegriffen werden.
Dienst-Agent-ID-Tokens Sie können das ID-Token in der Dienst-Agent-Authentifizierung auswählen, um Dienst-Agent-ID-Tokens für die Authentifizierung zu verwenden. Damit kann auf Cloud Function- und Cloud Run-Dienste zugegriffen werden. Wenn keine anderen Authentifizierungsoptionen verwendet werden, ist diese Option standardmäßig aktiviert.
Gegenseitige TLS-Authentifizierung Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.

HTTPS-Zertifikatsüberprüfung

Dialogflow verwendet standardmäßig den Standard-Trust Store von Google, um HTTPS-Zertifikate zu prüfen. Wenn Sie Zertifikate verwenden möchten, die vom Standard-Trust Store von Google nicht für Ihren HTTPS-Server erkannt werden, z. B. selbst signierte oder benutzerdefinierte Root-Zertifikate, lesen Sie die Informationen unter Benutzerdefinierte CA-Zertifikate.

Umgebungsspezifische Webhooks

Wenn Sie Umgebungen Produktionssysteme von Entwicklungssystemen zu isolieren (empfohlen), können Sie Ihre Webhooks so konfigurieren, dass sie umgebungsspezifisch sind. Für jede von Ihnen definierte Webhook-Ressource können Sie eine eindeutige URL und Authentifizierungseinstellungen für jede Umgebung, die Sie für den Agent definiert haben.

So können Sie Webhook-Codeaktualisierungen sicher entwickeln und testen bevor Sie sie in der Produktion bereitstellen.

Webhook-Ressourcen erstellen oder bearbeiten

Wenn ein Webhook-Dienst ausgeführt wird, müssen Sie in Ihrem Agent eine Webhook-Ressource mit Verbindungs- und Authentifizierungsinformationen erstellen. Nach der Erstellung können Sie die Einstellungen für Webhook-Ressourcen jederzeit bearbeiten.

So erstellen oder bearbeiten Sie eine Webhook-Ressource:

Console

  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 oder auf eine Webhook-Ressource in der Liste, um sie zu bearbeiten.
  7. Geben Sie die Standardeinstellungen für Webhook-Ressourcen ein. oder flexible Einstellungen für Webhook-Ressourcen.
  8. Klicken Sie auf Speichern.

API

Informationen zum Erstellen einer Webhook-Ressource finden Sie in der Methode create für den Typ Webhook. So bearbeiten Sie eine Webhook-Ressource (außer umgebungsspezifischen Einstellungen): Siehe die Methode patch oder update für den Typ Webhook.

Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:

Protokoll V3 V3beta1
REST Webhook-Ressource Webhook-Ressource
RPC Webhook-Oberfläche Webhook-Oberfläche
C++ WebhooksClient Nicht verfügbar
C# WebhooksClient Nicht verfügbar
Go WebhooksClient Nicht verfügbar
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP Nicht verfügbar Nicht verfügbar
Python WebhooksClient WebhooksClient
Ruby Nicht verfügbar Nicht verfügbar

So bearbeiten Sie die umgebungsspezifischen Einstellungen für einen Webhook: Siehe die Methode patch oder update für den Typ Environment.

Wählen Sie ein Protokoll und eine Version für die Umgebungsreferenz aus:

Protokoll V3 V3beta1
REST Umgebungsressource Umgebungsressource
RPC Umgebungsschnittstelle Umgebungsschnittstelle
C++ EnvironmentsClient Nicht verfügbar
C# EnvironmentsClient Nicht verfügbar
Go EnvironmentsClient Nicht verfügbar
Java EnvironmentsClient EnvironmentsClient
Node.js EnvironmentsClient EnvironmentsClient
PHP Nicht verfügbar Nicht verfügbar
Python EnvironmentsClient EnvironmentsClient
Ruby Nicht verfügbar Nicht verfügbar

Webhook-Fehler

Wenn Ihr Webhook-Dienst bei der Verarbeitung einer Webhook-Anfrage einen Fehler feststellt, muss Ihr Webhook-Code einen der folgenden HTTP-Statuscodes zurückgeben:

  • 400 Fehlerhafte Anfrage
  • 401 Nicht autorisiert
  • 403 Unzulässig
  • 404 Nicht gefunden
  • 500 Serverfehler
  • 503 Dienst nicht verfügbar

In allen folgenden Fehlersituationen ruft Dialogflow einen Webhook-Fehler oder ein integriertes Zeilimitereignis auf und fährt mit der Verarbeitung wie gewohnt fort:

  • Antwortzeitlimit überschritten.
  • Fehlerstatuscode empfangen.
  • Die Antwort ist ungültig.
  • Der Webhook-Dienst ist nicht verfügbar.

Wenn der Webhook-Dienstaufruf durch einen API-Aufruf zur Intent-Erkennung ausgelöst wurde, enthält das Feld queryResult.webhookStatuses in der Antwort zur Intent-Erkennung die Webhook-Statusinformationen.

Cloud Functions verwenden

Dialogflow lässt sich in Cloud Functions einbinden, sodass Sie problemlos einen sicheren, serverlosen Webhook erstellen können. Wenn Sie eine Funktion erstellen, die sich im selben Projekt wie Ihr Agent befindet, kann der Agent den Webhook ohne spezielle Konfiguration sicher aufrufen.

Es gibt jedoch zwei Situationen, in denen Sie diese Integration manuell einrichten müssen:

  1. Dialogflow-Dienst-Agent Dienstkonto mit der folgenden Adresse für Ihr Agent-Projekt vorhanden sein: 
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Dieses spezielle Dienstkonto und der zugehörige Schlüssel wird normalerweise automatisch erstellt, wenn Sie den ersten Agent für ein Projekt erstellen. Wenn der Agent vor dem 1. November 2020 erstellt wurde, können Sie die Erstellung dieses speziellen Dienstkontos auslösen: <ph type="x-smartling-placeholder">
      </ph>
    1. Erstellen Sie einen neuen Agent für das Projekt.
    2. Führen Sie den folgenden Befehl aus: 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. Wenn sich die Webhook-Funktion in einem anderen Projekt als der Agent befindet, müssen Sie den Cloud Functions-Invoker IAM-Rolle an die Dialogflow-Dienst-Agent Dienstkonto im Projekt Ihrer Funktion.

Container-Webhooks und das Go ezcx-Framework verwenden

Informationen zum Implementieren eines Container-Webhooks mit Go finden Sie in der Go ezcx-Framework Dieses Framework kann viele der zum Erstellen eines Webhooks erforderlichen Schritte vereinfachen.

Service Directory für den privaten Netzwerkzugriff verwenden

Dialogflow wird in privaten Service Directory-Zugriff eingebunden, sodass eine Verbindung zu Webhook-Zielen in Ihrem VPC-Netzwerk hergestellt werden kann. Dadurch wird der Traffic innerhalb des Google Cloud-Netzwerks beibehalten und IAM sowie VPC Service Controls erzwungen.

So richten Sie einen Webhook ein, der auf ein privates Netzwerk ausgerichtet ist:

  1. Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.

  2. Dialogflow-Dienst-Agent Dienstkonto mit der folgenden Adresse für Ihr Agent-Projekt vorhanden sein: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Gewähren Sie dem Dienstkonto Dialogflow-Dienst-Agent die folgenden IAM-Rollen:

    • servicedirectory.viewer des Service Directory-Projekts
    • servicedirectory.pscAuthorizedService des Netzwerkprojekts

  3. Geben Sie beim Erstellen des Webhooks den Service Directory-Dienst mit der URL und optionalen Authentifizierungsinformationen an.

    Console

    Screenshot: Service Directory-Webhook.

    API

    Weitere Informationen finden Sie im Feld serviceDirectory für den Typ Webhook.

    Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:

    Protokoll V3 V3beta1
    REST Webhook-Ressource Webhook-Ressource
    RPC Webhook-Oberfläche Webhook-Oberfläche
    C++ WebhooksClient Nicht verfügbar
    C# WebhooksClient Nicht verfügbar
    Go WebhooksClient Nicht verfügbar
    Java WebhooksClient WebhooksClient
    Node.js WebhooksClient WebhooksClient
    PHP Nicht verfügbar Nicht verfügbar
    Python WebhooksClient WebhooksClient
    Ruby Nicht verfügbar Nicht verfügbar

Um Probleme zu beheben, können Sie ein private Verfügbarkeitsdiagnose um zu prüfen, ob Service Directory richtig konfiguriert ist.

Dienst-Agent-Authentifizierung

Dialogflow kann ein ID-Token oder Zugriffstoken mit Dialogflow-Dienst-Agent.

Das Token wird dem Autorisierungs-HTTP-Header hinzugefügt, wenn Dialogflow einen Webhook aufruft.

ID-Token

Mit einem ID-Token kann auf Cloud Function- und Cloud Run-Dienste zugegriffen werden, nachdem Sie 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
die Rolle „Invoker“ gewährt haben Wenn sich Cloud Function- und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzlichen IAM-Berechtigung zum Aufrufen.

Die Zielgruppe, die zum Generieren des ID-Tokens verwendet wird, ist die gesamte Webhook-URL mit Ausnahme von Abfrageparametern. Wenn Sie Cloud Run verwenden, muss diese URL von den Cloud Run-Zielgruppen unterstützt werden. Wenn die Webhook-URL beispielsweise

https://myproject.cloudfunctions.net/my-function/method1?query=value

muss sich die folgende URL in benutzerdefinierten Zielgruppen befinden.

https://myproject.cloudfunctions.net/my-function/method1

Jeder Webhook kann das Token optional validieren mit Google-Clientbibliotheken oder Open-Source-Bibliotheken wie github.com/googleapis/google-auth-library-nodejs.

Zugriffstoken

Ein Zugriffstoken kann für den Zugriff auf andere Google Cloud APIs verwendet werden, nachdem Sie den erforderlichen Rollen 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Beispiele und Fehlerbehebung

Weitere Informationen finden Sie in der Anleitung für Webhooks

Zurück
Auftragsausführungen
Weiter
Sprachmodelle