En esta sección, se describe el formato de la carga útil de JSON cuando Actions on Google invoca tu entrega a través de Dialogflow v2.
Si usas Dialogflow para crear acciones, tu entrega se comunica con Dialogflow a través de su propio formato de webhook estándar en lugar del formato de webhook de conversaciones de Actions on Google. El formato de webhook de Dialogflow contiene toda la información del formato de webhook de conversación junto con datos adicionales específicos de Dialogflow, como la información sobre contextos y parámetros.
A fin de ver más ejemplos de mensajes JSON para webhooks de Dialogflow, puedes consultar este proyecto de GitHub.
Cuerpo de la solicitud
El mensaje request de Dialogflow contiene datos en el formato de webhook de Dialogflow. Este objeto incluye información específica de Actions on Google, como se resume a continuación:
- El valor de
originalDetectIntentRequest.source
es "google". - El
originalDetectIntentRequest.version
indica la versión de Actions on Google para la solicitud. originalDetectIntentRequest.payload
contiene información específica de Actions on Google, como la solicitud de conversación en JSON de Asistente.- El campo
Conversation.conversationToken
no es compatible con las solicitudes de webhook de Dialogflow. En su lugar, tu entrega puede usar un contexto de Dialogflow para conservar los datos durante la vida útil de la conversación.
Ejemplo de solicitud de invocación simple
En el siguiente fragmento, se muestra un ejemplo de una solicitud de invocación en el formato de webhook de Dialogflow.
{
"responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
"queryResult": {
"queryText": "GOOGLE_ASSISTANT_WELCOME",
"action": "input.welcome",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
"displayName": "Default Welcome Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "Talk to my test app",
"inputType": "VOICE"
}
],
"intent": "actions.intent.MAIN"
}
],
"user": {
"lastSeen": "2018-03-16T22:08:48Z",
"permissions": [
"UPDATE"
],
"locale": "en-US",
"userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
},
"conversation": {
"conversationId": "${SESSIONID}",
"type": "NEW"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Ejemplo de solicitud de conversación simple
En el fragmento que aparece a continuación, se muestra un ejemplo de una solicitud de conversación en formato de webhook de Dialogflow, en la que la entrada del usuario es una string de texto.
{
"responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
"queryResult": {
"queryText": "query from the user",
"action": "action.name.of.matched.dialogflow.intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
"displayName": "Name of Dialogflow Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "query from the user",
"inputType": "KEYBOARD"
}
],
"arguments": [
{
"rawText": "query from the user",
"textValue": "query from the user",
"name": "text"
}
],
"intent": "actions.intent.TEXT"
}
],
"user": {
"lastSeen": "2017-10-06T01:06:56Z",
"locale": "en-US",
"userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
},
"conversation": {
"conversationId": "1522951193000",
"type": "ACTIVE",
"conversationToken": "[]"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Ejemplo de resultado de ayuda
En el siguiente fragmento, se muestra un ejemplo de un resultado auxiliar en el formato de webhook de Dialogflow. En este ejemplo, se muestra la respuesta del usuario después de que el webhook le indica al Asistente que necesita obtener la confirmación del usuario.
{
"responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
"queryResult": {
"queryText": "actions_intent_CONFIRMATION",
"action": "Dialogflow action name of matched intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
"parameters": {
"CONFIRMATION": true
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow action name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {},
"inputs": [
{
"rawInputs": [
{
"query": "yes",
"inputType": "VOICE"
}
],
"arguments": [
{
"name": "CONFIRMATION",
"boolValue": true
}
],
"intent": "actions.intent.CONFIRMATION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
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
.
El mensaje de respuesta que tu entrega envía a Dialogflow debe estar en el formato de webhook de Dialogflow.
Cuando te comunicas con Asistente, tu respuesta suele contener un objeto payload
que encapsula un objeto "google
". El objeto de carga útil "google
" incluye información específica de Actions on Google. Debe contener, como mínimo, un campo expectUserResponse
y un campo richResponse
o systemIntent
.
A continuación, se resumen los campos clave para el objeto de carga útil "google
":
Campo | Descripción |
---|---|
expectUserResponse |
Indica si tu entrega espera una respuesta del usuario. Establece el valor en
true para mantener viva la conversación y false para finalizar
la conversación. |
userStorage |
Almacena datos persistentes vinculados a un usuario específico. La cantidad de almacenamiento total es de 10,000 bytes. |
richResponse |
Este campo contiene audio, texto, tarjetas, sugerencias o datos estructurados para que el Asistente los procese. Si deseas obtener más información sobre el uso de respuestas enriquecidas para Actions on Google, consulta Respuestas enriquecidas |
systemIntent |
Este campo tiene la misma estructura que ExpectedInput.possibleIntents . Por lo general, tu respuesta contiene un systemIntent si tu entrega usa un intent auxiliar. El campo possibleIntents de systemIntent se debe establecer como un objeto ExpectedIntent , con el nombre del campo inputValueData cambiado a data .
|
Dentro del objeto ExpectedIntent
, especifica estos valores:
- intent: Es un nombre de intent para el asistente que indica el tipo de información que quieres que proporcione el usuario.
- data: Es una especificación de valor, una cadena que describe los datos necesarios para que Asistente realice el asistente.
Por ejemplo, si solicitas el permiso del usuario, configura intent
en actions.intent.PERMISSSION
y data
en la especificación de valor como "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
, junto con los campos para ese tipo.
En la siguiente lista, se resumen las strings de especificación de valor para los asistentes que puedes configurar en un systemIntent
para una respuesta de webhook de Dialogflow. Si quieres obtener una lista completa de los intents de Actions on Google para el control de conversación, consulta la referencia de Intents.
Nombre del intent | Nombre del evento de Dialogflow | Especificación de valor | Descripción |
---|---|---|---|
actions.intent.CONFIRMATION
|
actions_intent_CONFIRMATION |
"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"
|
Obtiene una confirmación del usuario (por ejemplo, una respuesta a una pregunta de sí o no). |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
Obtiene una entrada de fecha y hora del usuario. |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
Obtiene una entrada de la dirección de entrega del usuario. |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
Solicita un flujo de vínculos directos a una app para Android. |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
Obtiene el elemento seleccionado de una IU de lista o carrusel. |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
Obtiene la información del usuario, incluidos el nombre completo, la ubicación aproximada o la ubicación precisa. |
actions.intent.SIGN_IN
|
actions_intent_SIGN_IN |
"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"
|
Solicita un flujo de vinculación de cuentas para vincular la cuenta de un usuario. |
Ejemplo de respuesta simple
En el siguiente fragmento, se muestra un ejemplo de una respuesta simple en el formato de webhook de Dialogflow.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
Ejemplo de ayuda
El fragmento que aparece a continuación muestra un ejemplo del uso de un intent auxiliar en el formato de webhook de Dialogflow. En este ejemplo, tu webhook usa el intent auxiliar actions.intent.OPTIONS
para indicarle al Asistente que obtenga una selección de usuario entre dos opciones.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Choose a item"
}
}
]
},
"systemIntent": {
"intent": "actions.intent.OPTION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"listSelect": {
"title": "Hello",
"items": [
{
"optionInfo": {
"key": "first title key"
},
"description": "first description",
"image": {
"url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
"accessibilityText": "first alt"
},
"title": "first title"
},
{
"optionInfo": {
"key": "second"
},
"description": "second description",
"image": {
"url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
"accessibilityText": "second alt"
},
"title": "second title"
}
]
}
}
}
}
}
}
Cuando recibe el mensaje del ejemplo anterior, Asistente se encarga de forma temporal de la conversación y le pide al usuario que realice una selección en función de las opciones proporcionadas. Cuando se recopila toda la entrada necesaria del usuario, el Asistente envía este resultado auxiliar a tu entrega en una solicitud de webhook de Dialogflow.
El siguiente fragmento muestra un ejemplo del resultado auxiliar con la selección de elección del usuario.
{
"responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
"queryResult": {
"queryText": "actions_intent_OPTION",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
"parameters": {
"OPTION": "key of selected item"
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow intent name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": []
},
"inputs": [
{
"rawInputs": [
{
"query": "Title of selected item",
"inputType": "TOUCH"
}
],
"arguments": [
{
"textValue": "Key of selected item",
"name": "OPTION"
}
],
"intent": "actions.intent.OPTION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
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 webhook de Dialogflow. El valor expectUserResponse
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.
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
Si deseas obtener información para anular el comportamiento predeterminado cuando los usuarios invocan una frase estándar para finalizar una conversación con Asistente, consulta la guía de salidas de conversación.