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:
Example 4: dropdown menu
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 theexternalDataSource
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
Node.js
JSON representation and fields
JSON representation |
---|
{ "name": string, "label": string, "type": enum ( |
Fields | |
---|---|
name
|
The name that identifies the selection input in a form input event. For details about working with form inputs, see Receive form data. |
label
|
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
|
The type of items that are displayed to users in a
|
items[]
|
An array of selectable items. For example, an array of radio buttons or checkboxes. Supports up to 100 items. |
onChangeAction
|
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
|
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
|
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
|
An external data source, such as a relational data base. |
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:
For examples of how to implement multiselect menus, see the
|
SelectionItem
JSON representation |
---|
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string } |
Fields | |
---|---|
text
|
The text that identifies or describes the item to users. |
value
|
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
|
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
|
For multiselect menus, the URL for the icon displayed next to the item's
|
bottomText
|
For multiselect menus, a text description or label that's displayed below the item's
|
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 ( |
Fields | |
---|---|
function
|
A custom function to invoke when the containing element is clicked or othrwise activated. For example usage, see Create interactive cards. |
parameters[]
|
List of action parameters. |
loadIndicator
|
Specifies the loading indicator that the action displays while making the call to the action. |
persistValues
|
Indicates whether form values persist after the action. The default value is
If
If
|
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
By specifying an
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
|
The name of the parameter for the action script. |
value
|
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.