Actions on Google-Webhook-Formate (Dialogflow)

In diesem Dokument wird das Webhook-Format für die Kommunikation zwischen Actions on Google und einem Auftragsausführungsdienst beschrieben, der eine benutzerdefinierte Unterhaltungsoberfläche definiert.

Es ist wichtig zu verstehen, wie Actions on Google und Ihre Auftragsausführung über die Webhook-Formate von Actions on Google kommunizieren:

  • Zur Teilnahme an Unterhaltungen mit Actions on Google implementiert die Auftragsausführung einen Webhook, der auf HTTP-Anfragen von Actions on Google antworten kann.
  • Wenn Nutzer deine Aktion aufrufen, empfängt die Auftragsausführung ein HTTP POST mit einer JSON-Nutzlast, die die Anfrage des Nutzers beschreibt.
  • Die Auftragsausführung wiederum liest die Parameter aus der Anfragenutzlast, generiert eine entsprechende JSON-formatierte Antwort und sendet mit dieser Antwort eine Antwort an Assistant.

Anfragetypen

In dieser Tabelle sind die Arten von Anfragen zusammengefasst, die Ihr Webhook möglicherweise von Assistant erhalten kann:

Typ Beschreibung JSON-Beispiele
Aufrufanfragen Nutzeräußerungen, die die Unterhaltung mit der Auftragsausführung einleiten oder Deep-Link-Aktionen auslösen (z. B. "Mit Personal Chef sprechen, um Rezepte zum Abendessen zu finden").
  • Wenn Sie Dialogflow verwenden, entsprechen diese Anfragen den Intents, die im Abschnitt Discovery der Integrationseinstellungen für Google Assistant definiert sind.
  • Wenn Sie das Actions SDK verwenden, entsprechen diese Anfragen den Intents, die im Aktionspaket definiert sind.
Unterhaltungsanfragen Äußerungen von Nutzern in derselben Sitzung, nachdem die Unterhaltung mit der Auftragsausführung begonnen hat. Im Format des Unterhaltungs-Webhooks sind dies die Rohtextantworten des Nutzers, die den actions.intent.TEXT-Intents entsprechen, die die Auftragsausführung in der vorherigen Abfolge angefordert hat.
Hilfsergebnisse Anfragen, die von Assistant an die Auftragsausführung gesendet werden, wenn der Webhook in der vorherigen Unterhaltungsrunde einen Hilfs-Intent angefordert hat, um Teile der Unterhaltung zu verarbeiten (z. B. actions.intent.OPTION und actions.intent.PERMISSION).

Unterhaltungsanfragen und -antworten

In einem typischen Actions on Google-Interaktionsszenario sagen Nutzer einen Satz, um eine Aktion aufzurufen. Um eine Antwort bereitzustellen, sucht Actions on Google nach der Auftragsausführung, die mit der vom Nutzer aufgerufenen Aktion übereinstimmt, und sendet die Anfrage dorthin.

Sobald Actions on Google feststellt, dass Ihre Auftragsausführung eine geeignete Übereinstimmung für den Aufruf des Nutzers ist, wird eine Unterhaltungssitzung gestartet. Dazu wird eine HTTP-Anfrage mit einer JSON-Nutzlast mit den Anfrageinformationen des Nutzers an den Auftragsausführungsendpunkt gesendet. Die Auftragsausführung parst die Anfrage und gibt eine Antwort zurück, die eine JSON-Nutzlast enthält. Actions on Google wandelt die Nutzlast dann in eine gerenderte Sprach- und Multimediaausgabe für Nutzer um.

Abbildung 1. Actions on Google, die die Auftragsausführung über das Actions SDK aufrufen.

Weitere Informationen zum Format der JSON-Nutzlast, wenn Actions on Google die Auftragsausführung über das Actions SDK aufruft, finden Sie unter Format des Unterhaltungs-Webhooks.

Dialogflow-Anfragen und -Antworten

Wenn Sie Aktionen erstellen, können Sie optional Dialogflow verwenden, um das Erstellen von dialogorientierten Schnittstellen zu vereinfachen. In diesem Szenario fungiert Dialogflow als Proxy zwischen Actions on Google und der Auftragsausführung. Anstatt die HTTP/JSON-Anfrage direkt an den Endpunkt der Auftragsausführung zu senden, sendet Actions on Google sie an Dialogflow.

Dialogflow packt die in der ursprünglichen Anfrage enthaltene JSON-Nutzlast im Webhook-Format von Dialogflow und leitet die resultierende Anfrage an die Dialogflow-Auftragsausführung weiter.

Wenn umgekehrt die Auftragsausführung eine Antwort an Dialogflow sendet, muss die JSON-Nutzlast der Antwort dem Webhook-Format von Dialogflow entsprechen. Die Auftragsausführung parst die Parameter aus der Dialogflow-JSON-Anfrage und generiert eine Antwort im Dialogflow-Webhook-Format. Dialogflow wandelt die Antwort der Auftragsausführung dann in eine Antwortnachricht um, die Assistant versteht.

Abbildung 2. Actions on Google ruft die Auftragsausführung über Dialogflow auf.

Weitere Informationen zum Format der JSON-Nutzlast, wenn Actions on Google die Auftragsausführung über Dialogflow aufruft, finden Sie unter Dialogflow-Webhook-Format.