In diesem Abschnitt wird das Format der JSON-Nutzlast beschrieben, wenn Actions on Google die Auftragsausführung über das Actions SDK aufruft.
Sobald eine Unterhaltung beginnt, wird sie durch eine eindeutige conversationId gekennzeichnet. Für jede nachfolgende Nutzerabfrage an Assistant erhält die Auftragsausführung einen Intent, den der Webhook verarbeiten und beantworten muss. Dieser conversationId wird in jedem Anfrage- und Antwortpaar beibehalten, bis die Unterhaltung endet.
Anfragetext
Wenn Nutzer eine erste Abfrage stellen oder eine Eingabe vornehmen, sendet Assistant eine Anfrage an die Auftragsausführung. Unterhaltungs-Webhook-Anfragen von Assistant enthalten Daten wie den ausgelösten Intent, den Rohtext der Nutzereingabe und die Oberflächenfunktionen des Geräts des Nutzers.
Die wichtigsten Felder für eine Anfrage im Webhook-Unterhaltungsformat sind unten zusammengefasst:
| Feld | Beschreibung |
|---|---|
isInSandbox |
Diese boolesche Variable wird hauptsächlich für die Funktion Transaktionen verwendet, um anzugeben, ob Ihr Webhook diese Anfrage im Sandbox-Modus verarbeiten soll. Im Sandbox-Modus sollte Ihr Webhook keine Bestellungen von Nutzern in Rechnung stellen oder ausführen.
Standardmäßig ist er auf „true“ festgelegt. |
surface |
Informationen zur Assistant-Oberfläche und den Funktionen des Nutzers. |
Inputs |
Informationen zum Aufrufantrag. Für den auslösenden Aufruf beinhaltet dies einen Intent, der einer Aktion zugeordnet ist. Für nachfolgende Anfragen in einer Unterhaltung kann dieses Objekt auch Argumente enthalten, die den erwarteten Eingaben entsprechen, die von der Auftragsausführung angegeben wurden. |
User |
Informationen zum Nutzer, der die Anfrage initiiert hat. Zu diesen Informationen gehören Berechtigungen, die der Nutzer erteilt hat, und das Gebietsschema des Nutzers. |
Conversation |
Informationen zum Unterhaltungskontext, einschließlich der Unterhaltungs-ID, des Typs (z. B. ob diese Anfrage eine neue Unterhaltung initiiert) und eines Unterhaltungstokens zum Speichern persistenter Daten für die gesamte Lebensdauer einer Unterhaltung. |
availableSurfaces |
Diese Informationen werden für Unterhaltungen mit mehreren Oberflächen verwendet. |
Beispiel für eine einfache Aufrufanfrage
Das folgende Snippet zeigt ein Beispiel für eine Aufrufanfrage im Unterhaltungs-Webhook-Format.
{
"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 dialogorientierte Anfrage im Unterhaltungs-Webhook-Format, bei der die Nutzereingabe einen Textstring ist (z. B. „My lucky number is 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 der HTTP-Posts von Ihrem Auftragsausführungsendpunkt an Assistant muss application/json sein.
Eine Antwort im Unterhaltungs-Webhook-Format enthält Daten wie die tatsächliche UI für die Anzeige des Nutzers (einschließlich Audio- und visueller Komponenten) und den Intent, der in der nachfolgenden Anfrage ausgelöst werden kann (ein erwarteter Intent). Der erwartete Intent kann ein beliebiger Intent sein, den Assistant versteht, wie in der Intents-API-Referenz beschrieben.
Weitere Informationen zum Formatieren der Benutzeroberfläche für Ihre Antworten, wenn sie in Assistant angezeigt werden, finden Sie in der Dokumentation zu Antworten.
Beispiel für eine einfache Antwort
Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort im Unterhaltungs-Webhook-Format.
{
"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?"
}
}
]
}
}
}
]
}
Beispiel für eine Hilfsanwendung
Das folgende Snippet zeigt ein Beispiel für die Verwendung eines Hilfs-Intents im Unterhaltungs-Webhook-Format. In diesem Beispiel verwendet der Webhook den Helper-Intent actions.intent.OPTIONS, um Assistant anzuweisen, eine Nutzerauswahl zwischen mehreren Optionen zu erhalten.
Weitere Informationen zur Verwendung von Hilfs-Intents finden Sie im Leitfaden Helper.
{
"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 Unterhaltungssitzung im Webhook-Antwortformat.
Der Wert expectedUserResponse von false in der Antwortnachricht signalisiert Assistant, dass keine weitere Nutzereingabe erwartet wird und die aktuelle Unterhaltung beendet werden sollte. Der Wert finalResponse gibt an, was Assistant anzeigen oder ausgeben soll, bevor die Unterhaltung beendet wird.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Informationen zum Überschreiben des Standardverhaltens, wenn Nutzer eine Standardwortgruppe zum Beenden einer Unterhaltung mit Assistant aufrufen, finden Sie unter Unterhaltungs-Exits.