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.