Card Formatting Messages

Simple example: WhereIs Bot

Hangouts 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 may 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 may be square ("IMAGE") or circular ("AVATAR"). The default is square ("IMAGE").
Result of above snippet:

Sections & 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": [
    {
      "sections": [
        {
          "header": "...",
          "widgets": [
            { ... },
            { ... }
          ]
        },
        { ... }
      ]
    }
  ]
}

Each widget may 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 may 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 may 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 may 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.
Example:

{
  "cards": [
    {
      "sections": [
        {
          "widgets": [
            {
              "buttons": [
                {
                  "imageButton": {
                    "iconUrl": "https://....png",
                    "onClick": {
                      "openLink": {
                        "url": "https://example.com/..."
                      }
                    }
                  }
                },
                {
                  "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/..."
                      }
                      }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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 Hangouts Chat:

"keyValue": {
  "icon": "TRAIN",
}

The following table lists the built-in icons that are available:

flight AIRPLANE bookmark BOOKMARK
directions_bus BUS directions_car CAR
schedule CLOCK confirmation_number CONFIRMATION_NUMBER_ICON
subject DESCRIPTION attach_money DOLLAR
mail EMAIL event_seat EVENT_SEAT
flight_land FLIGHT_ARRIVAL flight_takeoff FLIGHT_DEPARTURE
hotel HOTEL grade HOTEL_ROOM_TYPE
insert_invitation INVITE location_on MAP_PIN
card_membership MEMBERSHIP people MULTIPLE_PEOPLE
person PERSON local_phone PHONE
restaurant RESTAURANT_ICON shopping_cart SHOPPING_CART
grade STAR store STORE
local_play TICKET train TRAIN
videocam VIDEO_CAMERA play_circle_filled 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": {
       .
       .
       .
    }
  }
}

Send feedback about...

Hangouts Chat API
Hangouts Chat API
Need help? Visit our support page.