Format du webhook Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

Cette section décrit le format de la charge utile JSON lorsque Actions on Google appelle votre fulfillment via Dialogflow v2.

Si vous utilisez Dialogflow pour créer des actions, votre fulfillment communique avec Dialogflow via son propre format de webhook standard au lieu du Format du webhook de conversation Actions on Google. Le format de webhook Dialogflow contient toutes les informations format webhook de conversation ainsi que des données supplémentaires spécifiques à Dialogflow, telles que des informations différents contextes et paramètres.

Pour voir d'autres exemples de messages JSON pour les webhooks Dialogflow, vous pouvez consulter à ce projet GitHub.

Corps de la requête

Le message de request de Dialogflow contient des données au format webhook Dialogflow. Cet objet inclut Informations spécifiques à Actions on Google, comme résumé ci-dessous:

  • La valeur originalDetectIntentRequest.source est "google".
  • Le originalDetectIntentRequest.version indique l'action liée à Actions on Google de la requête.
  • Le originalDetectIntentRequest.payload contient des actions clés spécifiques à Google des informations, y compris la conversation demande JSON provenant de l'Assistant.
  • Le champ Conversation.conversationToken n'est pas compatible avec le webhook Dialogflow requêtes. À la place, votre fulfillment peut utiliser un contexte pour conserver les données de la conversation.

Exemple de requête d'appel simple

L'extrait de code ci-dessous montre un exemple de requête d'appel au format webhook 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}"
}

Exemple de requête de conversation simple

L'extrait de code ci-dessous montre un exemple de requête conversationnelle au format webhook Dialogflow, où l'entrée utilisateur est une chaîne de texte.

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

Exemple de résultat de l'outil d'aide

L'extrait de code ci-dessous montre un exemple de résultat d'assistance au format webhook Dialogflow. Cet exemple présente la réponse de l'utilisateur une fois que le webhook a été indiqué à l'Assistant dont il a besoin pour obtenir la confirmation de l'utilisateur.

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

Corps de la réponse

La valeur Content-Type dans l'en-tête des posts HTTP de votre point de terminaison de traitement vers l'Assistant doit être application/json.

Le message de réponse que votre fulfillment envoie à Dialogflow doit se trouver dans le format de webhook Dialogflow.

Lorsque vous communiquez avec l'Assistant, votre réponse contient généralement un payload objet qui encapsule un "google" . "google" l'objet de charge utile inclut Actions sur les informations spécifiques à Google Il doit contenir au minimum un champ expectUserResponse et un champ richResponse ou systemIntent.

Champs clés pour "google" de charge utile sont résumés ci-dessous:

Champ Description
expectUserResponse Indique si votre traitement attend une réponse de l'utilisateur. Définissez la valeur sur true quand poursuivre la conversation et false pour terminer la conversation.
userStorage Stocke les données persistantes liées à un utilisateur spécifique. L'espace de stockage total est de 10 000 octets.
richResponse Ce champ contient de l'audio, du texte, des fiches, des suggestions ou des données structurées pour que l'Assistant s'affiche. Pour en savoir plus sur l'utilisation des réponses enrichies pour Actions on Google, consultez Réponses enrichies
systemIntent Ce champ a la même structure que ExpectedInput.possibleIntents Votre réponse contient généralement systemIntent si votre traitement utilise Un intent d'aide. La possibleIntents dans systemIntent doit être défini sur ExpectedIntent , le nom du champ inputValueData ayant été remplacé par data.

Dans l'objet ExpectedIntent, vous spécifiez les valeurs suivantes :

  • intent: nom de l'intent pour l'application auxiliaire qui indique le type de les informations que vous souhaitez que l'utilisateur fournisse
  • data: une spécification de valeur, qui est une chaîne décrivant les données nécessaire pour que l'Assistant effectue l'aide.

Par exemple, si vous demandez l'autorisation de l'utilisateur, définissez intent sur actions.intent.PERMISSSION et le data à la spécification de valeur pour "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", ainsi que les champs pour de ce type.

La liste suivante récapitule les chaînes de spécification de valeur pour les assistants que vous pouvez définir dans un systemIntent pour une réponse de webhook Dialogflow. Pour obtenir la liste complète des intents Actions on Google pour contrôler la conversation, reportez-vous à la Documentation de référence sur les intents

Nom de l'intent Nom de l'événement Dialogflow Spécification de valeur Description
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Obtient une confirmation de l'utilisateur (par exemple, une réponse à une question par oui ou par non).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Récupère la date et l'heure saisies par l'utilisateur.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Obtient l'adresse de livraison saisie par l'utilisateur.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Demande un flux de lien profond vers une application Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Récupère l'élément sélectionné à partir d'une interface utilisateur de liste ou de carrousel.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Obtient les informations sur l'utilisateur, y compris son nom complet, sa position approximative ou la position exacte.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Demande un flux d'association de comptes pour associer le compte d'un utilisateur.

Exemple de réponse simple

L'extrait de code ci-dessous montre un exemple de réponse simple au format webhook Dialogflow.

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

Exemple de l'outil d'aide

L'extrait de code ci-dessous montre un exemple d'utilisation d'un intent d'assistance au format webhook Dialogflow. Dans cet exemple, le webhook utilise L'intent d'assistance actions.intent.OPTIONS demande à l'Assistant d'obtenir un la sélection de l'utilisateur entre deux options.

{
  "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"
              }
            ]
          }
        }
      }
    }
  }
}

À la réception du message de l'exemple précédent, l'Assistant prend en charge la conversation et invite l'utilisateur à faire une sélection en fonction les options données. Une fois que l'Assistant a collecté toutes les entrées utilisateur requises, il renvoie ce résultat d'aide à votre fulfillment dans une requête de webhook Dialogflow.

L'extrait de code ci-dessous montre un exemple de résultat de l'aide avec le choix de l'utilisateur.

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

Exemple de fin de conversation

L'extrait ci-dessous présente un exemple de réponse simple permettant de mettre fin à une conversation au format webhook Dialogflow. La expectUserResponse valeur false dans les signaux du message de réponse à l'Assistant qu'aucune autre action de l'utilisateur n'est attendue et qu'elle doit mettre fin au conversationnelle.

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

Pour savoir comment ignorer le comportement par défaut lorsque les utilisateurs appellent une requête phrase pour mettre fin à une conversation avec l'Assistant, consultez les guide des fermetures de conversation.