Send a card message

In addition to text messages, Chat apps can send card messages in spaces and to users. Cards support a defined layout, interactive UI elements like buttons, and rich media like images.

Use card messages to:

• Present detailed information
• Gather information from users
• Guide users to take a next step

This guide describes how to send card messages synchronously (a realtime response to a Chat event, like receiving a message from a user or getting added to a space) and asynchronously (sending a message from the app to a space or user without a prompt using the Chat REST API).

Prerequisites

To send the card messages in this guide, you need the following:

Anatomy of a card message

Each card, whether it is a dialog or a message, is a JSON object on the spaces.messages resource in Chat API.

The card JSON object consists of the following:

1. An array called cardsV2[] which contains one or more CardWithId objects.
2. A cardId, used to identify the card and scoped within a given message. (Cards in different messages can have the same ID.)

3. A card object, which consists of the following:

   • A header object that specifies things like a title, subtitle, and avatar-style image.
   • One or more section objects that each contain at least one widget.

   • One or more widget objects. Each widget is a composite object that can represent text, images, buttons, and other object types.

     The following widgets are supported in card messages and dialogs:

     • TextParagraph–Displays a paragraph of text with optional simple HTML formatting.
     • Image–Displays a clickable or static .PNG or .JPG image hosted on an HTTPS URL.
     • DecoratedText–Displays text with optional layout and functionality features, like icons and buttons.
     • ButtonList–Displays a set of buttons.

     The following widgets are supported in dialogs (support for card messages coming soon):

     • TextInput–Field in which users can enter text.

     • SelectionInput–Provides a set of selectable items, like a list of checkboxes, radio buttons, switches, or a dropdown menu.

     • Divider–Displays a horizontal line spanning the width of a card between stacked widgets, acting as a visual divider.

     • Grid–Lays a set of items out in a simple grid.

     Support for the following widget is coming soon:

     • DateTimePicker–Lets users specify a date, time, or both.

As an example, observe the header, section, and widget objects in the following card message:

The following code represents the JSON of the card message:

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/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",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Send a synchronous card message

In this example, a user sends the Chat app a message in Google Chat and the app responds by sending a simple synchronous card message showing the sender's name and avatar image:

In the following code samples, the Node.js and Python apps are hosted on Google Cloud Functions. The Apps Script example is hosted on Google Apps Script.

For full instructions describing how to build and deploy a Chat app, see Build a Chat app.

/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Send an asynchronous card message with Chat API

This example asynchronously creates a message with Chat API and sends it to a space that the Chat app is added to, like the one shown below:

To learn more about working with messages in Chat REST API, see Create, read, update, delete messages.

Open a dialog

Dialogs are windowed, card-based interfaces that Chat apps open to interact with users. To help users complete multi-step processes, apps can open sequential dialogs. Apps can open dialogs in response to a button click on a card message or in response to a slash command.

Dialogs are useful for many types of user interactions, including:

• Collecting information from users
• Authenticating users with Web services
• Configuring Chat app settings

In this example, a Chat app opens a dialog to help a user create a new contact for their address book:

To implement dialogs, see Open dialogs.

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:

Note that the text body of a basic message is parsed using a different markup syntax which is optimized for human users. For details, see Send a text message.

Built-in icons

The DecoratedText and ButtonList widgets support the icon element used to specify one of the built-in icons available in Google Chat:

{
  .
  .
  .
      "knownIcon": "TRAIN",
  .
  .
  .
}

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

Custom icons

The DecoratedText and ButtonList 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:

{ . . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . . }

Limits and considerations

As you get ready to send card messages, take note of these limits and considerations.

• The following widgets aren't supported by card messages, but support is coming soon:

  • TextInput, a field in which users can enter text.
  • SelectionInput, which provides a set of selectable items, like a list of checkboxes, radio buttons, switches, or a dropdown menu.
  • DateTimePicker, which lets users specify a date, time, or both.
  • Grid, which lays a set of items out in a simple grid.