En esta guía, se describe cómo las apps de Google Chat pueden recopilar y procesar información de los usuarios creando entradas de formularios en interfaces basadas en tarjetas.
Las apps de chat solicitan información a los usuarios para que realicen acciones fuera de Chat, lo que incluye las siguientes formas:
- Define la configuración. Por ejemplo, para permitir que los usuarios personalicen la configuración de notificaciones o configuren y agreguen la app de Chat a uno o más espacios.
- Crear o actualizar información en otras aplicaciones de Google Workspace Para Por ejemplo, permite que los usuarios creen un evento del Calendario de Google.
- Permite que los usuarios accedan a recursos y los actualicen en otras apps o servicios web. Por ejemplo, una app de Chat puede ayudar a los usuarios a actualizar el estado de un ticket de asistencia directamente desde un espacio de Chat.
Requisitos previos
Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva, completa una de las siguientes guías de inicio rápido en la arquitectura de app que quieres usar:- Servicio HTTP con Google Cloud Functions
- Google Apps Script
- Dialogflow CX de Google Cloud
- Google Cloud Pub/Sub
Crear formularios con tarjetas
Para recopilar información, las apps de Chat diseñan formularios y sus entradas, y los compilan en tarjetas. Para mostrar tarjetas a los usuarios, las apps de Chat pueden usar las siguientes interfaces de Chat:
- Mensajes que contienen una o más tarjetas
- Páginas principales que es una tarjeta que aparece en la pestaña Página principal en mensajes con la app de Chat.
- Diálogos, que son tarjetas que se abren en una nueva ventana desde los mensajes y las páginas principales.
Las apps de chat pueden compilar las tarjetas con los siguientes widgets:
Widgets de entrada de formularios que solicitan información a los usuarios De manera opcional, puedes añadir validación a los widgets de entrada de formularios para asegurarte de que los usuarios ingresen y formen la información correctamente. Las apps de chat pueden usar los siguientes widgets de entrada de formulario:
- Entradas de texto
(
textInput
) para formato libre o texto sugerido. - Entradas de selección
(
selectionInput
) son elementos de la IU seleccionables, como casillas de verificación, botones de selección y menús desplegables. Los widgets de entrada de selección también propagar elementos de fuentes de datos estáticas o dinámicas. Por ejemplo, los usuarios pueden Seleccionar de una lista de espacios de Chat de los que son miembros. - Selectores de fecha y hora
(
dateTimePicker
) para las entradas de fecha y hora.
- Entradas de texto
(
Un widget de botón para que los usuarios puedan enviar los valores que ingresaron en la tarjeta. Después de que un usuario hace clic en el botón, la app de Chat puede procesar la información que recibe.
A continuación, se muestra una tarjeta que consta de tres tipos diferentes de entradas de fecha y hora:
Si quieres ver más ejemplos de widgets interactivos que puedes usar para recopilar información, consulta Diseña una tarjeta o un diálogo interactivos.
Cómo recibir datos de widgets interactivos
Cada vez que los usuarios hacen clic en un botón, las apps de Chat reciben un evento de interacción CARD_CLICKED
que contiene información sobre la interacción. La carga útil
CARD_CLICKED
eventos de interacción contienen un common.formInputs
con cualquier valor que ingrese el usuario.
Puedes recuperar los valores del objeto common.formInputs.WIDGET_NAME
, donde WIDGET_NAME es el campo name
que especificaste para el widget.
Los valores se muestran como un tipo de datos específico para el widget (representado como
un objeto Inputs
).
En el siguiente ejemplo, una tarjeta recopila información de contacto mediante un mensaje de texto
entrada, selector de fecha y hora, y widget de entrada de selección:
{
"textInput": {
"name": "contactName",
"label": "First and last name",
"type": "SINGLE_LINE"
}
}, {
"dateTimePicker": {
"name": "contactBirthdate",
"label": "Birthdate",
"type": "DATE_ONLY"
}
}, {
"selectionInput": {
"name": "contactType",
"label": "Contact type",
"type": "RADIO_BUTTON",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
}
Controla el evento de interacción
Cuando un usuario ingresa datos en una tarjeta o un diálogo, tu app de Chat recibe un evento de interacción CARD_CLICKED
de la app de Chat que contiene los valores ingresados por el usuario.
A continuación, se muestra una parte de un evento de interacción CARD_CLICKED
en el que
un usuario ingresó valores para cada widget:
HTTP
{
"type": "CARD_CLICKED",
"common": { "formInputs": {
"contactName": { "stringInputs": {
"value": ["Kai 0"]
}},
"contactBirthdate": { "dateInput": {
"msSinceEpoch": 1000425600000
}},
"contactType": { "stringInputs": {
"value": ["Personal"]
}}
}}
}
Apps Script
{
"type": "CARD_CLICKED",
"common": { "formInputs": {
"contactName": { "": { "stringInputs": {
"value": ["Kai 0"]
}}},
"contactBirthdate": { "": { "dateInput": {
"msSinceEpoch": 1000425600000
}}},
"contactType": { "": { "stringInputs": {
"value": ["Personal"]
}}}
}}
}
Para recibir los datos, tu app de Chat controla de interacción para obtener los valores que los usuarios ingresan en los widgets. En la siguiente tabla, se muestra cómo obtener el valor de un widget de entrada de formulario determinado. Para cada widget, la tabla muestra el tipo de datos que acepta, dónde se almacena el valor en el evento de interacción y un valor de ejemplo.
Widget de entrada de formulario | Tipo de datos de entrada | Valor de entrada del evento de interacción | Valor de ejemplo |
---|---|---|---|
textInput |
stringInputs |
events.common.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
Para obtener el primer valor o el único, events.common.formInputs.contactType.stringInputs.value[0] |
Personal |
dateTimePicker que solo acepta fechas. |
dateInput |
events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch . |
1000425600000 |
Transfiere datos a otra tarjeta
Después de que un usuario envía información desde una tarjeta, es posible que debas devolver tarjetas adicionales para realizar alguna de las siguientes acciones:
- Crea secciones distintas para ayudar a los usuarios a completar formularios más largos.
- Permite que los usuarios obtengan una vista previa y confirmen la información de la tarjeta inicial para que puedan revisar sus respuestas antes de enviarlas.
- Completar de forma dinámica las partes restantes del formulario Por ejemplo, para indicarle que los usuarios creen una cita, una app de Chat podría mostrar una tarjeta inicial en la que se indique el motivo de la cita Luego, se completa otra tarjeta que proporciona los horarios disponibles según la tipo de cita.
Para transferir la entrada de datos de la tarjeta inicial, puedes compilar el widget button
con actionParameters
que contiene el name
del widget y el valor que ingresa el usuario, como se muestra en el siguiente ejemplo:
{
"buttonList": {
"buttons": [{
"text": "Submit",
"onClick": {
"action": {
"function": "openNextCard",
"parameters": [{
"key": "WIDGET_NAME",
"value": "USER_INPUT_VALUE"
}]
}
}
}]
}
}
Donde WIDGET_NAME es el name
del widget y el
USER_INPUT_VALUE es lo que ingresa el usuario. Por ejemplo, para una entrada de texto que recopila el nombre de una persona, el nombre del widget es contactName
y un valor de ejemplo es Kai O
.
Cuando un usuario hace clic en el botón, tu app de Chat recibe
CARD_CLICKED
evento de interacción. Para recuperar los valores, puedes usar el
event.common.parameters
.
A continuación, se muestra un ejemplo de cómo puedes pasar parámetros que contienen datos de entrada del usuario a una función que abre la siguiente tarjeta:
Node.js
// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {
// Open another card.
if (event.common.invokedFunction === "openNextCard") {
const parameters = event.common.parameters;
openNextCard(event);
}
}
Python
# Respond to button clicks on cards or dialogs
if request.get('type') == 'CARD_CLICKED':
if invoked_function := request.get('common', dict()).get('invokedFunction'):
if invoked_function == 'open_next_card':
parameters = request.get('common', dict()).get('parameters'),
return open_next_card(parameters)
Apps Script
// Respond to button clicks on cards or dialogs
function onCardClick(event) {
if (event.common.invokedFunction === "openNextCard") {
const parameters = event.common.parameters;
return openNextCard(parameters);
}
}
Cómo responder un envío de formulario
Después de recibir los datos de un mensaje o diálogo de la tarjeta, la app de Chat responde confirmando el recibo o mostrando un error.
En el siguiente ejemplo, una app de chat envía un mensaje de texto para confirmar que recibió correctamente un formulario enviado desde un mensaje de tarjeta.
Apps Script
function submitCardForm(contactName, contactBirthdate, contactType) {
return {
"text": "You entered the following contact information:\n\n" +
"*Name:* " + contactName + "\n" +
"*Birthdate:* " + contactBirthdate + "\n" +
"*Type:* " + contactType
}
}
Para procesar y cerrar un diálogo, devuelves un objeto ActionResponse
que especifica si deseas enviar un mensaje de confirmación, actualizar el mensaje o la tarjeta originales, o simplemente cerrar el diálogo. Para ver los pasos, consulta
Cierra un diálogo.
Solucionar problemas
Cuando una app de Google Chat o una tarjeta muestran un error, la interfaz de Chat muestra un mensaje que dice "Se produjo un error". o "No se pudo procesar la solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app de Chat la tarjeta produce un resultado inesperado; Por ejemplo, es posible que un mensaje de tarjeta no para que aparezca la opción.
Aunque es posible que no se muestre un mensaje de error en la IU de Chat, los mensajes de error descriptivos y los datos de registro están disponibles para ayudarte a corregir errores cuando se activa el registro de errores de las apps de Chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar problemas y corregir errores de Google Chat.
Temas relacionados
- Consulta el ejemplo de Administrador de contactos. una app de Chat que les pide a los usuarios que completen formulario de contacto a partir de mensajes y diálogos de tarjetas.
- Cómo abrir diálogos interactivos