Selection input

The SelectionInput widget provides a set of selectable items, such as checkboxes, radio buttons, switches, or a dropdown menu. You can use this widget to collect defined and standardized data from users. To collect undefined data from users, use the TextInput widget instead.

The SelectionInput widget supports suggestions, which help users enter uniform data, and on-change actions, which are Actions that run when a change occurs in a selection input field, such as a user selecting or un-selecting an item.

Chat apps can receive and process the value of selected items. For details about working with form inputs, see Receive form data.

Examples

This section provides examples of cards that use the SelectionInput widget. The examples use different types of section inputs:

Example 1: checkboxes

The following displays a dialog that asks the user to specify whether a contact is professional and/or personal with a SelectionInput widget that uses checkboxes:

Example 2: radio buttons

The following displays a dialog that asks the user to specify whether a contact is professional or personal with a SelectionInput widget that uses radio buttons:

Example 3: switches

The following displays a dialog that asks the user to specify whether a contact is professional or personal with a SelectionInput widget that uses switches:

The following displays a dialog that asks the user to specify whether a contact is professional or personal with a SelectionInput widget that uses a dropdown menu:

Example 5: multiselect menu

The following displays a dialog that asks the user to select contacts from a multiselect menu:

Additional data sources for multiselect menus

The following section explains how to use multiselect menus to populate data from dynamic sources, such as a Google Workspace application or external data source.

Data sources from Google Workspace

You can populate items for a multiselect menu from the following data sources in Google Workspace:

  • Google Workspace users: You can only populate users within the same Google Workspace organization.
  • Chat spaces: The user inputting items in the multiselect menu can only view and select spaces that they belong to within their Google Workspace organization.

To use Google Workspace data sources, you specify the platformDataSource field. Unlike other selection input types, you omit SectionItem objects, as these selection items are dynamically sourced from Google Workspace.

The following code shows a multiselect menu of Google Workspace users. To populate users, the selection input sets commonDataSource to USER:

JSON

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

The following code shows a multiselect menu of Chat spaces. To populate spaces, the selection input specifies the hostAppDataSource field. The multiselect menu also sets defaultToCurrentSpace to true, which makes the current space the default selection in the menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
Data sources outside of Google Workspace

Multiselect menus can also populate items from a third-party or external data source. For example, you can use multiselect menus to help a user select from a list of sales leads from a customer relationship management (CRM) system.

To use an external data source, you use the externalDataSource field to specify a function that returns items from the data source.

To reduce the requests to an external data source, you can include suggested items that appear in the multiselect menu before users type in the menu. For example, you can populate recently searched contacts for the user. To populate suggested items from an external data source, specify SelectionItem objects.

The following code shows a multiselect menu of items from an external set of contacts for the user. The menu displays one contact by default and runs the function getContacts to retrieve and populate items from the external data source:

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

For external data sources, you can also autocomplete items that users start typing in the multiselect menu. For example, if a user starts typing Atl for a menu that populates cities in the United States, your Chat app can autosuggest Atlanta before the user finishes typing. You can autocomplete up to 100 items.

To autocomplete items, you create a function that queries the external data source and returns items whenever a user types in the multiselect menu. The function must do the following:

  • Pass an event object that represents the user interaction with the menu.
  • Identify that the interaction event's invokedFunction value matches the function from the externalDataSource field.
  • When the functions match, return suggested items from the external data source. To suggest items based on what the user types, get the value for the autocomplete_widget_query key. This value represents what the user types in the menu.

The following code autocompletes items from an external data resource. Using the previous example, the Chat app suggests items based on when the function getContacts is triggered:

Apps Script

apps-script/selection-input/on-widget-update.gs
/**
 * 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
/**
 * 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
            },
          ]
        }
      }
    }
  };
}

JSON representation and fields

JSON representation 
{
  "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.
}
Fields
name

string

The name that identifies the selection input in a form input event.

For details about working with form inputs, see Receive form data.

label

string

The text that appears above the selection input field in the user interface.

Specify text that helps the user enter the information your app needs. For example, if users are selecting the urgency of a work ticket from a drop-down menu, the label might be "Urgency" or "Select urgency".

type

enum (SelectionType)

The type of items that are displayed to users in a SelectionInput widget. Selection types support different types of interactions. For example, users can select one or more checkboxes, but they can only select one value from a dropdown menu.

items[]

object (SelectionItem)

An array of selectable items. For example, an array of radio buttons or checkboxes. Supports up to 100 items.

onChangeAction

object (Action)

If specified, the form is submitted when the selection changes. If not specified, you must specify a separate button that submits the form.

For details about working with form inputs, see Receive form data.

multiSelectMaxSelectedItems

integer

For multiselect menus, the maximum number of items that a user can select. Minimum value is 1 item. If unspecified, defaults to 3 items.

multiSelectMinQueryLength

integer

For multiselect menus, the number of text characters that a user inputs before the Chat app queries autocomplete and displays suggested items in the menu.

If unspecified, defaults to 0 characters for static data sources and 3 characters for external data sources.

Union field multi_select_data_source. Chat apps only. For a multiselect menu, the data source that populates selection items. multi_select_data_source can be only one of the following:
externalDataSource

object (Action)

An external data source, such as a relational data base.

platformDataSource

object (PlatformDataSource)

A data source from Google Workspace.

SelectionType

Enums
CHECK_BOX A set of checkboxes. Users can select one or more checkboxes.
RADIO_BUTTON A set of radio buttons. Users can select one radio button.
SWITCH A set of switches. Users can turn on one or more switches.
DROPDOWN A dropdown menu. Users can select one item from the menu.
MULTI_SELECT

Supported by Chat apps, but not Google Workspace Add-ons.

A multiselect menu for static or dynamic data. From the menu bar, users select one or more items. Users can also input values to populate dynamic data. For example, users can start typing the name of a Google Chat space and the widget autosuggests the space.

To populate items for a multiselect menu, you can use one of the following types of data sources:

  • Static data: Items are specified as SelectionItem objects in the widget. Up to 100 items.
  • Google Workspace data: Items are populated using data from Google Workspace, such as Google Workspace users or Google Chat spaces.
  • External data: Items are populated from an external data source outside of Google Workspace.

For examples of how to implement multiselect menus, see the SelectionInput widget page .

SelectionItem

JSON representation 
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
Fields
text

string

The text that identifies or describes the item to users.

value

string

The value associated with this item. The client should use this as a form input value.

For details about working with form inputs, see Receive form data.

selected

boolean

Whether the item is selected by default. If the selection input only accepts one value (such as for radio buttons or a dropdown menu), only set this field for one item.

startIconUri

string

For multiselect menus, the URL for the icon displayed next to the item's text field. Supports PNG and JPEG files. Must be an HTTPS URL. For example, https://developers.google.com/chat/images/quickstart-app-avatar.png.

bottomText

string

For multiselect menus, a text description or label that's displayed below the item's text field.

Action

An action that describes the behavior when the form is submitted. For example, you can invoke an Apps Script script to handle the form. If the action is triggered, the form values are sent to the server.

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

string

A custom function to invoke when the containing element is clicked or othrwise activated.

For example usage, see Create interactive cards.

parameters[]

object (ActionParameter)

List of action parameters.

loadIndicator

enum (LoadIndicator)

Specifies the loading indicator that the action displays while making the call to the action.

persistValues

boolean

Indicates whether form values persist after the action. The default value is false.

If true, form values remain after the action is triggered. To let the user make changes while the action is being processed, set LoadIndicator to NONE. For card messages in Chat apps, you must also set the action's ResponseType to UPDATE_MESSAGE and use the same cardId from the card that contained the action.

If false, the form values are cleared when the action is triggered. To prevent the user from making changes while the action is being processed, set LoadIndicator to SPINNER.

interaction

enum (Interaction)

Optional. Required when opening a dialog.

What to do in response to an interaction with a user, such as a user clicking a button in a card message.

If unspecified, the app responds by executing an action —like opening a link or running a function—as normal.

By specifying an interaction, the app can respond in special interactive ways. For example, by setting interaction to OPEN_DIALOG, the app can open a dialog. When specified, a loading indicator isn't shown.

Supported by Chat apps, but not Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client.

ActionParameter

List of string parameters to supply when the action method is invoked. For example, consider three snooze buttons: snooze now, snooze one day, or snooze next week. You might use action method = snooze(), passing the snooze type and snooze time in the list of string parameters.

To learn more, see CommonEventObject.

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string

The name of the parameter for the action script.

value

string

The value of the parameter.

LoadIndicator

Specifies the loading indicator that the action displays while making the call to the action.

Enums
SPINNER Displays a spinner to indicate that content is loading.
NONE Nothing is displayed.

Interaction

Optional. Required when opening a dialog.

What to do in response to an interaction with a user, such as a user clicking a button in a card message.

If unspecified, the app responds by executing an action —like opening a link or running a function—as normal.

By specifying an interaction, the app can respond in special interactive ways. For example, by setting interaction to OPEN_DIALOG, the app can open a dialog.

When specified, a loading indicator isn't shown.

Supported by Chat apps, but not Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client.

Enums
INTERACTION_UNSPECIFIED Default value. The action executes as normal.
OPEN_DIALOG

Opens a dialog, a windowed, card-based interface that Chat apps use to interact with users.

Only supported by Chat apps in response to button-clicks on card messages.

Not supported by Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client.

Troubleshoot

When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, see Troubleshoot and fix Google Chat errors.