Formato webhook Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

Questa sezione descrive il formato del payload JSON quando Actions on Google richiama il tuo il fulfillment tramite Dialogflow v2.

Se utilizzi Dialogflow per creare azioni, il tuo fulfillment comunica con Dialogflow tramite il proprio formato webhook standard anziché tramite Formato webhook di conversazione di Actions on Google. Il formato webhook di Dialogflow contiene tutte le informazioni del formato webhook di conversazione insieme ad altri dati specifici di Dialogflow, come le informazioni 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 da Dialogflow contiene dati nel formato webhook di Dialogflow. Questo oggetto include Informazioni specifiche per le azioni su Google, come riassunte di seguito:

  • Il valore di originalDetectIntentRequest.source è "google".
  • L'elemento originalDetectIntentRequest.version indica le Azioni su Google per la richiesta.
  • L'originalDetectIntentRequest.payload contiene azioni chiave specifiche su Google informazioni, inclusa la conversazione richiesta JSON dell'assistente.
  • Il campo Conversation.conversationToken non è supportato dal webhook Dialogflow richieste. Per il completamento, invece, puoi utilizzare Dialogflow. contesto per rendere persistenti i dati della conversazione.

Esempio di richiesta di chiamata semplice

Lo snippet seguente mostra un esempio di richiesta di chiamata in Dialogflow webhook.

{
  "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 seguente mostra un esempio di richiesta conversazionale in Dialogflow formato webhook, in cui l'input dell'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 helper

Lo snippet seguente mostra un esempio di risultato helper nel formato webhook di Dialogflow. Questo esempio mostra la risposta dell'utente dopo che il webhook indica all'assistente di avere bisogno della 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

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

Il messaggio di risposta che il fulfillment invia a Dialogflow deve essere in il formato webhook Dialogflow.

Quando comunichi con l'assistente, la tua risposta in genere contiene un payload che incapsula "google" . "google" l'oggetto payload include Informazioni specifiche di Actions on Google. Deve contenere almeno expectUserResponse e un campo richResponse o systemIntent.

I campi chiave per "google" gli oggetti payload sono riassunti di seguito:

Campo Descrizione
expectUserResponse Indica se l'evasione degli ordini prevede una risposta dell'utente. Imposta il valore su true quando continuare la conversazione e false per terminare la conversazione.
userStorage Archivia dati permanenti associati a un utente specifico. Lo spazio di archiviazione totale è di 10.000 byte.
richResponse Questo campo contiene audio, testo, schede, suggerimenti o dati strutturati per il rendering dell'assistente. Per ulteriori informazioni sull'utilizzo delle risposte avanzate per Actions on Google, vedi Risposte avanzate
systemIntent Questo campo ha la stessa struttura del ExpectedInput.possibleIntents. In genere la risposta contiene un systemIntent se il completamento utilizza un intent helper. La possibleIntents nel campo systemIntent deve essere impostato su un ExpectedIntent con il nome campo inputValueData modificato in data.

Nel ExpectedIntent , devi specificare questi valori:

  • intent: il nome dell'intent per l'assistente che indica il tipo di le informazioni che vuoi che l'utente fornisca
  • data: una specifica del valore, ovvero una stringa che descrive i dati presenti necessario affinché l'assistente possa svolgere l'assistente.

Ad esempio, se richiedi l'autorizzazione dell'utente, imposta intent su actions.intent.PERMISSSION e data alla specifica del valore per "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", insieme ai campi per quel tipo.

Il seguente elenco riassume le stringhe della 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, vedi Riferimento agli intent.

Nome intent Nome evento Dialogflow Specifica valore Descrizione
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Consente di ottenere una conferma dall'utente (ad esempio una risposta a una domanda che prevede una risposta affermativa o negativa).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Consente di ottenere una data e un'ora inserite 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" Consente di richiedere 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 dall'interfaccia utente di un elenco o di un carosello.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Consente di ottenere informazioni sull'utente, tra cui nome e cognome, posizione approssimativa oppure posizione esatta.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Richiede un flusso di collegamento dell'account per collegare l'account di un utente.

Esempio di risposta semplice

Lo snippet seguente mostra un esempio di risposta semplice in Dialogflow webhook.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Esempio di supporto

Lo snippet seguente mostra un esempio di utilizzo di un intent helper in Dialogflow webhook. In questo esempio, il webhook utilizza l'intent di assistenza actions.intent.OPTIONS per indicare all'assistente di ottenere una selezione dell'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"
              }
            ]
          }
        }
      }
    }
  }
}

Alla ricezione del messaggio dell'esempio precedente, l'assistente prende in carico la conversazione e chiede all'utente di effettuare una selezione in base le opzioni offerte. Dopo aver raccolto tutti gli input utente richiesti, l'assistente invia questo risultato helper al tuo fulfillment in una richiesta webhook di Dialogflow.

Lo snippet seguente mostra un esempio del risultato helper con la selezione da parte 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 conversazione

Lo snippet seguente mostra un esempio di risposta semplice per terminare una conversazione nel formato webhook di Dialogflow. La expectUserResponse valore di false negli indicatori dei messaggi di risposta per l'assistente che non siano previsti ulteriori input dell'utente e che l'operazione termini conversazione.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

Scopri come eseguire l'override del comportamento predefinito quando gli utenti richiamano un modello frase per terminare una conversazione con l'assistente, consulta le guida alle uscite dalla conversazione.