Format de webhook de conversation {:#conversation-webhook-format} (Dialogflow)

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

Lorsqu'une conversation démarre, elle est identifiée par un conversationId unique. Pour chaque utilisateur suivant à l'Assistant, votre traitement reçoit un intent qui que votre webhook doit traiter et auquel il doit répondre. Cet conversationId est conservé dans chaque requête. jusqu'à la fin de la conversation.

Remarque :Vous devez répondre dans un délai de 10 secondes, sinon l'Assistant suppose que votre traitement a expiré et met fin à votre conversation.

Corps de la requête

Lorsque l'utilisateur effectue une requête initiale ou fournit une entrée ultérieure, l'Assistant envoie une demande à votre traitement. Requêtes de webhook de conversation de l'Assistant contiennent des données comme l'intent qui a été déclenché, le texte brut de l'utilisateur d'entrée et de surface de l'appareil de l'utilisateur.

Les champs clés d'une requête au format webhook de conversation sont résumés ci-dessous:

Champ	Description
isInSandbox	Cette variable booléenne est principalement utilisée pour le paramètre transactions, pour indiquer si le webhook doit gérer cette requête en mode bac à sable. . En mode Sandbox, votre webhook ne doit pas facturer ni traiter les bons de commande des utilisateurs. Par défaut, il est défini sur "true".
surface	Informations sur la surface de l'Assistant avec laquelle l'utilisateur interagit et sur ses fonctionnalités.
Inputs	Informations sur la requête d'appel. Pour l'appel de déclenchement, il s'agit d'un élément Un intent qui est mappé à une action. Pour dans une conversation, cet objet peut également inclure des arguments correspondant au entrées attendues spécifiées par votre traitement.
User	Informations sur l'utilisateur à l'origine de la requête. Ces informations incluent les autorisations accordé par l'utilisateur et ses paramètres régionaux.
Conversation	Informations sur le contexte de la conversation, y compris l'ID de la conversation, le type (par exemple, si cette requête lance une nouvelle conversation) et un jeton de conversation pour stocker des données persistantes tout au long de la durée de vie de la conversation.
availableSurfaces	Ces informations sont utilisées pour les conversations sur plusieurs surfaces.

Exemple de requête d'appel simple

L'extrait ci-dessous présente un exemple de requête d'appel au format webhook de conversation.

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

Exemple de requête de conversation simple

L'extrait ci-dessous montre un exemple de requête conversationnelle au format webhook de conversation, où l'entrée utilisateur est une chaîne de texte (par exemple, "Mon chiffre porte-bonheur est le 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"
        }
      ]
    }
  ]
}

Corps de la réponse

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

Une réponse dans le Le format webhook de conversation contient des données telles que l'interface utilisateur pour afficher (y compris les composants audio et visuels) et l'intention qui peut être déclenché dans la requête suivante (appelée intent attendu). La valeur attendue peut correspondre à n'importe quel intent compris par l'Assistant, tel que décrit dans la documentation de référence de l'API Intents.

Remarque :Dans vos réponses webhook, vous spécifiez généralement actions.intent.TEXT que l'intent attendu. Cet intent représente une réponse textuelle brute de l'objet utilisateur. La fonction ask() générique de la bibliothèque cliente attend cet intent.

Pour en savoir plus sur la mise en forme de l'interface utilisateur pour vos réponses lorsque qui s'affichent dans l'Assistant, consultez les Réponses.

Exemple de réponse simple

L'extrait ci-dessous montre un exemple de réponse simple dans la conversation le format 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?"
              }
            }
          ]
        }
      }
    }
  ]
}

Exemple de l'outil d'aide

L'extrait ci-dessous montre un exemple d'utilisation d'un intent d'assistance dans la conversation le format webhook. 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 plusieurs options.

Pour en savoir plus sur l'utilisation des intents d'assistance, consultez Guide des outils d'aide.

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

Exemple de fin de conversation

L'extrait ci-dessous présente un exemple de réponse simple permettant de mettre fin à une conversation dans le format de réponse du webhook de conversation.

expectedUserResponse la valeur false dans le message de réponse indique à l'Assistant qu'aucun autre utilisateur une entrée est attendue et doit mettre fin à la conversation en cours. La finalResponse indique ce que l'Assistant doit afficher ou générer pour l'utilisateur la conversation se termine.

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

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