En esta sección, se describe el formato de la carga útil de JSON cuando Actions on Google invoca tu entrega a través del SDK de Actions.
Una vez que comienza una conversación, se identifica mediante un conversationId único. Para cada consulta posterior de usuario al Asistente, tu entrega recibe un intent que el webhook debe procesar y al que debe responder. Este conversationId se conserva en cada par de solicitud y respuesta hasta que finaliza la conversación.
Cuerpo de la solicitud
Cuando los usuarios realizan una consulta inicial o proporcionan una entrada posterior, Asistente envía una solicitud a la entrega. Las solicitudes de webhook de conversaciones de Asistente contienen datos como el intent que se activó, el texto sin procesar de la entrada 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 conversaciones:
| Campo | Descripción |
|---|---|
isInSandbox |
Esta variable booleana se usa principalmente para la función de
transacciones a fin de indicar si tu webhook debe controlar esta solicitud en modo de zona de pruebas. En el modo de zona de pruebas, tu webhook no debe cobrar ni entregar las órdenes de compra de los usuarios.
De forma predeterminada, se establece en "true". |
surface |
Información sobre la plataforma de Asistente con la que el usuario está interactuando y sus funciones. |
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. En las solicitudes posteriores de una conversación, este objeto también puede incluir argumentos que correspondan a las entradas esperadas que especificó tu entrega. |
User |
Información sobre el usuario que inició la solicitud. Esta información incluye los permisos que otorga el usuario y la configuración regional del usuario. |
Conversation |
Información sobre el contexto de la conversación, incluido el ID, el tipo (por ejemplo, si esta solicitud inicia una conversación nueva) y un token de la conversación para almacenar datos persistentes durante toda la vida útil de la conversación. |
availableSurfaces |
Esta información se usa para las conversaciones de varias superficies. |
Ejemplo de solicitud de invocación simple
El siguiente fragmento muestra un ejemplo de una solicitud de invocación en el formato de webhook de conversaciones.
{
"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
En el siguiente fragmento, se muestra un ejemplo de una solicitud de conversación en el formato de webhook de conversaciones, en la que la entrada del usuario es una string 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 el formato de webhook de conversación contiene datos como la IU real que se muestra al usuario (incluidos los componentes visuales y de audio) y el intent que se puede activar en la solicitud posterior (llamado intent esperado). El intent esperado puede ser cualquiera de los intents que comprenda el Asistente, como se describe en la referencia de la API de Intents.
Si quieres obtener más información para dar formato a la interfaz de usuario de tus respuestas cuando se muestran en Asistente, consulta la documentación sobre respuestas.
Ejemplo de respuesta simple
En el siguiente fragmento, se muestra un ejemplo de una respuesta simple en el formato de webhook de conversación.
{
"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 del uso de un intent auxiliar en el formato de webhook de la conversación. En este ejemplo, el webhook usa el intent auxiliar actions.intent.OPTIONS para indicarle al Asistente que obtenga una selección de usuario entre varias opciones.
Para obtener más información sobre el uso de intents auxiliares, consulta la guía de Asistentes.
{
"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
En el siguiente fragmento, se muestra un ejemplo de una respuesta simple para finalizar una sesión de conversación en el formato de respuesta de webhook de conversaciones.
El valor expectedUserResponse de false en el mensaje de respuesta le indica a Asistente que no se esperan más entradas del usuario y que debe finalizar la conversación actual. El valor finalResponse indica qué debería mostrar Asistente o qué salida le mostrará el usuario antes de que finalice la conversación.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Para aprender a anular el comportamiento predeterminado cuando los usuarios invocan una frase estándar para finalizar una conversación con Asistente, consulta Salidas de conversación.