Formato webhook di conversazione {:#conversation-webhook-format} (Dialogflow)

Questa sezione descrive il formato del payload JSON quando Actions on Google richiama il tuo completamento tramite l'SDK Actions.

Una volta iniziata, la conversazione viene identificata da un conversationId univoco. Per ogni utente successivo la query all'assistente, il fulfillment riceve un intent che che il webhook deve elaborare e rispondere. Questo conversationIdè persistente in ogni richiesta coppia di risposte fino al termine della conversazione.

Nota: la tua risposta deve avvenire entro 10 secondi, altrimenti l'assistente presuppone che l'evasione dell'ordine sia scaduta e la conversazione termina.

Corpo della richiesta

Quando gli utenti effettuano una query iniziale o forniscono input successivi, l'assistente invia una richiesta per raggiungere la tua destinazione. Richieste webhook di conversazione dall'assistente contengono dati come l'intent che è stato attivato e il testo non elaborato dell'utente e le capacità di superficie del dispositivo dell'utente.

Di seguito sono riepilogati i campi chiave per una richiesta nel formato webhook di conversazione:

Campo	Descrizione
isInSandbox	Questa variabile booleana viene utilizzata principalmente per transazioni, per indicare se il webhook deve gestire questa richiesta nella sandbox. . In modalità sandbox, il webhook non deve addebitare o evadere alcun ordine di acquisto degli utenti. Per impostazione predefinita, è impostata su "true".
surface	Informazioni sulla piattaforma dell'assistente con cui l'utente sta interagendo e le sue funzionalità.
Inputs	Informazioni sulla richiesta di chiamata. Per la chiamata di attivazione, è inclusa una intent associato a un'azione. Per i successivi richieste in una conversazione, questo oggetto potrebbe anche includere argomenti corrispondenti a quelli previsti, specificati dal fulfillment.
User	Informazioni sull'utente che ha avviato la richiesta. Queste informazioni includono le autorizzazioni concessa dall'utente e le sue impostazioni internazionali.
Conversation	Informazioni sul contesto della conversazione, inclusi l'ID e il tipo (ad esempio, se questa richiesta avvia una nuova conversazione) e un token di conversazione per archiviare dati permanenti per tutta la durata delle conversazioni.
availableSurfaces	Queste informazioni vengono utilizzate per conversazioni su più superfici.

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 seguente mostra un esempio di richiesta conversazionale nel formato webhook di conversazione, dove l'input dell'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

Content-Type nell'intestazione dei post HTTP del tuo endpoint di evasione degli ordini per l'assistente deve essere application/json.

Una risposta nel del webhook di conversazione contiene dati come l'UI effettiva per mostrare l'utente (inclusi i componenti audio e video) e l'intento che può essere attivati nella richiesta successiva (detta intent previsto). Il valore previsto può essere qualsiasi intent compreso dall'assistente, come descritto nel riferimento dell'API Intent.

Nota: nelle risposte webhook, in genere devi specificare actions.intent.TEXT come l'intento previsto. Questo intent rappresenta una risposta di testo non elaborata dalla richiesta utente. La funzione ask() generica nella libreria client prevede questo intent.

Per ulteriori informazioni sulla formattazione dell'interfaccia utente delle risposte quando vengono mostrate nell'assistente, documentazione relativa alle risposte.

Esempio di risposta semplice

Lo snippet seguente mostra un esempio di risposta semplice nella conversazione webhook.

{
  "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 supporto

Lo snippet seguente mostra un esempio di utilizzo di un intent helper nella conversazione webhook. In questo esempio, il webhook utilizza la proprietà Intento helper actions.intent.OPTIONS di chiedere all'assistente di ottenere un la selezione dell'utente tra le varie opzioni.

Per scoprire di più sull'utilizzo degli helper intent, consulta 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 conversazione

Lo snippet seguente mostra un esempio di risposta semplice per terminare una conversazione nel formato di risposta del webhook di conversazione.

La expectedUserResponse il valore di false nel messaggio di risposta segnala all'assistente che nessun altro utente è previsto e dovrebbe terminare la conversazione in corso. La finalResponse indica ciò che l'assistente dovrebbe mostrare all'utente prima termina la conversazione.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

Scopri come eseguire l'override del comportamento predefinito quando gli utenti richiamano un modello frase per terminare una conversazione con l'assistente, vedi Uscite dalla conversazione.