Cette section décrit le format de la charge utile JSON lorsque Actions on Google appelle le traitement via le SDK Actions.
Lorsqu'une conversation démarre, elle est identifiée par un conversationId unique. Pour chaque requête utilisateur envoyée à l'Assistant, votre fulfillment reçoit un intent que votre webhook doit traiter et traiter. Ce conversationId est conservé dans chaque paire requête/réponse jusqu'à la fin de la conversation.
Corps de la requête
Lorsque les utilisateurs effectuent une requête initiale ou fournissent une entrée ultérieure, l'Assistant envoie une requête à votre traitement. Les requêtes de webhook de conversation de l'Assistant contiennent des données telles que l'intent déclenché, le texte brut de l'entrée utilisateur et les capacités de surface de l'appareil de l'utilisateur.
Voici les principaux champs d'une requête au format webhook de la conversation:
| Champ | Description |
|---|---|
isInSandbox |
Cette variable booléenne est principalement utilisée pour la fonctionnalité de
transactions, pour indiquer si votre webhook doit gérer cette requête en mode bac à sable. En mode sandbox, votre webhook ne doit pas facturer ni traiter de bons de commande auprès 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 ses fonctionnalités. |
Inputs |
Informations sur la requête d'appel. Pour l'appel du déclencheur, cela inclut un intent correspondant à une action. Pour les requêtes ultérieures d'une conversation, cet objet peut également inclure des arguments correspondant aux 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ées 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 les données persistantes tout au long de la conversation. |
availableSurfaces |
Ces informations sont utilisées dans les conversations multiplates-formes. |
Exemple de requête d'appel simple
L'extrait ci-dessous présente un exemple de requête d'appel au format webhook de la 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 demande de conversation simple
L'extrait ci-dessous présente un exemple de requête de conversation au format webhook, dans lequel l'entrée utilisateur est une chaîne de texte (par exemple, Myuck number is 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
La valeur Content-Type dans l'en-tête des posts HTTP de votre point de terminaison de traitement à l'Assistant doit être application/json.
Une réponse au format webhook de la conversation contient des données telles que l'interface utilisateur réelle à présenter à l'utilisateur (y compris les composants audio et visuels) et l'intent pouvant être déclenché dans la requête suivante (appelé intent attendu). L'intent attendu peut être n'importe quel intent compris par l'Assistant, comme 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 lorsqu'elles sont affichées dans l'Assistant, consultez la documentation Réponses.
Exemple de réponse simple
L'extrait ci-dessous présente un exemple de réponse simple au 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 d'assistance
L'extrait ci-dessous montre un exemple d'utilisation d'un intent d'assistance au format webhook. Dans cet exemple, le webhook utilise l'intent d'assistance actions.intent.OPTIONS pour demander à l'Assistant d'obtenir une sélection de l'utilisateur entre plusieurs options.
Pour en savoir plus sur l'utilisation des intents d'assistance, consultez le guide 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"
}
]
}
}
}
]
}
Mettre fin à la conversation
L'extrait ci-dessous montre un exemple de réponse simple pour mettre fin à une session de conversation au format de réponse du webhook.
La valeur expectedUserResponse du message de réponse false indique à l'Assistant qu'aucune autre entrée utilisateur n'est attendue et qu'elle doit mettre fin à la conversation actuelle. La valeur finalResponse indique ce que l'Assistant doit afficher ou afficher à l'utilisateur avant la fin de la conversation.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Pour savoir comment ignorer le comportement par défaut lorsque des utilisateurs appellent une expression standard pour mettre fin à une conversation avec l'Assistant, consultez la section Sorties de conversation.