Add text and images to a card or dialog

This page explains how to add text and images to a card or dialog message, and to modify how the text and images appear within the message.


Design and preview cards with the Card Builder.

Open the Card Builder

Prerequisites

  • A Google Workspace account with access to Google Chat.
  • A published Chat app. To build a Chat app, follow this quickstart.
  • Add an image

    The Image widget displays a PNG or JPG image hosted on an HTTPS URL. The displayed image's width fills the entire width of the displayed card, and its height adjusts to maintain the image's aspect ratio. The Image widget supports onclick actions that occur when users click the image. Example of onclick actions include:

    • Open a hyperlink with OpenLink, such as a hyperlink to the Google Chat developer documentation, https://developers.google.com/chat.
    • Run an action that runs a custom function, like calling an API.

    The Image widget has the following limitations:

    • Only PNG and JPG images are supported.
    • The host URL must be HTTPS.
    • To ensure performant cards, maximum recommended image size is 2MB.

    The following is a card consisting of an Image widget. It displays the Google Chat developer documentation landing page image. When users click the image, the Google Chat developer documentation opens in a new tab.

    Add an image component

    The Image widget is an image with limited styling. An imageCompent widget lets you apply cropStyle and borderStyle to an image.

    The following example shows two images in a grid where one of the images is cropped:

    Crop an image

    You can adjust the shape of an image by applying a cropStyle. There are several shapes to apply to an image:

    • Use SQUARE to apply a square crop.
    • Use CIRCLE to apply a circular crop.
    • Use RECTANGLE_CUSTOM to apply a rectangular crop with a custom aspect ratio. For example, you can use RECTANGLE_4_3 to apply a rectangular crop with a 4:3 aspect ratio.

    The following example shows five images in a grid with a different cropStyle applied to each image:

    Add an icon

    The Icon widget represents either a built-in icon or custom icon. You can use Icon in card messages and dialogs in the following ways:

    • Display a standalone icon.
    • Display an icon in front of related text, as part of a DecoratedText widget.
    • Display an icon as an interactive button, as part of a ButtonList widget.

    The following is a card consisting of an Icon component with a built-in icon:

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

    AIRPLANE BOOKMARK
    BUS CAR
    CLOCK CONFIRMATION_NUMBER_ICON
    DESCRIPTION DOLLAR
    EMAIL 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

    Add a paragraph of formatted text

    The TextParagraph widget displays a paragraph of text with optional HTML formatting. When setting the text content of these widgets, just include the corresponding HTML tags. For more information about which HTML tags are supported, see Card text formatting.

    For example, the following formatting is available for paragraph text:

    • Display bold, underlined, or italicized text with HTML <b>, <u>, <i> tags.
    • Link to websites with HTML <a href="https://www.google.com">hyperlinks</a>.
    • Add some color with HTML <font color="#ea9999">font tags</font>.

    Each TextParagraph widget renders as a new paragraph, and can be thought of as similar to an HTML <p> tag.

    The following is a card consisting of two TextParagraph widgets used to display two paragraphs with simple HTML formatting:

    Display text with decorative elements

    The DecoratedText widget displays text with optional layout and capabilities. For example:

    • Display an icon in front of the text with startIcon.
    • Show a title before the text with topLabel.
    • Add a clickable button with button or switchable toggle with switchControl.

    Use the DecoratedText widget when you need to present information in an easy-to-consume and interactive way. The widget is perfect for use cases such as contact cards, order status updates, and work ticket notifications.

    The DecoratedText widget supports simple text HTML formatting. When setting the text content of these widgets, just include the corresponding HTML tags. For more information about which HTML tags are supported, see Card text formatting.

    The following is a card consisting of a DecoratedText widget used to display contact details, such as email address, online status, phone number, and website:

    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.