Cómo agregar elementos interactivos de la IU a las tarjetas

En esta página, se explica cómo agregar widgets y elementos de la IU a las tarjetas para que los usuarios puedan interactuar con tu app de Google Chat, por ejemplo, haciendo clic en un botón o enviando información.

Las apps de chat pueden usar las siguientes interfaces de Chat para compilar tarjetas interactivas:

  • Mensajes que contienen una o más tarjetas.
  • Páginas principales: Es una tarjeta que aparece en la pestaña Página principal en los mensajes directos de la app de Chat.
  • Diálogos, que son tarjetas que se abren en una ventana nueva desde mensajes y páginas principales.

Cuando los usuarios interactúan con las tarjetas, las apps de Chat pueden usar los datos que reciben para procesar y responder según corresponda. Para obtener más información, consulta Cómo recopilar y procesar información de los usuarios de Google Chat.

Usa el Creador de tarjetas para diseñar y obtener una vista previa de las interfaces de usuario y de mensajería de las apps de Chat:

Abre el Creador de tarjetas

Requisitos previos

Una app de Google Chat habilitada para funciones interactivas Para crear una app de Chat interactiva, completa una de las siguientes guías de inicio rápido según la arquitectura de app que quieras usar:

Agrega un botón

El widget ButtonList muestra un conjunto de botones. Los botones pueden mostrar texto, un ícono o ambos. Cada Button admite una acción OnClick que se produce cuando los usuarios hacen clic en el botón. Por ejemplo:

  • Abre un hipervínculo con OpenLink para proporcionarles a los usuarios información adicional.
  • Ejecuta un action que ejecute una función personalizada, como llamar a una API.

Para la accesibilidad, los botones admiten texto alternativo.

Cómo agregar un botón que ejecute una función personalizada

La siguiente es una tarjeta que consta de un widget ButtonList con dos botones. Con un solo botón, se abre la documentación para desarrolladores de Google Chat en una pestaña nueva. El otro botón ejecuta una función personalizada llamada goToView() y pasa el parámetro viewType="BIRD EYE VIEW".

Cómo agregar un botón con el estilo de Material Design

A continuación, se muestra un conjunto de botones con diferentes estilos de botones de Material Design.

Para aplicar el estilo de Material Design, no incluyas el atributo "color".

Agrega un botón con un color personalizado y uno desactivado

Puedes configurar "disabled": "true" para evitar que los usuarios hagan clic en un botón.

A continuación, se muestra una tarjeta que consta de un widget ButtonList con dos botones. Un botón usa el campo Color para personalizar el color de fondo del botón. El otro botón se desactiva con el campo Disabled, lo que evita que el usuario haga clic en el botón y ejecute la función.

Cómo agregar un botón con un ícono

A continuación, se muestra una tarjeta que consta de un widget ButtonList con dos widgets de ícono Button. Un botón usa el campo knownIcon para mostrar el ícono de correo electrónico integrado de Google Chat. El otro botón usa el campo iconUrl para mostrar un widget de ícono personalizado.

Cómo agregar un botón con un ícono y texto

A continuación, se muestra una tarjeta que consta de un widget ButtonList que le solicita al usuario que envíe un correo electrónico. El primer botón muestra un ícono de correo electrónico y el segundo muestra texto. El usuario puede hacer clic en el ícono o en el botón de texto para ejecutar la función sendEmail.

Personaliza el botón para una sección plegable

Personaliza el botón de control que contrae y expande secciones dentro de una tarjeta. Elige entre una variedad de íconos o imágenes para representar visualmente el contenido de la sección, lo que facilita que los usuarios comprendan la información y que interactúen con ella.

Agrega un menú ampliado

Se puede usar Overflow menu en las tarjetas de Chat para ofrecer opciones y acciones adicionales. Te permite incluir más opciones sin desordenar la interfaz de la tarjeta, lo que garantiza un diseño limpio y organizado.

Agrega una lista de chips

El widget ChipList proporciona una forma versátil y visualmente atractiva de mostrar información. Usa listas de chips para representar etiquetas, categorías y otros datos relevantes, lo que facilita a los usuarios navegar por tu contenido y, además, interactuar con él.

Recopilar información de los usuarios

En esta sección, se explica cómo agregar widgets que recopilan información, como texto o selecciones.

Para obtener información sobre cómo procesar lo que ingresan los usuarios, consulta Cómo recopilar y procesar información de los usuarios de Google Chat.

Cómo recopilar texto

El widget TextInput proporciona un campo en el que los usuarios pueden ingresar texto. El widget admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes, y acciones de cambio, que son Actions que se ejecutan cuando se produce un cambio en el campo de entrada de texto, como cuando un usuario agrega o borra texto.

Cuando necesites recopilar datos abstractos o desconocidos de los usuarios, usa este widget de TextInput. Para recopilar datos definidos de los usuarios, usa el widget SelectionInput.

La siguiente es una tarjeta que consta de un widget TextInput:

Recopila fechas o horas

El widget DateTimePicker permite que los usuarios ingresen una fecha, una hora o ambas. También pueden usar el selector para seleccionar fechas y horas. Si los usuarios ingresan una fecha o hora no válidas, el selector muestra un error que les solicita que ingresen la información correctamente.

A continuación, se muestra una tarjeta que consta de tres tipos diferentes de widgets DateTimePicker:

Permite que los usuarios seleccionen elementos

El widget SelectionInput proporciona un conjunto de elementos seleccionables, como casillas de verificación, botones de selección, interruptores o un menú desplegable. Puedes usar este widget para recopilar datos definidos y estandarizados de los usuarios. Para recopilar datos no definidos de los usuarios, usa el widget TextInput.

El widget SelectionInput admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes, y acciones de cambio, que son Actions que se ejecutan cuando se produce un cambio en un campo de entrada de selección, como cuando un usuario selecciona o anula la selección de un elemento.

Las apps de chat pueden recibir y procesar el valor de los elementos seleccionados. Para obtener más información sobre cómo trabajar con entradas de formularios, consulta Cómo procesar la información que ingresan los usuarios.

En esta sección, se proporcionan ejemplos de tarjetas que usan el widget SelectionInput. En los ejemplos, se usan diferentes tipos de entradas de sección:

Cómo agregar una casilla de verificación

A continuación, se muestra una tarjeta que le pide al usuario que especifique si un contacto es profesional, personal o ambos, con un widget SelectionInput que usa casillas de verificación:

Cómo agregar un botón de selección

A continuación, se muestra una tarjeta que le pide al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput que usa botones de selección:

Agrega un interruptor

A continuación, se muestra una tarjeta que le solicita al usuario que especifique si un contacto es profesional, personal o ambos con un widget SelectionInput que usa interruptores:

A continuación, se muestra una tarjeta que le pide al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput que usa un menú desplegable:

Cómo agregar un menú de selección múltiple

A continuación, se muestra una tarjeta en la que se le pide al usuario que seleccione contactos en un menú de selección múltiple:

Puedes propagar elementos para un menú de selección múltiple desde las siguientes fuentes de datos en Google Workspace:

  • Usuarios de Google Workspace: Solo puedes propagar usuarios dentro de la misma organización de Google Workspace.
  • Espacios de Chat: El usuario que ingresa elementos en el menú de selección múltiple solo puede ver y seleccionar los espacios a los que pertenece dentro de su organización de Google Workspace.

Para usar las fuentes de datos de Google Workspace, debes especificar el campo platformDataSource. A diferencia de otros tipos de entradas de selección, omites los objetos SectionItem, ya que estos elementos de selección se obtienen de forma dinámica de Google Workspace.

En el siguiente código, se muestra un menú de selección múltiple de usuarios de Google Workspace. Para propagar los usuarios, la entrada de selección establece commonDataSource en USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

En el siguiente código, se muestra un menú de selección múltiple de espacios de Chat. Para propagar espacios, la entrada de selección especifica el campo hostAppDataSource. El menú de selección múltiple también establece defaultToCurrentSpace en true, lo que hace que el espacio actual sea la selección predeterminada en el menú:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Los menús de selección múltiple también pueden propagar elementos de una fuente de datos externa o de terceros. Por ejemplo, puedes usar menús de selección múltiple para ayudar a un usuario a elegir entre una lista de clientes potenciales de ventas de un sistema de administración de relaciones con clientes (CRM).

Para usar una fuente de datos externa, debes usar el campo externalDataSource para especificar una función que muestre elementos de la fuente de datos.

Para reducir las solicitudes a una fuente de datos externa, puedes incluir elementos sugeridos que aparecen en el menú de selección múltiple antes de que los usuarios escriban en el menú. Por ejemplo, puedes propagar los contactos buscados recientemente del usuario. Para propagar elementos sugeridos desde una fuente de datos externa, especifica objetos SelectionItem.

En el siguiente código, se muestra un menú de selección múltiple de elementos de un conjunto externo de contactos para el usuario. El menú muestra un contacto de forma predeterminada y ejecuta la función getContacts para recuperar y propagar elementos de la fuente de datos externa:

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

En el caso de las fuentes de datos externas, también puedes completar automáticamente los elementos que los usuarios comienzan a escribir en el menú de selección múltiple. Por ejemplo, si un usuario comienza a escribir Atl para un menú que propaga ciudades de Estados Unidos, tu app de chat puede sugerir automáticamente Atlanta antes de que el usuario termine de escribir. Puedes autocompletar hasta 100 elementos.

Para autocompletar elementos, crea una función que consulte la fuente de datos externa y muestre elementos cada vez que un usuario escriba en el menú de selección múltiple. La función debe hacer lo siguiente:

  • Pasa un objeto de evento que represente la interacción del usuario con el menú.
  • Identifica que el valor de invokedFunction del evento de interacción coincida con la función del campo externalDataSource.
  • Cuando las funciones coincidan, muestra los elementos sugeridos de la fuente de datos externa. Para sugerir elementos en función de lo que el usuario escribe, obtén el valor de la clave autocomplete_widget_query. Este valor representa lo que el usuario escribe en el menú.

El siguiente código completa automáticamente los elementos de un recurso de datos externo. Con el ejemplo anterior, la app de Chat sugiere elementos según el momento en que se activa la función getContacts:

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Valida los datos ingresados en las tarjetas

En esta página, se explica cómo validar los datos que se ingresan al action y los widgets de una tarjeta. Por ejemplo, puedes validar que un campo de entrada de texto tenga texto ingresado por el usuario o que contenga una cantidad determinada de caracteres.

Configura los widgets necesarios para realizar acciones

Como parte del action de la tarjeta, agrega nombres de los widgets que necesita una acción a su lista requiredWidgets.

Si alguno de los widgets enumerados aquí no tiene un valor cuando se invoca esta acción, se cancela el envío de la acción del formulario.

Cuando se configura "all_widgets_are_required": "true" para una acción, esta acción requiere todos los widgets de la tarjeta.

Establece una acción all_widgets_are_required en la selección múltiple

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "value": "contact-1",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 1",
                "bottomText": "Contact one description",
                "selected": false
              },
              {
                "value": "contact-2",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 2",
                "bottomText": "Contact two description",
                "selected": false
              },
              {
                "value": "contact-3",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 3",
                "bottomText": "Contact three description",
                "selected": false
              },
              {
                "value": "contact-4",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 4",
                "bottomText": "Contact four description",
                "selected": false
              },
              {
                "value": "contact-5",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 5",
                "bottomText": "Contact five description",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}
Establece una acción all_widgets_are_required en dateTimePicker

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}
Establece una acción all_widgets_are_required en el menú desplegable

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

Cómo establecer la validación para un widget de entrada de texto

En el campo de validación del widget textInput, se puede especificar el límite de caracteres y el tipo de entrada para este widget de entrada de texto.

Cómo establecer un límite de caracteres para un widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}
Cómo establecer el tipo de entrada para un widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

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 puede procesar tu 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 la tarjeta.

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.