Questa sezione descrive il formato del payload JSON quando Actions on Google richiama il tuo fulfillment tramite Dialogflow v2.
Se utilizzi Dialogflow per creare azioni, il fulfillment comunica con Dialogflow tramite il proprio formato webhook standard anziché tramite il formato webhook di conversazione Actions on Google. Il formato webhook di Dialogflow contiene tutte le informazioni sul formato webhook di conversazione, oltre a dati aggiuntivi specifici per Dialogflow, come informazioni su contesti e parametri.
Per visualizzare altri esempi di messaggi JSON per i webhook Dialogflow, puoi fare riferimento a questo progetto GitHub.
Corpo della richiesta
Il messaggio di richiesta di Dialogflow contiene dati nel formato webhook di Dialogflow. Questo oggetto include informazioni specifiche di Actions on Google, come riepilogate di seguito:
- Il valore di
originalDetectIntentRequest.sourceè "google". originalDetectIntentRequest.versionindica la versione di Actions on Google della richiesta.- Il campo
originalDetectIntentRequest.payloadcontiene informazioni chiave specifiche di Actions on Google, tra cui la richiesta di conversazione inviata dall'assistente. - Il campo
Conversation.conversationTokennon è supportato dalle richieste di webhook di Dialogflow. Il fulfillment può invece utilizzare un contesto Dialogflow per mantenere i dati nel corso della durata della conversazione.
Esempio di richiesta di chiamata semplice
Lo snippet seguente mostra un esempio di richiesta di chiamata nel formato webhook di Dialogflow.
{
"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}"
}
Esempio di richiesta di conversazione semplice
Lo snippet riportato di seguito mostra un esempio di richiesta conversazionale nel formato webhook Dialogflow, in cui l'input utente è una stringa di testo.
{
"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}"
}
Esempio di risultato della guida
Lo snippet seguente mostra un esempio di risultato helper nel formato webhook Dialogflow. Questo esempio mostra la risposta dell'utente dopo che il webhook ha indicato all'assistente che deve ottenere la conferma dell'utente.
{
"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}"
}
Corpo della risposta
Il Content-Type nell'intestazione dei post HTTP provenienti dall'endpoint di evasione degli ordini
all'assistente deve essere application/json.
Il messaggio di risposta che il tuo fulfillment invia a Dialogflow deve essere nel formato webhook di Dialogflow.
Durante la comunicazione con l'assistente, la risposta in genere contiene un oggetto payload che incapsula un oggetto "google". L'oggetto payload "google" include informazioni specifiche di Actions on Google. Deve contenere almeno un campo expectUserResponse e un campo richResponse o systemIntent.
I campi chiave per l'oggetto payload "google" sono riepilogati di seguito:
| Campo | Descrizione |
|---|---|
expectUserResponse |
Indica se il fulfillment prevede una risposta dell'utente. Imposta il valore su
true per mantenere viva la conversazione e su false per terminare
la conversazione. |
userStorage |
Archivia dati permanenti associati a un utente specifico. La quantità totale di archiviazione è di 10.000 byte. |
richResponse |
Questo campo contiene audio, testo, schede, suggerimenti o dati strutturati che l'assistente dovrà mostrare. Per scoprire di più sull'utilizzo delle risposte avanzate per Actions on Google, consulta la pagina Risposte dettagliate. |
systemIntent |
Questo campo ha la stessa struttura di ExpectedInput.possibleIntents. In genere, la risposta contiene un
systemIntent se il fulfillment utilizza
un intent helper. Il campo possibleIntents in systemIntent deve essere impostato su un oggetto ExpectedIntent, con il nome del campo inputValueData modificato in data.
|
All'interno dell'oggetto ExpectedIntent, devi specificare i seguenti valori:
- intent: un nome di intent per l'helper che indica il tipo di informazioni che vuoi che l'utente fornisca e
- data: una specifica del valore, ovvero una stringa che descrive i dati necessari all'assistente per eseguire l'helper.
Ad esempio, se viene richiesta l'autorizzazione dell'utente, imposta intent su
actions.intent.PERMISSSION e data sulla specifica del valore su
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", insieme ai campi per quel tipo.
Il seguente elenco riassume le stringhe di specifica dei valori per gli helper che puoi impostare in un
systemIntent per una risposta webhook di Dialogflow. Per un elenco completo degli intent di Actions on Google per il controllo conversazionale, consulta la pagina di riferimento relativa agli intent.
| Nome intent | Nome evento Dialogflow | Specifica del valore | Descrizione |
|---|---|---|---|
actions.intent.CONFIRMATION
|
actions_intent_CONFIRMATION |
"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"
|
Riceve una conferma dall'utente (ad esempio, una risposta a una domanda sì o no). |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
Consente di ottenere una data e un'ora inseriti dall'utente. |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
Consente di ottenere un indirizzo di consegna inserito dall'utente. |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
Richiede un flusso di link diretti in un'app per Android. |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
Consente di ottenere l'elemento selezionato da un elenco o dall'interfaccia utente di un carosello. |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
Consente di ottenere le informazioni dell'utente, tra cui nome completo, posizione approssimativa o posizione esatta. |
actions.intent.SIGN_IN
|
actions_intent_SIGN_IN |
"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"
|
Richiede una procedura di collegamento degli account per collegare l'account di un utente. |
Esempio di risposta semplice
Lo snippet seguente mostra un esempio di risposta semplice nel formato webhook di Dialogflow.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
Esempio di helper
Lo snippet riportato di seguito mostra un esempio di utilizzo di un intent helper nel formato webhook di Dialogflow. In questo esempio, il webhook utilizza l'intent helper actions.intent.OPTIONS per indicare all'assistente di ottenere una selezione utente tra due opzioni.
{
"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"
}
]
}
}
}
}
}
}
Dopo aver ricevuto il messaggio dell'esempio precedente, l'assistente prende temporaneamente il controllo della conversazione e chiede all'utente di effettuare una selezione in base alle opzioni fornite. Dopo aver raccolto tutti gli input utente richiesti, l'assistente invia questo risultato helper al fulfillment in una richiesta webhook di Dialogflow.
Lo snippet riportato di seguito mostra un esempio del risultato di supporto con la selezione della scelta dell'utente.
{
"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}"
}
Esempio di fine della conversazione
Lo snippet seguente mostra un esempio di risposta semplice per terminare una sessione di conversazione
in formato webhook Dialogflow. Il valore expectUserResponse false nel messaggio di risposta indica all'assistente che non sono previsti ulteriori input da parte dell'utente e che la conversazione in corso deve terminare.
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
Per informazioni su come ignorare il comportamento predefinito quando gli utenti richiamano una frase standard per terminare una conversazione con l'assistente, consulta la guida all'uscita dalla conversazione.