En esta sección, se describe el formato de la carga útil de JSON cuando Actions on Google invoca tu entregas a través del SDK de Actions.
Cuando se inicia una conversación, se identifica con un conversationId único. Para cada usuario posterior
al Asistente, tu entrega recibe un intent que
el webhook debe procesar y responder. Este conversationId se conserva en todas las solicitudes y
par de respuestas hasta que finalice la conversación.
Cuerpo de la solicitud
Cuando los usuarios hacen una consulta inicial o proporcionan alguna entrada posterior, Asistente envía una solicitud a tu entrega. Solicitudes de webhook de conversación del Asistente contienen datos como el intent que se activó, el texto sin procesar del usuario y las capacidades de superficie del dispositivo del usuario.
A continuación, se resumen los campos clave para una solicitud en el formato de webhook de conversación:
| Campo | Descripción |
|---|---|
isInSandbox |
Esta variable booleana se utiliza principalmente para el atributo
de transacciones para indicar si tu webhook debe controlar esta solicitud en la zona de pruebas.
. En el modo de zona de pruebas, tu webhook no debe cobrar ni completar las órdenes de compra de los usuarios.
De forma predeterminada, se establece en "true". |
surface |
Información sobre la superficie de Asistente con la que el usuario está interactuando y sus capacidades. |
Inputs |
Información sobre la solicitud de invocación. Para la invocación de activación, esto incluye un intent que se asigna a una acción. Para versiones posteriores solicitudes en una conversación, este objeto también puede incluir argumentos correspondientes al las entradas esperadas que especifique tu entrega. |
User |
Información sobre el usuario que inició la solicitud. Esta información incluye permisos que otorga el usuario y la configuración regional del usuario. |
Conversation |
Información sobre el contexto de la conversación, incluido su ID y el tipo (por ejemplo, si esta solicitud inicia una nueva conversación) y un token de conversación para almacenar datos persistentes a lo largo de toda la conversación. |
availableSurfaces |
Esta información se usa para conversaciones de superficies múltiples. |
Ejemplo de solicitud de invocación simple
En el siguiente fragmento, se muestra un ejemplo de una solicitud de invocación en formato de webhook de conversación.
{
"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"
}
]
}
]
}
Ejemplo de solicitud de conversación simple
El siguiente fragmento muestra un ejemplo de una solicitud de conversación en el formato de webhook de conversación. donde la entrada del usuario es una cadena de texto (por ejemplo, "Mi número de la suerte es 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"
}
]
}
]
}
Cuerpo de la respuesta
El Content-Type en el encabezado de las publicaciones HTTP desde tu extremo de entrega
al Asistente debe ser application/json.
Una respuesta en la de webhook de conversación contiene datos como la IU real para mostrar el usuario (incluidos los componentes visuales y de audio), y la intención que se puede se activa en la solicitud posterior (denominado un intent esperado). Lo que se espera intent puede ser cualquiera de los intents que el Asistente comprenda, como se describe en la referencia de la API de Intents.
Para obtener más información sobre cómo dar formato a la interfaz de usuario en tus respuestas cuando se muestran en el Asistente, consulta la Respuestas.
Ejemplo de respuesta simple
El siguiente fragmento muestra un ejemplo de una respuesta simple en la conversación en formato de 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?"
}
}
]
}
}
}
]
}
Ejemplo de ayuda
El siguiente fragmento muestra un ejemplo de uso de un intent auxiliar en la conversación
en formato de webhook. En este ejemplo, el webhook usa
El intent auxiliar actions.intent.OPTIONS para indicarle a Asistente que obtenga un
la selección del usuario entre varias opciones.
Para obtener más información sobre el uso de intents auxiliares, consulta la Ayudante.
{
"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"
}
]
}
}
}
]
}
Ejemplo de finalización de conversación
El siguiente fragmento muestra un ejemplo de una respuesta simple para finalizar una conversación en el formato de respuesta de webhook de conversación.
El expectedUserResponse
de false en el mensaje de respuesta le indica al Asistente que ya no
se espera una entrada y que esta finalice la conversación actual. El
finalResponse
valor indica qué debería mostrar el Asistente o enviar al usuario antes
la conversación termina.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Para aprender a anular el comportamiento predeterminado cuando los usuarios invocan un frase para finalizar una conversación con el Asistente, consulta Salidas de la conversación.