Questa sezione descrive il formato del payload JSON quando Actions on Google richiama il tuo fulfillment tramite l'SDK Actions.
Una volta avviata, la conversazione viene identificata da un conversationId univoco. Per ogni query utente successiva all'assistente, il fulfillment riceve un intent che il webhook deve elaborare e a cui deve rispondere. Questo conversationIdviene mantenuto in ogni coppia di richiesta e risposta fino al termine della conversazione.
Corpo della richiesta
Quando gli utenti effettuano una query iniziale o forniscono un input successivo, l'assistente invia una richiesta al fulfillment. Le richieste di webhook per le conversazioni provenienti dall'assistente contengono dati quali l'intent attivato, il testo non elaborato dell'input utente e le funzionalità di visualizzazione del dispositivo dell'utente.
Di seguito sono riepilogati i campi principali per una richiesta nel formato webhook di conversazione:
| Campo | Descrizione |
|---|---|
isInSandbox |
Questa variabile booleana viene utilizzata principalmente per la funzionalità
transazioni, al fine di indicare se il webhook deve gestire questa richiesta in modalità
sandbox. In modalità sandbox, il webhook non deve addebitare né evadere gli ordini di acquisto degli utenti.
Il valore predefinito è "true". |
surface |
Informazioni sulla piattaforma dell'assistente con cui l'utente interagisce e sulle sue funzionalità. |
Inputs |
Informazioni sulla richiesta di chiamata. Per la chiamata di trigger, include un intent mappato a un'azione. Per le richieste successive in una conversazione, questo oggetto potrebbe anche includere argomenti corrispondenti agli input previsti specificati dal fulfillment. |
User |
Informazioni sull'utente che ha avviato la richiesta. Queste informazioni includono le autorizzazioni concesse dall'utente e le impostazioni internazionali dell'utente. |
Conversation |
Informazioni sul contesto della conversazione, tra cui l'ID conversazione, il tipo (ad esempio se questa richiesta sta avviando una nuova conversazione) e un token di conversazione per archiviare i dati persistenti per tutta la durata della conversazione. |
availableSurfaces |
Queste informazioni vengono utilizzate per le conversazioni su più piattaforme. |
Esempio di richiesta di chiamata semplice
Lo snippet seguente mostra un esempio di richiesta di chiamata nel formato webhook di conversazione.
{
"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"
}
]
}
]
}
Esempio di richiesta di conversazione semplice
Lo snippet di seguito mostra un esempio di richiesta conversazionale nel formato webhook di conversazione, in cui l'input utente è una stringa di testo (ad esempio "Il mio numero fortunato è 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"
}
]
}
]
}
Corpo della risposta
Il Content-Type nell'intestazione dei post HTTP provenienti dall'endpoint di evasione degli ordini
all'assistente deve essere application/json.
Una risposta nel formato webhook di conversazione contiene dati quali l'interfaccia utente effettiva per mostrare l'utente (inclusi i componenti audio e visivi) e l'intent che può essere attivato nella richiesta successiva (chiamato intent previsto). L'intent previsto può essere uno qualsiasi degli intent che l'assistente comprende, come descritto nel riferimento dell'API Intents.
Per saperne di più sulla formattazione dell'interfaccia utente per le risposte quando vengono visualizzate nell'assistente, consulta la documentazione relativa alle risposte.
Esempio di risposta semplice
Lo snippet seguente mostra un esempio di risposta semplice nel formato webhook di conversazione.
{
"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?"
}
}
]
}
}
}
]
}
Esempio di helper
Lo snippet seguente mostra un esempio di utilizzo di un intent helper nel formato webhook di conversazione. In questo esempio, il webhook utilizza l'intent helper actions.intent.OPTIONS per indicare all'assistente di ottenere una selezione utente tra più opzioni.
Per scoprire di più sull'utilizzo degli intent helper, consulta la guida 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"
}
]
}
}
}
]
}
Esempio di fine della conversazione
Lo snippet seguente mostra un esempio di risposta semplice per terminare una sessione di conversazione nel formato di risposta webhook di conversazione.
Il valore expectedUserResponse
false nel messaggio di risposta indica all'assistente che non sono previsti ulteriori input
da parte dell'utente e che dovrebbe terminare la conversazione in corso. Il valore finalResponse indica cosa l'assistente deve mostrare o mostrare all'utente prima della fine della conversazione.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Per informazioni su come eseguire l'override del comportamento predefinito quando gli utenti richiamano una frase standard per terminare una conversazione con l'assistente, consulta Uscite dalla conversazione.