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.
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.
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.