Cette section décrit le format de la charge utile JSON lorsque Actions on Google appelle votre traitement via Dialogflow v2.
Si vous utilisez Dialogflow pour créer des actions, votre traitement communique avec Dialogflow via son propre format de webhook standard au lieu du format de webhook de conversation Actions on Google. Le format de webhook Dialogflow contient toutes les informations du format de webhook de conversation ainsi que des données supplémentaires spécifiques à Dialogflow, telles que des informations sur les contextes et les paramètres.
Pour voir d'autres exemples de messages JSON pour les webhooks Dialogflow, consultez ce projet GitHub.
Corps de la requête
Le message request de Dialogflow contient des données au format de webhook Dialogflow. Cet objet inclut des informations spécifiques à Actions on Google, comme résumé ci-dessous:
- La valeur
originalDetectIntentRequest.sourceest "google". originalDetectIntentRequest.versionindique la version Actions on Google de la requête.- Le
originalDetectIntentRequest.payloadcontient des informations clés spécifiques à Actions on Google, y compris la requête de conversation JSON de l'Assistant. - Le champ
Conversation.conversationTokenn'est pas compatible avec les requêtes de webhook Dialogflow. À la place, le traitement peut utiliser un contexte Dialogflow pour conserver les données tout au long de la durée de vie 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 de 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 demande de conversation simple
L'extrait ci-dessous montre un exemple de requête de conversation au format de 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 d'aide
L'extrait ci-dessous montre un exemple de résultat de l'application auxiliaire au format webhook Dialogflow. Cet exemple montre la réponse de l'utilisateur une fois que le webhook indique à l'Assistant qu'il doit 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
Le Content-Type dans l'en-tête des posts HTTP depuis votre point de terminaison de traitement vers l'Assistant doit être application/json.
Le message de réponse que votre fulfillment envoie à Dialogflow doit être au format du webhook Dialogflow.
Lorsque vous communiquez avec l'Assistant, votre réponse contient généralement un objet payload qui encapsule un objet "google". L'objet de charge utile "google" inclut des informations spécifiques à Actions on Google. Il doit contenir au minimum un champ expectUserResponse, ainsi qu'un champ richResponse ou systemIntent.
Les principaux champs de l'objet de charge utile "google" 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 sur false pour la mettre fin à 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 des contenus audio, du texte, des fiches, des suggestions ou des données structurées que l'Assistant doit afficher. Pour en savoir plus sur l'utilisation des réponses enrichies pour Actions on Google, consultez la section Réponses enrichies. |
systemIntent |
Ce champ présente la même structure que ExpectedInput.possibleIntents. Votre réponse contient généralement un systemIntent si votre traitement utilise un intent d'aide. Le champ possibleIntents de systemIntent doit être défini sur un objet ExpectedIntent, avec le nom du champ inputValueData remplacé par data.
|
Dans l'objet ExpectedIntent, vous spécifiez les valeurs suivantes:
- Intent: nom d'intent de l'outil d'aide qui indique le type d'informations que vous souhaitez que l'utilisateur fournisse.
- data: spécification de valeur, qui est une chaîne décrivant les données requises pour que l'Assistant exécute l'application auxiliaire.
Par exemple, si vous demandez l'autorisation de l'utilisateur, définissez intent sur actions.intent.PERMISSSION et data sur la spécification de valeur "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", ainsi que les champs correspondant à ce type.
La liste suivante récapitule les chaînes de spécification de valeur des assistants que vous pouvez définir dans un élément systemIntent pour une réponse webhook Dialogflow. Pour obtenir la liste complète des intents Actions on Google pour le contrôle conversationnel, consultez la documentation de référence sur les intents.
| Nom de l'intent | Nom de l'événement Dialogflow | Spécification de la 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 oui ou non). |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
Récupère une date et une heure saisies par l'utilisateur. |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
Récupère une adresse de livraison saisie de la part de l'utilisateur. |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
Demande un flux de liens profonds dans une application Android. |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
Obtient l'élément sélectionné à partir d'une liste ou d'une interface de carrousel. |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
obtient les informations de l'utilisateur, y compris son nom complet, sa position approximative ou sa 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 ci-dessous montre un exemple de réponse simple au format de webhook Dialogflow.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
Exemple d'aide
L'extrait ci-dessous montre un exemple d'utilisation d'un intent d'assistance au format de webhook Dialogflow. Dans cet exemple, votre webhook utilise l'intent d'assistance actions.intent.OPTIONS pour demander à l'Assistant d'obtenir une sélection d'utilisateurs 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 temporairement le relais et invite l'utilisateur à faire un choix en fonction des options données. Lors de la collecte de toutes les entrées utilisateur requises, l'Assistant renvoie ce résultat d'assistance à votre traitement dans une requête de webhook Dialogflow.
L'extrait ci-dessous montre un exemple de résultat de l'application auxiliaire avec la sélection du 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 montre un exemple de réponse simple permettant de mettre fin à une session de conversation au format webhook Dialogflow. La valeur expectUserResponse de false dans le message de réponse indique à l'Assistant qu'aucune autre entrée utilisateur n'est attendue et qu'elle doit mettre fin à la conversation en cours.
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
Pour savoir comment ignorer le comportement par défaut lorsque les utilisateurs appellent une expression standard pour mettre fin à une conversation avec l'Assistant, consultez le guide des sorties de conversation.