Simple example: WhereIs Bot
Google Chat supports more complex UIs in the form of cards. A simple example card:
This card, returned by our "WhereIs" bot, is constructed with the following JSON:
{
"cards": [
{
"sections": [
{
"widgets": [
{
"image": { "imageUrl": "https://..." }
},
{
"buttons": [
{
"textButton": {
"text": "OPEN IN GOOGLE MAPS",
"onClick": {
"openLink": {
"url": "https://..."
}
}
}
}
]
}
]
}
]
}
]
}
Components
The following sections document the UI elements available in cards.
Headers
A card can have a single header structure, which can contain the following attributes:
{
"cards": [
{
"header": {
"title": "Pizza Bot Customer Support",
"subtitle": "pizzabot@example.com",
"imageUrl": "https://goo.gl/aeDtrS",
"imageStyle": "IMAGE"
},
...
}
]
}
The imageStyle attribute controls the shape of the header image, which is
square ("IMAGE") or circular ("AVATAR"). The default is square ("IMAGE").
Result of above snippet:
Sections and widgets
A card must contain one or more sections, which are displayed in a vertical layout inside the card. Sections are separated by a line and contain one or more widgets. A section will look like the following in JSON form:
{
"cards": [
{
"header": "...",
"sections": [
{
"widgets": [
{ ... },
{ ... }
]
},
{ ... }
]
}
]
}
Each widget can only contain one type of UI element. For example, we do not allow a widget to contain both a TextParagraph and an Image element.
TextParagraph
A TextParagraph widget displays one or more lines of text, which can contain HTML tags as described in Card Text Formatting. Example:
{
"cards": [
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "<b>Roses</b> are <font color=\"#ff0000\">red</font>,<br><i>Violets</i> are <font color=\"#0000ff\">blue</font>"
}
}
]
}
]
}
]
}
Result:
KeyValue
A KeyValue widget displays a topLabel, content, and a bottomLabel. You can
attach an onClick event to the keyValue, making the topLabel, content, and
bottomLabel into clickable regions. Set contentMultiline to true to allow
content to span multiple lines. A KeyValue can also optionally have a built-in
icon, a custom icon, or a button associated with
it.
For example:
{
"cards": [
{
"sections": [
{
"widgets": [
{
"keyValue": {
"topLabel": "Order No.",
"content": "12345",
"contentMultiline": "false",
"bottomLabel": "Delayed",
"onClick": {
"openLink": {
"url": "https://example.com/"
}
},
"icon": "TRAIN",
"button": {
"textButton": {
"text": "VISIT WEBSITE",
"onClick": {
"openLink": {
"url": "http://site.com"
}
}
}
}
}
}
]
}
]
}
]
}
Result:
For the full list of available built-in icons, see Built-in Icons.
Image widget
An Image widget displays a full-width image from a custom URL. Example:
{
"cards": [
{
"sections": [
{
"widgets": [
{
"image": {
"imageUrl": "https://example.com/kitten.png",
"onClick": {
"openLink": {
"url": "https://example.com/"
}
}
}
}
]
}
]
}
]
}
Result:
Buttons
A widget can also contain one or more buttons. Buttons in the same widget will
be laid out horizontally. Buttons are mutually exclusive with other UI elements
in a widget; it is an error to specify another UI element alongside buttons in
the same widget.
There are two types of buttons: ImageButton and TextButton. An ImageButton can
specify either a built-in icon (see Built-in Icons
section below) or a custom image URL.
A button can specify a URL that will be opened when a user clicks on it, or an
action to be handled by the bot's CARD_CLICKED event handler, as shown in
Creating interactive cards.
Example:
{
"cards": [
{
"sections": [
{
"widgets": [
{
"buttons": [
{
"imageButton": {
"iconUrl": "https://....png",
"onClick": {
"openLink": {
"url": "https://example.com/..."
}
}
}
},
{
"imageButton": {
"icon": "EMAIL",
"onClick": {
"openLink": {
"url": "mailto:me@example.com"
}
}
}
},
{
"textButton": {
"text": "VISIT WEBSITE",
"onClick": {
"openLink": {
"url": "https://example.com/..."
}
}
}
},
{
"textButton": {
"text": "Snooze 1 day",
"onClick": {
"action": {
"actionMethodName": "snooze",
"parameters": [
{
"key": "hours",
"value": "24"
},
{
"key": "id",
"value": "123456"
}
]
}
}
}
},
{
"textButton": {
"text": "Snooze 1 hour",
"onClick": {
"action": {
"actionMethodName": "snooze",
"parameters": [
{
"key": "hours",
"value": "1"
},
{
"key": "id",
"value": "123456"
}
]
}
}
}
}
]
}
]
}
]
}
]
}
Result:
Full example: Pizza Bot
A full example message containing a card:
JSON message:
{
"cards": [
{
"header": {
"title": "Pizza Bot Customer Support",
"subtitle": "pizzabot@example.com",
"imageUrl": "https://goo.gl/aeDtrS"
},
"sections": [
{
"widgets": [
{
"keyValue": {
"topLabel": "Order No.",
"content": "12345"
}
},
{
"keyValue": {
"topLabel": "Status",
"content": "In Delivery"
}
}
]
},
{
"header": "Location",
"widgets": [
{
"image": {
"imageUrl": "https://maps.googleapis.com/..."
}
}
]
},
{
"widgets": [
{
"buttons": [
{
"textButton": {
"text": "OPEN ORDER",
"onClick": {
"openLink": {
"url": "https://example.com/orders/..."
}
}
}
}
]
}
]
}
]
}
]
}
Card formatting
Card text formatting
Inside cards, most text fields support basic text formatting via a small subset of HTML tags. The supported tags and their purpose are shown in the table below:
| Bold | <b> | Italic | <i> | |
| Underline | <u> | Strikethrough | <strike> | |
| Font Color | <font color=""> | Hyperlink | <a href=""> | |
| Line Break | <br> |
Note that the text body of a basic message is parsed using a different markup syntax which is optimized for human users (see Basic Message Formatting).
Built-in icons
The
KeyValue and Button widgets support the icon element
used to specify one of the built-in icons available in Google Chat:
"keyValue": {
"icon": "TRAIN",
}
The following table lists the built-in icons that are available:
| AIRPLANE | BOOKMARK | ||
| BUS | CAR | ||
| CLOCK | CONFIRMATION_NUMBER_ICON | ||
| DESCRIPTION | DOLLAR | ||
| EVENT_SEAT | |||
| FLIGHT_ARRIVAL | FLIGHT_DEPARTURE | ||
| HOTEL | HOTEL_ROOM_TYPE | ||
| INVITE | MAP_PIN | ||
| MEMBERSHIP | MULTIPLE_PEOPLE | ||
| PERSON | PHONE | ||
| RESTAURANT_ICON | SHOPPING_CART | ||
| STAR | STORE | ||
| TICKET | TRAIN | ||
| VIDEO_CAMERA | VIDEO_PLAY |
Custom icons
The KeyValue and Button widgets allow you to use
the built-in icons listed above, or define your own custom icons. To specify a
custom icon, use the iconUrl element as shown here:
{
"imageButton": {
"iconUrl": "https://....png",
"onClick": {
.
.
.
}
}
}