Namespace Google.Apps.Card.V1
Classes
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.
Action.Types
Container for nested types declared in the Action message type.
Action.Types.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.
BorderStyle
The style options for the border of a card or widget, including the border type and color.
BorderStyle.Types
Container for nested types declared in the BorderStyle message type.
Button
A text, icon, or text and icon button that users can click. For an example in Google Chat apps, see Add a button.
To make an image a clickable button, specify an
[Image][google.apps.card.v1.Image] (not an
[ImageComponent][google.apps.card.v1.ImageComponent]) and set an
onClick action.
Button.Types
Container for nested types declared in the Button message type.
ButtonList
A list of buttons layed out horizontally. For an example in Google Chat apps, see Add a button.
Card
A card interface displayed in a Google Chat message or Google Workspace add-on.
Cards support a defined layout, interactive UI elements like buttons, and rich media like images. Use cards to present detailed information, gather information from users, and guide users to take a next step.
To learn how to build cards, see the following documentation:
- For Google Chat apps, see Design the components of a card or dialog.
- For Google Workspace add-ons, see Card-based interfaces.
Note: You can add up to 100 widgets per card. Any widgets beyond this limit are ignored. This limit applies to both card messages and dialogs in Google Chat apps, and to cards in Google Workspace add-ons.
Example: Card message for a Google Chat app
To create the sample card message in Google Chat, use the following JSON:
{
"cardsV2": [
{
"cardId": "unique-card-id",
"card": {
"header": {
"title": "Sasha",
"subtitle": "Software Engineer",
"imageUrl":
"https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha"
},
"sections": [
{
"header": "Contact Info",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"decoratedText": {
"startIcon": {
"knownIcon": "EMAIL"
},
"text": "sasha@example.com"
}
},
{
"decoratedText": {
"startIcon": {
"knownIcon": "PERSON"
},
"text": "<font color=\"#80e27e\">Online</font>"
}
},
{
"decoratedText": {
"startIcon": {
"knownIcon": "PHONE"
},
"text": "+1 (555) 555-1234"
}
},
{
"buttonList": {
"buttons": [
{
"text": "Share",
"onClick": {
"openLink": {
"url": "https://example.com/share"
}
}
},
{
"text": "Edit",
"onClick": {
"action": {
"function": "goToView",
"parameters": [
{
"key": "viewType",
"value": "EDIT"
}
]
}
}
}
]
}
}
]
}
]
}
}
]
}
Card.Types
Container for nested types declared in the Card message type.
Card.Types.CardAction
A card action is the action associated with the card. For example, an invoice card might include actions such as delete invoice, email invoice, or open the invoice in a browser.
Card.Types.CardFixedFooter
A persistent (sticky) footer that that appears at the bottom of the card.
Setting fixedFooter without specifying a primaryButton or a
secondaryButton causes an error.
For Chat apps, you can use fixed footers in dialogs, but not card messages. For an example in Google Chat apps, see Add a persistent footer.
Card.Types.CardHeader
Represents a card header. For an example in Google Chat apps, see Add a header.
Card.Types.NestedWidget
A list of widgets that can be displayed in a containing layout, such
as a CarouselCard.
Google Chat apps:
Card.Types.Section
A section contains a collection of widgets that are rendered vertically in the order that they're specified.
Carousel
A carousel, also known as a slider, rotates and displays a list of widgets in a slideshow format, with buttons navigating to the previous or next widget.
For example, this is a JSON representation of a carousel that contains three text paragraph widgets.
{
"carouselCards": [
{
"widgets": [
{
"textParagraph": {
"text": "First text paragraph in carousel",
}
}
]
},
{
"widgets": [
{
"textParagraph": {
"text": "Second text paragraph in carousel",
}
}
]
},
{
"widgets": [
{
"textParagraph": {
"text": "Third text paragraph in carousel",
}
}
]
}
]
}
Carousel.Types
Container for nested types declared in the Carousel message type.
Carousel.Types.CarouselCard
A card that can be displayed as a carousel item. Google Chat apps:
Chip
A text, icon, or text and icon chip that users can click.
ChipList
A list of chips layed out horizontally, which can either scroll horizontally or wrap to the next line.
ChipList.Types
Container for nested types declared in the ChipList message type.
CollapseControl
Represent an expand and collapse control.
Columns
The Columns widget displays up to 2 columns in a card or dialog. You can
add widgets to each column; the widgets appear in the order that they are
specified. For an example in Google Chat apps, see
Display cards and dialogs in
columns.
The height of each column is determined by the taller column. For example, if the first column is taller than the second column, both columns have the height of the first column. Because each column can contain a different number of widgets, you can't define rows or align widgets between the columns.
Columns are displayed side-by-side. You can customize the width of each
column using the HorizontalSizeStyle field. If the user's
screen width is too narrow, the second column wraps below the first:
- On web, the second column wraps if the screen width is less than or equal to 480 pixels.
- On iOS devices, the second column wraps if the screen width is less than or equal to 300 pt.
- On Android devices, the second column wraps if the screen width is less than or equal to 320 dp.
To include more than two columns, or to use rows, use the
[Grid][google.apps.card.v1.Grid] widget.
Google Workspace add-ons and Chat apps: The add-on UIs that support columns include:
- The dialog displayed when users open the add-on from an email draft.
- The dialog displayed when users open the add-on from the Add attachment menu in a Google Calendar event.
Columns.Types
Container for nested types declared in the Columns message type.
Columns.Types.Column
A column.
Columns.Types.Column.Types
Container for nested types declared in the Column message type.
Columns.Types.Column.Types.Widgets
The supported widgets that you can include in a column.
DateTimePicker
Lets users input a date, a time, or both a date and a time.
Supports form submission validation. When Action.all_widgets_are_required
is set to true or this widget is specified in Action.required_widgets,
the submission action is blocked unless a value is selected. For an example
in Google Chat apps, see Let a user pick a date and
time.
Users can input text or 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.
DateTimePicker.Types
Container for nested types declared in the DateTimePicker message type.
DecoratedText
A widget that displays text with optional decorations such as a label above or below the text, an icon in front of the text, a selection widget, or a button after the text. For an example in Google Chat apps, see Display text with decorative text.
DecoratedText.Types
Container for nested types declared in the DecoratedText message type.
DecoratedText.Types.SwitchControl
Either a toggle-style switch or a checkbox inside a decoratedText widget.
Google Workspace add-ons and Chat apps:
Only supported in the decoratedText widget.
DecoratedText.Types.SwitchControl.Types
Container for nested types declared in the SwitchControl message type.
Divider
Displays a divider between widgets as a horizontal line. For an example in Google Chat apps, see Add a horizontal divider between widgets.
Google Workspace add-ons and Chat apps:
For example, the following JSON creates a divider:
"divider": {}
Grid
Displays a grid with a collection of items. Items can only include text or
images. For responsive columns, or to include more than text or images, use
[Columns][google.apps.card.v1.Columns]. For an example in Google Chat apps,
see Display a Grid with a collection of
items.
A grid supports any number of columns and items. The number of rows is determined by items divided by columns. A grid with 10 items and 2 columns has 5 rows. A grid with 11 items and 2 columns has 6 rows.
Google Workspace add-ons and Chat apps:
For example, the following JSON creates a 2 column grid with a single item:
"grid": {
"title": "A fine collection of items",
"columnCount": 2,
"borderStyle": {
"type": "STROKE",
"cornerRadius": 4
},
"items": [
{
"image": {
"imageUri": "https://www.example.com/image.png",
"cropStyle": {
"type": "SQUARE"
},
"borderStyle": {
"type": "STROKE"
}
},
"title": "An item",
"textAlignment": "CENTER"
}
],
"onClick": {
"openLink": {
"url": "https://www.example.com"
}
}
}
Grid.Types
Container for nested types declared in the Grid message type.
Grid.Types.GridItem
Represents an item in a grid layout. Items can contain text, an image, or both text and an image.
Grid.Types.GridItem.Types
Container for nested types declared in the GridItem message type.
Icon
An icon displayed in a widget on a card. For an example in Google Chat apps, see Add an icon.
Image
An image that is specified by a URL and can have an onClick action. For an
example, see Add an
image.
ImageComponent
Represents an image.
ImageCropStyle
Represents the crop style applied to an image.
Google Workspace add-ons and Chat apps:
For example, here's how to apply a 16:9 aspect ratio:
cropStyle {
"type": "RECTANGLE_CUSTOM",
"aspectRatio": 16/9
}
ImageCropStyle.Types
Container for nested types declared in the ImageCropStyle message type.
MaterialIcon
A Google Material Icon, which includes over 2500+ options.
For example, to display a checkbox icon with customized weight and grade, write the following:
{
"name": "check_box",
"fill": true,
"weight": 300,
"grade": -25
}
OnClick
Represents how to respond when users click an interactive element on a card, such as a button.
OpenLink
Represents an onClick event that opens a hyperlink.
OpenLink.Types
Container for nested types declared in the OpenLink message type.
OverflowMenu
A widget that presents a pop-up menu with one or more actions that users can
invoke. For example, showing non-primary actions in a card. You can use this
widget when actions don't fit in the available space. To use, specify this
widget in the OnClick action of widgets that support it. For example, in a
Button.
OverflowMenu.Types
Container for nested types declared in the OverflowMenu message type.
OverflowMenu.Types.OverflowMenuItem
An option that users can invoke in an overflow menu.
SelectionInput
A widget that creates one or more UI items that users can select.
Supports form submission validation for dropdown and multiselect menus
only. When Action.all_widgets_are_required is set to true or this widget
is specified in Action.required_widgets, the submission action is blocked
unless a value is selected. For example, a dropdown menu or checkboxes. You
can use this widget to collect data that can be predicted or enumerated. For
an example in Google Chat apps, see Add selectable UI
elements.
Chat apps can process the value of items that users select or input. For details about working with form inputs, see Receive form data.
To collect undefined or abstract data from users, use the [TextInput][google.apps.card.v1.TextInput] widget.
SelectionInput.Types
Container for nested types declared in the SelectionInput message type.
SelectionInput.Types.PlatformDataSource
For a
[SelectionInput][google.apps.card.v1.SelectionInput] widget that uses a
multiselect menu, a data source from Google Workspace. Used to populate
items in a multiselect menu.
SelectionInput.Types.PlatformDataSource.Types
Container for nested types declared in the PlatformDataSource message type.
SelectionInput.Types.SelectionItem
An item that users can select in a selection input, such as a checkbox or switch. Supports up to 100 items.
Suggestions
Suggested values that users can enter. These values appear when users click inside the text input field. As users type, the suggested values dynamically filter to match what the users have typed.
For example, a text input field for programming language might suggest
Java, JavaScript, Python, and C++. When users start typing Jav, the list
of suggestions filters to show Java and JavaScript.
Suggested values help guide users to enter values that your app can make
sense of. When referring to JavaScript, some users might enter javascript
and others java script. Suggesting JavaScript can standardize how users
interact with your app.
When specified, TextInput.type is always SINGLE_LINE, even if it's set
to MULTIPLE_LINE.
Suggestions.Types
Container for nested types declared in the Suggestions message type.
Suggestions.Types.SuggestionItem
One suggested value that users can enter in a text input field.
TextInput
A field in which users can enter text. Supports suggestions and on-change
actions.
Supports form submission validation. When Action.all_widgets_are_required
is set to true or this widget is specified in Action.required_widgets,
the submission action is blocked unless a value is entered. For an example in
Google Chat apps, see Add a field in which a user can enter
text.
Chat apps receive and can process the value of entered text during form input events. For details about working with form inputs, see Receive form data.
When you need to collect undefined or abstract data from users, use a text input. To collect defined or enumerated data from users, use the [SelectionInput][google.apps.card.v1.SelectionInput] widget.
TextInput.Types
Container for nested types declared in the TextInput message type.
TextParagraph
A paragraph of text that supports formatting. For an example in Google Chat apps, see Add a paragraph of formatted text. For more information about formatting text, see Formatting text in Google Chat apps and Formatting text in Google Workspace add-ons.
TextParagraph.Types
Container for nested types declared in the TextParagraph message type.
Validation
Represents the necessary data for validating the widget it's attached to.
Validation.Types
Container for nested types declared in the Validation message type.
Widget
Each card is made up of widgets.
A widget is a composite object that can represent one of text, images, buttons, and other object types.
Widget.Types
Container for nested types declared in the Widget message type.
Enums
Action.Types.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. If specified for an add-on, the entire card is stripped and nothing is shown in the client.
Action.Types.LoadIndicator
Specifies the loading indicator that the action displays while making the call to the action.
BorderStyle.Types.BorderType
Represents the border types applied to widgets.
Button.Types.Type
Optional. The
type
of a button. If color field is set, the type is forced to FILLED.
Card.Types.DisplayStyle
In Google Workspace add-ons, determines how a card is displayed.
Card.Types.DividerStyle
The divider style of a card. Currently only used for dividers betweens card sections.
Card.Types.NestedWidget.DataOneofCase
Enum of possible cases for the "data" oneof.
ChipList.Types.Layout
The chip list layout.
Columns.Types.Column.Types.HorizontalSizeStyle
Specifies how a column fills the width of the card. The width of each
column depends on both the HorizontalSizeStyle and the width of the
widgets within the column.
Columns.Types.Column.Types.VerticalAlignment
Specifies whether widgets align to the top, bottom, or center of a column.
Columns.Types.Column.Types.Widgets.DataOneofCase
Enum of possible cases for the "data" oneof.
DateTimePicker.Types.DateTimePickerType
The format for the date and time in the DateTimePicker widget.
Determines whether users can input a date, a time, or both a date and time.
DecoratedText.ControlOneofCase
Enum of possible cases for the "control" oneof.
DecoratedText.Types.SwitchControl.Types.ControlType
How the switch appears in the user interface.
Grid.Types.GridItem.Types.GridItemLayout
Represents the various layout options available for a grid item.
Icon.IconsOneofCase
Enum of possible cases for the "icons" oneof.
ImageCropStyle.Types.ImageCropType
Represents the crop style applied to an image.
OnClick.DataOneofCase
Enum of possible cases for the "data" oneof.
OpenLink.Types.OnClose
What the client does when a link opened by an OnClick action is closed.
Implementation depends on client platform capabilities. For example, a web
browser might open a link in a pop-up window with an OnClose handler.
If both OnOpen and OnClose handlers are set, and the client platform
can't support both values, OnClose takes precedence.
OpenLink.Types.OpenAs
When an OnClick action opens a link, then the client can either open it
as a full-size window (if that's the frame used by the client), or an
overlay (such as a pop-up). The implementation depends on the client
platform capabilities, and the value selected might be ignored if the
client doesn't support it. FULL_SIZE is supported by all clients.
SelectionInput.MultiSelectDataSourceOneofCase
Enum of possible cases for the "multi_select_data_source" oneof.
SelectionInput.Types.PlatformDataSource.DataSourceOneofCase
Enum of possible cases for the "data_source" oneof.
SelectionInput.Types.PlatformDataSource.Types.CommonDataSource
A data source shared by all [Google Workspace applications] (https://developers.google.com/workspace/chat/api/reference/rest/v1/HostApp).
SelectionInput.Types.SelectionItem.StartIconOneofCase
Enum of possible cases for the "start_icon" oneof.
SelectionInput.Types.SelectionType
The format for the items that users can select. Different options support different types of interactions. For example, users can select multiple checkboxes, but can only select one item from a dropdown menu.
Each selection input supports one type of selection. Mixing checkboxes and switches, for example, isn't supported.
Suggestions.Types.SuggestionItem.ContentOneofCase
Enum of possible cases for the "content" oneof.
TextInput.Types.Type
How a text input field appears in the user interface. For example,
whether it's a single line input field, or a multi-line input. If
initialSuggestions is specified, type is always SINGLE_LINE,
even if it's set to MULTIPLE_LINE.
TextParagraph.Types.TextSyntax
Syntax to use for formatting text.
Validation.Types.InputType
The type of the input widget.
Widget.DataOneofCase
Enum of possible cases for the "data" oneof.
Widget.Types.HorizontalAlignment
Specifies whether widgets align to the left, right, or center of a column.
Widget.Types.ImageType
The shape used to crop the image.
Widget.Types.VerticalAlignment
Represents vertical alignment attribute.