Format des Unterhaltungs-Webhooks {:#conversation-webhook-format} (Dialogflow)

In diesem Abschnitt wird das Format der JSON-Nutzlast beschrieben, wenn Actions on Google Ihre über das Actions SDK

Sobald eine Unterhaltung beginnt, wird sie durch eine eindeutige conversationId identifiziert. Für jeden weiteren Nutzer Anfrage an Assistant hat, erhält Ihre Auftragsausführung einen Intent, der die der Webhook verarbeiten und auf die er antworten muss. conversationId wird in jeder Anfrage beibehalten und bis die Unterhaltung beendet ist.

Hinweis :Ihre Antwort muss innerhalb von 10 Sekunden erfolgen. Andernfalls wird Assistant geht davon aus, dass die Ausführungszeit abgelaufen ist und die Unterhaltung beendet wird.

Anfragetext

Wenn Nutzer eine erste Anfrage stellen oder einige nachfolgende Eingaben machen, sendet Assistant eine Anfrage bis hin zu Ihrer Erfüllung. Anfragen von Unterhaltungs-Webhooks von Assistant Daten wie den ausgelösten Intent, den Rohtext des Nutzers die Eingabe und die Oberflächenfunktionen des Geräts.

Im Folgenden sind die wichtigsten Felder für eine Anfrage im Format des Unterhaltungs-Webhooks aufgeführt:

Feld	Beschreibung
isInSandbox	Diese boolesche Variable wird hauptsächlich für Folgendes verwendet: Transaktionen, um anzugeben, ob der Webhook diese Anfrage in der Sandbox verarbeiten soll. . Im Sandbox-Modus sollte Ihr Webhook keine Bestellungen von Nutzern in Rechnung stellen oder ausführen. Die Standardeinstellung ist „true“.
surface	Informationen zur Assistant-Oberfläche, mit der der Nutzer interagiert, und zu ihren Funktionen.
Inputs	Informationen zur Aufrufanfrage. Für den auslösenden Aufruf gehört dazu ein intent, der einer Aktion zugeordnet ist. Für weitere Anfragen in einer Konversation enthält, kann dieses Objekt auch Argumente enthalten, die dem Parameter erwartete Eingaben, die von der Auftragsausführung angegeben werden.
User	Informationen zu dem Nutzer, der die Anfrage gestellt hat. Zu diesen Informationen gehören Berechtigungen und der Sprache des Nutzers.
Conversation	Informationen zum Unterhaltungskontext, einschließlich Unterhaltungs-ID und Typ (z. B. ob diese Anfrage eine neue Unterhaltung initiiert) und ein Unterhaltungstoken zum Speichern persistenter Daten über die gesamte Lebensdauer der Konversation hinweg.
availableSurfaces	Diese Informationen werden für <ph type="x-smartling-placeholder"></ph> Unterhaltungen auf mehreren Oberflächen

Beispiel für eine einfache Aufrufanfrage

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

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to my test app"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

Beispiel für eine einfache Unterhaltungsanfrage

Das folgende Snippet zeigt ein Beispiel für eine Konversationsanfrage im Webhook-Format für Unterhaltungen. Dabei ist die Nutzereingabe ein Textstring (z. B. „Meine Glückszahl ist 88“):

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.TEXT",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "My lucky number is 88."
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

Antworttext

Die Content-Type im Header von HTTP-Beiträgen von Ihrem Endpunkt für die Auftragsausführung an Assistant application/json sein.

Eine Antwort im Das Format des Konversations-Webhooks enthält Daten wie die Benutzeroberfläche zur Anzeige der Nutzer (einschließlich audiovisueller Komponenten) und dem Intent, der durch in der nachfolgenden Anfrage ausgelöst (als erwarteter Intent bezeichnet). Der erwartete Wert Intent kann jeder der Intents sein, die Assistant versteht, wie beschrieben in der Intents API-Referenz

Hinweis: In Ihren Webhook-Antworten geben Sie normalerweise actions.intent.TEXT an. wie der erwartete Intent. Dieser Intent stellt eine Rohtextantwort vom Nutzer. Die generische ask()-Funktion in der Clientbibliothek erwartet diesen Intent.

Wenn Sie mehr über die Formatierung der Benutzeroberfläche für Ihre Antworten erfahren möchten, werden sie in Assistant angezeigt, sieh dir die Dokumentation zu Antworten

Beispiel für eine einfache Antwort

Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort in der Unterhaltung Webhook-Format verwenden.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
              }
            }
          ]
        }
      }
    }
  ]
}

Hilfsbeispiel

Das folgende Snippet zeigt ein Beispiel für die Verwendung eines Hilfs-Intents in der Unterhaltung Webhook-Format verwenden. In diesem Beispiel verwendet der Webhook den Parameter Helfer-Intent actions.intent.OPTIONS, Assistant anzuweisen, einen Auswahl zwischen mehreren Optionen.

Weitere Informationen zur Verwendung von Hilfs-Intents finden Sie in der Hilfsleitfaden.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.OPTION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
            "carouselSelect": {
              "items": [
                {
                  "optionInfo": {
                    "key": "one",
                    "synonyms": [
                      "synonym of KEY_ONE 1",
                      "synonym of KEY_ONE 2"
                    ]
                  },
                  "description": "Description of number one",
                  "title": "Number one"
                },
                {
                  "optionInfo": {
                    "key": "two",
                    "synonyms": [
                      "synonym of KEY_TWO 1",
                      "synonym of KEY_TWO 2"
                    ]
                  },
                  "description": "Description of number two",
                  "title": "Number two"
                }
              ]
            }
          }
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this shows an example of a carousel"
              }
            }
          ],
          "suggestions": [
            {
              "title": "1"
            },
            {
              "title": "2"
            }
          ]
        }
      }
    }
  ]
}

Beispiel für „Unterhaltung beenden“

Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort zum Beenden einer Unterhaltung Sitzung im Antwortformat des Unterhaltungs-Webhooks angeben.

Die expectedUserResponse Der Wert false in der Antwortnachricht signalisiert Assistant, dass kein weiterer Nutzer Eingabe wird erwartet und die aktuelle Unterhaltung beendet. Die finalResponse gibt an, was Assistant dem Nutzer vorher anzeigen oder ausgeben soll dass das Gespräch beendet wird.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

Informationen zum Überschreiben des Standardverhaltens beim Aufrufen eines Standards durch Nutzer um eine Unterhaltung mit Assistant zu beenden, siehe Unterhaltungsausstiege: