Dialogflow-Webhook-Format {:#dialogflow-webhook-format} (Dialogflow)

In diesem Abschnitt wird das Format der JSON-Nutzlast beschrieben, wenn Actions on Google die Auftragsausführung über Dialogflow v2 aufruft.

Wenn Sie Dialogflow zum Erstellen von Aktionen verwenden, kommuniziert die Auftragsausführung über ihr eigenes Standard-Webhook-Format anstelle des Webhook-Formats für Actions on Google-Unterhaltungen mit Dialogflow. Das Webhook-Format von Dialogflow enthält alle Informationen aus dem Format für Unterhaltungs-Webhooks sowie zusätzliche Dialogflow-spezifische Daten wie Informationen zu Kontexten und Parametern.

Weitere Beispiele für JSON-Nachrichten für Dialogflow-Webhooks finden Sie in diesem GitHub-Projekt.

Anfragetext

Die request-Nachricht von Dialogflow enthält Daten im Dialogflow-Webhook-Format. Dieses Objekt enthält Actions on Google-spezifische Informationen, wie unten zusammengefasst:

  • Der Wert von originalDetectIntentRequest.source lautet „google“.
  • originalDetectIntentRequest.version gibt die Actions on Google-Version für die Anfrage an.
  • Das originalDetectIntentRequest.payload enthält wichtige Actions on Google-spezifische Informationen, einschließlich der Unterhaltungsanfrage vom Assistant.
  • Das Feld Conversation.conversationToken wird von Dialogflow-Webhook-Anfragen nicht unterstützt. Stattdessen kann die Auftragsausführung einen Dialogflow-Kontext verwenden, um Daten über die gesamte Lebensdauer der Unterhaltung zu speichern.

Beispiel für eine einfache Aufrufanfrage

Das folgende Snippet zeigt ein Beispiel für eine Aufrufanfrage im Dialogflow-Webhook-Format.

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Beispiel für eine einfache Unterhaltungsanfrage

Das folgende Snippet zeigt ein Beispiel für eine dialogorientierte Anfrage im Dialogflow-Webhook-Format, bei der die Nutzereingabe ein Textstring ist.

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Beispiel für ein Hilfsergebnis

Das folgende Snippet zeigt ein Beispiel für ein Hilfsergebnis im Dialogflow-Webhook-Format. Dieses Beispiel zeigt die Antwort des Nutzers, nachdem der Webhook Assistant signalisiert, dass er die Bestätigung des Nutzers anfordern muss.

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Antworttext

Content-Type im Header von HTTP-Beiträgen von Ihrem Auftragsausführungsendpunkt an Assistant muss application/json sein.

Die Antwortnachricht, die die Auftragsausführung an Dialogflow sendet, muss das Dialogflow-Webhook-Format haben.

Wenn du mit Assistant kommunizierst, enthält deine Antwort in der Regel ein payload-Objekt, das ein google-Objekt enthält. Das Nutzlastobjekt „google“ enthält Actions on Google-spezifische Informationen. Er muss mindestens das Feld expectUserResponse und entweder das Feld richResponse oder systemIntent enthalten.

Die wichtigsten Felder für das Nutzlastobjekt „google“ sind unten zusammengefasst:

Feld Beschreibung
expectUserResponse Gibt an, ob die Auftragsausführung eine Nutzerantwort erwartet. Legen Sie den Wert auf true fest, wenn die Unterhaltung fortgesetzt werden soll, und auf false, um sie zu beenden.
userStorage Speichert persistente Daten, die an einen bestimmten Nutzer gebunden sind. Der gesamte Speicherplatz beträgt 10.000 Byte.
richResponse Dieses Feld enthält Audio, Text, Karten, Vorschläge oder strukturierte Daten zum Rendern durch Assistant. Weitere Informationen zur Verwendung von Rich-Antworten für Actions on Google findest du unter Rich-Antworten.
systemIntent Dieses Feld hat die gleiche Struktur wie ExpectedInput.possibleIntents. Die Antwort enthält normalerweise ein systemIntent, wenn die Auftragsausführung einen Hilfs-Intent verwendet. Das Feld possibleIntents in der Datei systemIntent muss auf ein ExpectedIntent-Objekt festgelegt werden. Der Feldname inputValueData muss in data geändert werden.

Im Objekt ExpectedIntent geben Sie folgende Werte an:

  • intent: Ein Intent-Name für das Hilfsprogramm, der die Art von Informationen angibt, die der Nutzer bereitstellen soll.
  • data: Eine Wertspezifikation. Dabei handelt es sich um einen String, der die Daten beschreibt, die Assistant für die Ausführung des Hilfsprogramms benötigt.

Wenn Sie beispielsweise die Berechtigung des Nutzers anfordern, setzen Sie intent auf actions.intent.PERMISSSION und data auf die Wertspezifikation auf "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", zusammen mit den Feldern für diesen Typ.

In der folgenden Liste sind die Wertespezifikationsstrings für Helfer zusammengefasst, die Sie in einem systemIntent für eine Dialogflow-Webhook-Antwort festlegen können. Eine vollständige Liste der Actions on Google-Intents für die Konversationssteuerung finden Sie in der Intents-Referenz.

Intent-Name Dialogflow-Ereignisname Wertspezifikation Beschreibung
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Er erhält eine Bestätigung vom Nutzer, z. B. eine Antwort auf eine Ja- oder Nein-Frage.
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Ruft eine Datums- und Uhrzeiteingabe vom Nutzer ab.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Ruft eine vom Nutzer eingegebene Lieferadresse ab.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Fordert einen Deeplink-Vorgang zu einer Android-App an.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Ruft das ausgewählte Element aus einer Listen- oder Karussell-Benutzeroberfläche ab.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Erfasst die Daten des Nutzers, einschließlich des vollständigen Namens, des ungefähren Standorts oder des genauen Standorts.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Fordert einen Kontoverknüpfungsvorgang an, um das Konto eines Nutzers zu verknüpfen.

Beispiel für eine einfache Antwort

Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort im Dialogflow-Webhook-Format.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Hilfsprogramm-Beispiel

Das folgende Snippet zeigt ein Beispiel für die Verwendung eines Hilfs-Intents im Dialogflow-Webhook-Format. In diesem Beispiel verwendet der Webhook den Hilfs-Intent actions.intent.OPTIONS, um Assistant anzuweisen, zwischen zwei Optionen durch den Nutzer auszuwählen.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

Beim Erhalt der Nachricht aus dem vorherigen Beispiel übernimmt Assistant vorübergehend die Unterhaltung und fordert den Nutzer auf, eine Auswahl basierend auf den angegebenen Optionen zu treffen. Nachdem alle erforderlichen Nutzereingaben erfasst wurden, sendet Assistant dieses Hilfsergebnis in einer Dialogflow-Webhook-Anfrage an die Auftragsausführung zurück.

Das folgende Snippet zeigt ein Beispiel für das Hilfsergebnis bei Auswahl der Nutzerauswahl.

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Beispiel für das Beenden einer Unterhaltung

Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort zum Beenden einer Unterhaltungssitzung im Dialogflow-Webhook-Format. Der expectUserResponse-Wert false in der Antwortnachricht signalisiert Assistant, dass keine weitere Nutzereingabe erwartet wird und die aktuelle Unterhaltung beendet werden soll.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

Informationen zum Überschreiben des Standardverhaltens, wenn Nutzer eine Standardphrase aufrufen, um eine Unterhaltung mit Assistant zu beenden, finden Sie im Leitfaden zum Beenden von Unterhaltungen.