Cette section décrit le format de la charge utile JSON lorsqu'Actions on Google appelle votre traitement via le SDK Actions.
Lorsqu'une conversation commence, elle est identifiée par un conversationId unique. Pour chaque requête utilisateur ultérieure adressée à l'Assistant, le traitement reçoit un intent que votre webhook doit traiter et auquel votre webhook doit répondre. 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 des entrées ultérieures, 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 fonctionnalités de surface de l'appareil de l'utilisateur.
Les principaux champs 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 la fonctionnalité de
transactions, afin d'indiquer si votre webhook doit gérer cette requête en mode bac à sable. En mode bac à sable, 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 Assistant avec laquelle l'utilisateur interagit et sur ses fonctionnalités. |
Inputs |
Informations sur la requête d'appel. Pour le déclencheur, cela inclut un intent qui est mappé à une action. Pour les requêtes ultérieures dans 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 des données persistantes tout au long de la durée de la conversation. |
availableSurfaces |
Ces informations sont utilisées pour les conversations multisurfaces. |
Exemple de requête d'appel simple
L'extrait ci-dessous montre 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 demande de conversation simple
L'extrait ci-dessous montre un exemple de requête de conversation au format webhook de conversation, où l'entrée utilisateur est une chaîne de texte (par exemple, "My Lucky 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
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.
Une réponse au format webhook de conversation contient des données telles que l'UI réelle pour montrer à l'utilisateur (y compris les composants audio et visuels) et l'intent qui peut ê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 de 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 montre un exemple de réponse simple au format de webhook de conversation.
{
"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'aide
L'extrait ci-dessous montre un exemple d'utilisation d'un intent d'assistance dans le format du webhook de conversation. 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 des assistants.
{
"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 montre un exemple de réponse simple permettant de mettre fin à une session de conversation au format de réponse webhook de conversation.
La valeur expectedUserResponse 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. La valeur finalResponse indique ce que l'Assistant doit afficher ou fournir à l'utilisateur avant la fin de la conversation.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Pour découvrir comment ignorer le comportement par défaut lorsque les utilisateurs appellent une expression standard pour mettre fin à une conversation avec l'Assistant, consultez Sorties de conversation.