This page explains how to add widgets and UI elements to card or dialog messages so that users can interact with your Google Chat app, such as by clicking a button or submitting information.
Use the Card Builder to design and preview JSON card messages for Chat apps:
Open the Card BuilderPrerequisites
A Google Chat app that's enabled for interactive features. To create an interactive Chat app, complete one of the following quickstarts based on the app architecture that you want to use:
- HTTP service with Google Cloud Functions
- Google Apps Script
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
Add a button
The
ButtonList
widget
displays a set of buttons. Buttons can display text, an
icon, or both text and an icon. Each
Button
supports an
OnClick
action
that occurs when users click the button. For example:
- Open a hyperlink with
OpenLink
, in order to provide users with additional information. - Run an
action
that runs a custom function, like calling an API.
For accessibility, buttons support alternative text.
Add a button that runs a custom function
The following is a card consisting of a ButtonList
widget with two buttons.
One button opens the Google Chat developer documentation in a new tab. The
other button runs a custom function called goToView()
and passes the
viewType="BIRD EYE VIEW"
parameter.
Add a button with Material Design style
The following displays a set of buttons in different Material Design button styles.
To apply Material Design style, don't include the 'color' attribute.
Add a button with custom color and a deactivated button
You can prevent users from clicking a button by setting "disabled": "true"
.
The following displays a card consisting of a ButtonList
widget with two
buttons. One button uses the
Color
field
to customize the button's background
color. The other button is deactivated with the Disabled
field, which
prevents the user from clicking the button and executing the function.
Add a button with an icon
The following displays a card consisting of a ButtonList
widget with two icon
Button
widgets. One button uses the
knownIcon
field to display Google Chat's built-in email icon. The other button uses the
iconUrl
field to display a
custom icon widget.
Add a button with an icon and text
The following displays a card consisting of a ButtonList
widget that prompts
the user to send an email. The first button displays an email icon and the
second button displays text. The user can click either the icon or text
button to run the sendEmail
function.
Add an Overflow Menu
The
Overflow menu
can be used in Chat cards to offer additional options and actions. It lets
you include more options without cluttering the card's interface, ensuring a
clean and organized design.
Add a Chips list
The ChipList
widget provides a versatile and visually appealing way to display information.
Use chip lists to represent tags, categories, or other relevant data, making it
easier for users to navigate and interact with your content.
Add selectable UI elements
The SelectionInput
widget
provides a set of selectable items, such as checkboxes, radio buttons, switches,
or a drop-down 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 Process information inputted by users.
This section provides examples of cards that use the SelectionInput
widget.
The examples use different types of section inputs:
Add a checkbox
The following displays a dialog that asks the user to specify whether a
contact is professional, personal, or both, with a SelectionInput
widget that
uses checkboxes:
Add a radio button
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:
Add a switch
The following displays a dialog that asks the user to specify whether a
contact is professional, personal, or both with a SelectionInput
widget that
uses switches:
Add a drop-down 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 drop-down menu:
Add a multiselect menu
The following displays a dialog that asks the user to select contacts from a multiselect menu:
Use 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, because 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
Add a field in which a user can enter text
The TextInput
widget
provides a field in which users can enter text. The
widget supports suggestions, which help users enter uniform data, and on-change
actions, which are
Actions
that run when a change occurs in the text input field, like a user adding or
deleting text.
When you need to collect abstract or unknown data from users, use this
TextInput
widget. To collect defined data from users, use the
SelectionInput
widget instead.
To process the text that users input, see Process information inputted by users.
The following is a card consisting of a TextInput
widget:
Let a user pick a date and time
The
DateTimePicker
widget
lets users input a date, a time, or both a date and
a time. Or, users can use the picker to select dates and times. If users input
an invalid date or time, the picker shows an error that prompts users to input
the information correctly.
To process the date and time values that users input, see Process information inputted by users.
The following displays a card consisting of three different types of
DateTimePicker
widgets:
Validate data inputted to cards
This page explains how to validate data inputted to a card's action
and widgets.
For example, you can validate that a text input field has text entered by the
user, or that it contains a certain number of characters.
Set required widgets for actions
As part of the card's action
,
add names of widgets that an action needs to its requiredWidgets
list.
If any widgets listed here don't have a value when this action is invoked, then the form action submission is cancelled.
When "all_widgets_are_required": "true"
is set for an action, then all widgets
in the card are required by this action.
Set an all_widgets_are_required
action in multiselect
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
}
]
}
}
]
}
]
}
Set an all_widgets_are_required
action in 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"
}
}
]
}
]
}
Set an all_widgets_are_required
action in drop-down menu
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
}
]
}
}
]
}
]
}
Set the validation for a text input widget
In the textInput
widget's validation field, it can specify the character limit and input type for
this text input widget.
Set a character limit for a text input widget
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
}
}
}
]
}
]
}
Set the input type for a text input widget
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"
}
}
}
]
}
]
}
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.