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 identifiziert. Bei jeder nachfolgenden Nutzerabfrage an Assistant erhält die Auftragsausführung einen Intent, den der Webhook verarbeiten und darauf antworten muss. Diese conversationId wird in jedem Anfrage- und Antwortpaar beibehalten, bis die Unterhaltung endet.
Anfragetext
Wenn Nutzer eine erste Anfrage stellen oder nachträglich etwas eingeben, 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 Format des Unterhaltungs-Webhooks sind unten zusammengefasst:
| Feld | Beschreibung |
|---|---|
isInSandbox |
Diese boolesche Variable wird hauptsächlich für die Funktion
Transaktionen verwendet und gibt an, ob der Webhook diese Anfrage im Sandbox-Modus verarbeiten soll. Im Sandbox-Modus sollte der 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 enthält dies einen Intent, der einer Aktion zugeordnet ist. Bei nachfolgenden Anfragen in einer Unterhaltung kann dieses Objekt auch Argumente enthalten, die den erwarteten Eingaben entsprechen, die von der Auftragsausführung angegeben werden. |
User |
Informationen über den Nutzer, der die Anfrage initiiert hat. Zu diesen Informationen gehören auch vom Nutzer erteilte Berechtigungen und die Sprache des Nutzers. |
Conversation |
Informationen zum Unterhaltungskontext, einschließlich der Unterhaltungs-ID, des Typs (z. B. ob durch diese Anfrage eine neue Unterhaltung initiiert wird) und ein Unterhaltungstoken zum Speichern persistenter Daten über die gesamte Laufzeit der 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 Format des Unterhaltungs-Webhooks.
{
"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 Format des Unterhaltungs-Webhooks, bei der die Nutzereingabe aus einem Textstring besteht (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
Content-Type im Header von HTTP-Beiträgen von Ihrem Auftragsausführungsendpunkt an Assistant muss application/json sein.
Eine Antwort im Unterhaltungs-Webhook-Format enthält Daten wie die tatsächliche UI, die dem Nutzer angezeigt wird (einschließlich Audio- und visuelle Komponenten), und den Intent, der in der nachfolgenden Anfrage ausgelöst werden kann (ein erwarteter Intent). Der erwartete Intent kann jeder der Intents sein, die Assistant versteht, wie in der Intents API-Referenz beschrieben.
Weitere Informationen zum Formatieren der Benutzeroberfläche für Antworten, wenn diese 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 Format eines Unterhaltungs-Webhooks.
{
"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?"
}
}
]
}
}
}
]
}
Hilfsprogramm-Beispiel
Das folgende Snippet zeigt ein Beispiel für die Verwendung eines Hilfs-Intents im Format eines Unterhaltungs-Webhooks. In diesem Beispiel verwendet der Webhook den Hilfs-Intent actions.intent.OPTIONS, um Assistant anzuweisen, eine Nutzerauswahl aus mehreren Optionen abzurufen.
Weitere Informationen zur Verwendung von Hilfs-Intents finden Sie in der Anleitung zu Assistenten.
{
"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 das Beenden einer Unterhaltung
Das folgende Snippet zeigt ein Beispiel für eine einfache Antwort zum Beenden einer Unterhaltungssitzung im Antwortformat des Unterhaltungs-Webhooks.
Der Wert expectedUserResponse von false in der Antwortnachricht signalisiert Assistant, dass keine weitere Nutzereingabe erwartet wird und die aktuelle Unterhaltung beendet werden soll. Der Wert finalResponse gibt an, was Assistant dem Nutzer anzeigen oder ausgeben soll, bevor die Unterhaltung endet.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Informationen zum Überschreiben des Standardverhaltens, wenn Nutzer eine Standardphrase aufrufen, um eine Unterhaltung mit Assistant zu beenden, finden Sie unter Unterhaltungen beenden.