Entrada de selección

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 en su lugar.

El widget SelectionInput admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes, y acciones ante cambios (Actions) que se ejecutan cuando se produce un cambio en un campo de entrada de selección, por ejemplo, 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 detalles sobre cómo trabajar con entradas de formularios, consulta Recibe datos de formularios.

Ejemplos

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:

• Casillas de verificación
• Botones de selección
• Interruptores
• Menú desplegable
• Menú de selección múltiple

Ejemplo 1: casillas de verificación

A continuación, se muestra un diálogo que le solicita al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput que usa casillas de verificación:

Ejemplo 2: botones de selección

A continuación, se muestra un diálogo que le solicita al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput que usa botones de selección:

Ejemplo 3: interruptores

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

Ejemplo 4: menú desplegable

A continuación, se muestra un diálogo que le solicita al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput que usa un menú desplegable:

Ejemplo 5: menú de selección múltiple

A continuación, se muestra un diálogo en el que se le solicita al usuario que seleccione contactos de un menú de selección múltiple:

Fuentes de datos adicionales para menús de selección múltiple

En la siguiente sección, se explica cómo usar menús de selección múltiple para propagar datos de fuentes dinámicas, como una aplicación de Google Workspace o una fuente de datos externa.

Fuentes de datos de Google Workspace

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 pertenecen dentro de su organización de Google Workspace.

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

El siguiente código muestra un menú de selección múltiple de usuarios de Google Workspace. Para propagar 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 del menú:

JSON

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

Fuentes de datos fuera de Google Workspace

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 seleccionar de una lista de posibles clientes comerciales de un sistema de administración de relaciones con clientes (CRM).

Si quieres usar una fuente de datos externa, usa 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 aparezcan en el menú de selección múltiple antes de que los usuarios escriban en el menú. Por ejemplo, puedes propagar los contactos que buscó el usuario recientemente. 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:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

En el caso de las fuentes de datos externas, también puedes autocompletar 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, debes crear 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 invokedFunction del evento de interacción coincide con la función del campo externalDataSource.
• Cuando las funciones coinciden, se muestran elementos sugeridos de la fuente de datos externa. Para sugerir elementos en función de lo que escribe el usuario, 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 elementos de un recurso de datos externo. Con el ejemplo anterior, la app de Chat sugiere elementos según el momento en el que se activa la función getContacts:

Apps Script

apps-script/selection-input/on-widget-update.gs

Ver en GitHub

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js

Ver en GitHub

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Representación de JSON y campos

Representación JSON

{ "name": string, "label": string, "type": enum (SelectionType), "items": [ { object (SelectionItem) } ], "onChangeAction": { object (Action) }, "multiSelectMaxSelectedItems": integer, "multiSelectMinQueryLength": integer, // Union field multi_select_data_source can be only one of the following: "externalDataSource": { object (Action) }, "platformDataSource": { object (PlatformDataSource) } // End of list of possible types for union field multi_select_data_source. }

Campos
name	string Es el nombre que identifica la entrada de selección en un evento de entrada de formulario. Para obtener información detallada sobre cómo trabajar con entradas de formularios, consulta Recibe datos de formularios.
label	string El texto que aparece sobre el campo de entrada de selección en la interfaz de usuario. Especifica un texto que ayude al usuario a ingresar la información que necesita tu app. Por ejemplo, si los usuarios seleccionan la urgencia de un ticket de trabajo en un menú desplegable, la etiqueta podría ser "Urgencia" o "Seleccionar urgencia".
type	enum (SelectionType) Es el tipo de elementos que se muestran a los usuarios en un widget SelectionInput. Los tipos de selección admiten diferentes tipos de interacciones. Por ejemplo, los usuarios pueden seleccionar una o más casillas de verificación, pero solo pueden seleccionar un valor de un menú desplegable.
items[]	object (SelectionItem) Es un array de elementos seleccionables. Por ejemplo, un array de botones de selección o casillas de verificación. Admite hasta 100 elementos.
onChangeAction	object (Action) Si se especifica, el formulario se envía cuando cambia la selección. Si no se especifica, debes especificar otro botón que envíe el formulario. Para obtener información detallada sobre cómo trabajar con entradas de formularios, consulta Recibe datos de formularios.
multiSelectMaxSelectedItems	integer En el caso de los menús de selección múltiple, la cantidad máxima de elementos que puede seleccionar un usuario. El valor mínimo es 1 artículo. Si no se especifica, el valor predeterminado es 3 elementos.
multiSelectMinQueryLength	integer En los menús de selección múltiple, la cantidad de caracteres de texto que un usuario ingresa antes de que la app de Chat consulte se autocompleta y muestra los elementos sugeridos en el menú. Si no se especifica, el valor predeterminado es 0 caracteres para las fuentes de datos estáticas y 3 caracteres para las fuentes de datos externas.
Campo de unión multi_select_data_source. Solo para apps de Chat. Para un menú de selección múltiple, es la fuente de datos que propaga los elementos de selección. multi_select_data_source solo puede ser una de las siguientes opciones:
externalDataSource	object (Action) Una fuente de datos externa, como una base de datos relacional.
platformDataSource	object (PlatformDataSource) Una fuente de datos de Google Workspace.

SelectionType

Enumeradores
CHECK_BOX	Un conjunto de casillas de verificación. Los usuarios pueden seleccionar una o más casillas de verificación.
RADIO_BUTTON	Un conjunto de botones de selección. Los usuarios pueden elegir un botón de selección.
SWITCH	Un conjunto de interruptores. Los usuarios pueden activar uno o más interruptores.
DROPDOWN	Un menú desplegable Los usuarios pueden seleccionar un elemento del menú.
MULTI_SELECT	Son compatibles con las apps de Chat, pero no los complementos de Google Workspace. Un menú de selección múltiple para datos estáticos o dinámicos. En la barra de menú, los usuarios seleccionan uno o más elementos. Los usuarios también pueden ingresar valores para propagar datos dinámicos. Por ejemplo, los usuarios pueden comenzar a escribir el nombre de un espacio de Google Chat y el widget lo sugerirá automáticamente. Para propagar los elementos de un menú de selección múltiple, puedes usar uno de los siguientes tipos de fuentes de datos: Datos estáticos: los elementos se especifican como objetos SelectionItem en el widget. Hasta 100 elementos. Datos de Google Workspace: Los elementos se propagan con datos de Google Workspace, como los usuarios de Google Workspace o los espacios de Google Chat. Datos externos: Los elementos se propagan desde una fuente de datos externa a Google Workspace. Para ver ejemplos de cómo implementar menús de selección múltiple, consulta la página del widget SelectionInput .

SelectionItem

Representación JSON
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string }

Campos
text	string Es el texto que identifica o describe el elemento a los usuarios.
value	string El valor asociado con este elemento. El cliente debe usar esto como un valor de entrada de formulario. Para obtener información detallada sobre cómo trabajar con entradas de formularios, consulta Recibe datos de formularios.
selected	boolean Indica si el elemento está seleccionado de forma predeterminada. Si la entrada de selección solo acepta un valor (como los botones de selección o un menú desplegable), establece este campo solo para un elemento.
startIconUri	string En el caso de los menús de selección múltiple, la URL del ícono se muestra junto al campo text del elemento. Admite archivos PNG y JPEG. Debe ser una URL HTTPS. Por ejemplo, https://developers.google.com/chat/images/quickstart-app-avatar.png.
bottomText	string Para los menús de selección múltiple, una descripción de texto o etiqueta que se muestra debajo del campo text del elemento.

Acción

Una acción que describe el comportamiento cuando se envía el formulario. Por ejemplo, puedes invocar una secuencia de comandos de Apps Script para controlar el formulario. Si se activa la acción, los valores del formulario se envían al servidor.

Representación JSON
{ "function": string, "parameters": [ { object (ActionParameter) } ], "loadIndicator": enum (LoadIndicator), "persistValues": boolean, "interaction": enum (Interaction) }

Campos
function	string Es una función personalizada que se invoca cuando se hace clic en el elemento contenedor o se activa de otro modo. Para ver ejemplos de uso, consulta Cómo crear tarjetas interactivas.
parameters[]	object (ActionParameter) Lista de parámetros de acción.
loadIndicator	enum (LoadIndicator) Especifica el indicador de carga que muestra la acción mientras se realiza la llamada a la acción.
persistValues	boolean Indica si los valores del formulario persisten después de la acción. El valor predeterminado es false. Si es true, los valores del formulario permanecen después de que se activa la acción. Para permitir que el usuario realice cambios mientras se procesa la acción, configura LoadIndicator como NONE. Para los mensajes de tarjetas en las apps de Chat, también debes configurar el ResponseType de la acción en UPDATE_MESSAGE y usar el mismo cardId de la tarjeta que contenía la acción. Si es false, los valores del formulario se borran cuando se activa la acción. Para evitar que el usuario haga cambios mientras se procesa la acción, establece LoadIndicator en SPINNER.
interaction	enum (Interaction) Opcional. Es obligatorio al abrir un diálogo. Qué hacer en respuesta a una interacción con un usuario, como cuando un usuario hace clic en un botón en un mensaje de tarjeta. Si no se especifica, la app responde con la ejecución normal de un elemento action, como abrir un vínculo o ejecutar una función. Cuando se especifica un interaction, la app puede responder de maneras interactivas especiales. Por ejemplo, si estableces interaction en OPEN_DIALOG, la app podrá abrir un diálogo. Cuando se especifica, no se muestra un indicador de carga. Son compatibles con las apps de Chat, pero no los complementos de Google Workspace. Si se especifica para un complemento, se quitará toda la tarjeta y no se mostrará nada en el cliente.

ActionParameter

Lista de parámetros de cadena que se deben proporcionar cuando se invoca el método de acción. Por ejemplo, considera tres botones para posponer: Posponer ahora, Posponer un día o Posponer la próxima semana. Puedes usar action method = snooze() y pasar el tipo y el tiempo de posposición en la lista de parámetros de cadena.

Para obtener más información, consulta CommonEventObject.

Representación JSON
{ "key": string, "value": string }

Campos
key	string El nombre del parámetro de la secuencia de comandos de acción.
value	string El valor del parámetro.

LoadIndicator

Especifica el indicador de carga que muestra la acción mientras se realiza la llamada a la acción.

Enumeradores
SPINNER	Muestra un ícono giratorio para indicar que se está cargando el contenido.
NONE	No se muestra nada.

Interacción

Opcional. Es obligatorio al abrir un diálogo.

Qué hacer en respuesta a una interacción con un usuario, como cuando un usuario hace clic en un botón en un mensaje de tarjeta.

Si no se especifica, la app responde con la ejecución normal de un elemento action, como abrir un vínculo o ejecutar una función.

Cuando se especifica un interaction, la app puede responder de maneras interactivas especiales. Por ejemplo, si estableces interaction en OPEN_DIALOG, la app podrá abrir un diálogo.

Cuando se especifica, no se muestra un indicador de carga.

Son compatibles con las apps de Chat, pero no los complementos de Google Workspace. Si se especifica para un complemento, se quitará toda la tarjeta y no se mostrará nada en el cliente.

Enumeradores
INTERACTION_UNSPECIFIED	Valor predeterminado action se ejecuta con normalidad.
OPEN_DIALOG	Abre un diálogo, una interfaz con ventanas y basadas en tarjetas que usan las apps de Chat para interactuar con los usuarios. Solo es compatible con apps de Chat en respuesta a clics en botones en mensajes de tarjetas. No es compatible con los complementos de Google Workspace. Si se especifica para un complemento, se quitará toda la tarjeta y no se mostrará nada en el cliente.

Solución de problemas

Cuando una app o tarjeta de Google Chat devuelve un error, la interfaz de Chat muestra un mensaje que dice “Se produjo un error” o “No se pudo 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 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 de las apps de chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar y corregir errores de Google Chat.