Recopilar y procesar información de los usuarios de Google Chat

En esta guía, se describe cómo las apps de Google Chat pueden recopilar y procesar información de los usuarios mediante la compilación de entradas de formularios en interfaces basadas en tarjetas.

Un diálogo con una variedad de widgets diferentes. — **Figura 1**: Una app de Chat de muestra que abre un diálogo para recopilar información de contacto.

**Figura 1**: Una app de Chat de muestra que abre un diálogo para recopilar información de contacto.

Las apps de Chat solicitan información de los usuarios para realizar acciones dentro o fuera de Chat, incluso de las siguientes maneras:

Establece 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.
Crea o actualiza información en otras aplicaciones de Google Workspace. 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

Node.js

Una app de Google Chat que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Python

Una app de Google Chat que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Java

Una app de Google Chat que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Apps Script

Una app de Google Chat que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.

Compila 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 son tarjetas que aparecen en la pestaña Página principal en mensajes directos con la app de Chat
Diálogos, que son tarjetas que se abren en una ventana nueva desde mensajes y páginas principales

Las apps de Chat pueden compilar las tarjetas con los siguientes widgets:

Widgets de entrada de formulario que solicitan información de los usuarios (opcional) Puedes agregar validación a los widgets de entrada de formulario para asegurarte de que los usuarios ingresen y formateen la información correctamente. Las apps de Chat pueden usar los siguientes widgets de entrada de formulario:
- Entradas de texto (textInput) para texto de formato libre o sugerido.
- Las 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 pueden 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 entradas de fecha y hora
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 entonces procesar la información que recibe.

En el siguiente ejemplo, una tarjeta recopila información de contacto con una entrada de texto, un selector de fecha y hora, y una entrada de selección:

Para ver un ejemplo de una app de Chat que usa este formulario de contacto, consulta el siguiente código:

Node.js

node/contact-form-app/index.js

Ver en GitHub

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py

Ver en GitHub

# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Ver en GitHub

// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs

Ver en GitHub

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Para obtener más ejemplos de widgets interactivos que puedes usar para recopilar información, consulta Diseña una tarjeta o un diálogo interactivo.

Recibe 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 que depende de la ubicación del botón:

Si el botón está en un mensaje o diálogo, las apps de Chat reciben un CARD_CLICKED evento de interacción que contiene información sobre la interacción. La carga útil de CARD_CLICKED eventos de interacción contiene un common.formInputs objeto con los valores que ingresa el usuario.

Puedes recuperar los valores del objeto common.formInputs.WIDGET_NAME, donde WIDGET_NAME es el name campo que especificaste para el widget. Los valores se muestran como un tipo de datos específico para el widget (representado como un Inputs objeto).

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"]
    }}}
  }}
}

Si el botón está en una página principal, las apps de Chat reciben un SUBMIT_FORM evento de interacción. La carga útil del evento de interacción contiene un commonEventObject.formInputs objeto con los valores que ingresa el usuario.

Puedes recuperar los valores del objeto commonEventObject.formInputs.WIDGET_NAME, donde WIDGET_NAME es el name campo que especificaste para el widget. Los valores se muestran como un tipo de datos específico para el widget (representado como un Inputs objeto).

A continuación, se muestra una parte de un evento de interacción SUBMIT_FORM en el que un usuario ingresó valores para cada widget:

HTTP

{
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script

{
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

Para recibir los datos, tu app de Chat controla el evento 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 el widget, 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`	`event.common.formInputs.contactName.stringInputs.value[0]`	`Kai O`
`selectionInput`	`stringInputs`	Para obtener el primer valor o el único, `event.common.formInputs.contactType.stringInputs.value[0]`	`Personal`
`dateTimePicker` que solo acepta fechas	`dateInput`	`event.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 mostrar tarjetas adicionales para realizar cualquiera de las siguientes acciones:

Ayudar a los usuarios a completar formularios más largos mediante la creación de secciones distintas
Permitir que los usuarios obtengan una vista previa de la información de la tarjeta inicial y la confirmen para que puedan revisar sus respuestas antes de enviarlas
Propagar de forma dinámica las partes restantes del formulario Por ejemplo, para solicitar a los usuarios que creen una cita, una app de Chat podría mostrar una tarjeta inicial que solicite el motivo de la cita y, luego, propagar otra tarjeta que proporcione horarios disponibles según el tipo de cita.

Para transferir la entrada de datos de la tarjeta inicial, puedes compilar el button widget con actionParameters que contengan el name del widget y el valor que ingresa el usuario, como se muestra en el siguiente ejemplo:

Node.js

node/contact-form-app/index.js

Ver en GitHub

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py

Ver en GitHub

'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Ver en GitHub

new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs

Ver en GitHub

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Cuando un usuario hace clic en el botón, tu app de Chat recibe un CARD_CLICKED evento de interacción del que puedes recibir datos.

Responde a un envío de formulario

Después de recibir los datos de un mensaje de tarjeta o diálogo, la app de Chat responde confirmando la recepción 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 diálogo o un mensaje de tarjeta.

Node.js

node/contact-form-app/index.js

Ver en GitHub

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Python

python/contact-form-app/main.py

Ver en GitHub

contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Ver en GitHub

String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

Apps Script

apps-script/contact-form-app/main.gs

Ver en GitHub

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Para procesar y cerrar un diálogo, debes mostrar un ActionResponse objeto que especifique si deseas enviar un mensaje de confirmación, actualizar el mensaje o la tarjeta originales, o simplemente cerrar el diálogo. Para conocer los pasos, consulta Cierra un diálogo.

Solucionar problemas

Cuando una app o tarjeta de Google Chat muestra 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 o la tarjeta de Chat producen un resultado inesperado; por ejemplo, es posible que no aparezca un mensaje de tarjeta.

Aunque es posible que no se muestre un mensaje de error en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando se activa el registro de errores para las apps de Chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Soluciona y corrige errores de Google Chat.

Consulta la muestra del Administrador de contactos, que es una app de Chat que solicita a los usuarios que completen un formulario de contacto desde mensajes de tarjetas y diálogos.
Abre diálogos interactivos

Recopilar y procesar información de los usuarios de Google Chat Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Requisitos previos

Node.js

Python

Java

Apps Script

Compila formularios con tarjetas

Node.js

Python

Java

Apps Script

Recibe datos de widgets interactivos

HTTP

Apps Script

HTTP

Apps Script

Transfiere datos a otra tarjeta

Node.js

Python

Java

Apps Script

Responde a un envío de formulario

Node.js

Python

Java

Apps Script

Solucionar problemas

Temas relacionados

Recopilar y procesar información de los usuarios de Google Chat