Design an interactive card or dialog

This page explains how to add widgets and UI elements to card or dialog messages so that users can interact with your Google Chat app, such as by clicking a button or submitting information.


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 a button

    The ButtonList widget displays a set of buttons. Buttons can display text, an icon, or both text and an icon. Each Button supports an OnClick action that occurs when users click the button. For example:

    • Open a hyperlink with OpenLink, in order to provide users with additional information.
    • Run an action that runs a custom function, like calling an API.

    For accessibility, buttons support alternative text.

    Add a button that runs a custom function

    The following is a card consisting of a ButtonList widget with two buttons. One button opens the Google Chat developer documentation in a new tab. The other button runs a custom function called goToView() and passes the viewType="BIRD EYE VIEW" parameter.

    Add a button with custom color and a deactivated button

    You can prevent users from clicking a button by setting "disabled": "true".

    The following displays a card consisting of a ButtonList widget with two buttons. One button uses the Color field to customize the button's background color. The other button is deactivated with the Disabled field, which prevents the user from clicking the button and executing the function.

    Add a button with an icon

    The following displays a card consisting of a ButtonList widget with two icon Button widgets. One button uses the knownIcon field to display Google Chat's built-in email icon. The other button uses the iconUrl field to display a custom icon widget.

    Add a button with an icon and text

    The following displays a card consisting of a ButtonList widget that prompts the user to send an email. The first button displays an email icon and the second button displays text. The user can click either the icon or text button to run the sendEmail function.

    Add selectable UI elements

    The SelectionInput widget provides a set of selectable items, such as checkboxes, radio buttons, switches, or a drop-down menu. You can use this widget to collect defined and standardized data from users. To collect undefined data from users, use the TextInput widget instead.

    The SelectionInput widget supports suggestions, which help users enter uniform data, and on-change actions, which are Actions that run when a change occurs in a selection input field, such as a user selecting or un-selecting an item.

    Chat apps can receive and process the value of selected items. For details about working with form inputs, see Receive form data.

    This section provides examples of cards that use the SelectionInput widget. The examples use different types of section inputs:

    Add a checkbox

    The following displays a dialog that asks the user to specify whether a contact is professional, personal, or both, with a SelectionInput widget that uses checkboxes:

    Add a radio button

    The following displays a dialog that asks the user to specify whether a contact is professional or personal with a SelectionInput widget that uses radio buttons:

    Add a switch

    The following displays a dialog that asks the user to specify whether a contact is professional, personal, or both with a SelectionInput widget that uses switches:

    The following displays a dialog that asks the user to specify whether a contact is professional or personal with a SelectionInput widget that uses a drop-down menu:

    Add a multiselect menu

    The following displays a dialog that asks the user to select contacts from a multiselect menu:

    Use data sources for multiselect menus

    The following section explains how to use multiselect menus to populate data from dynamic sources, such as a Google Workspace application or external data source.

    Data sources from Google Workspace

    You can populate items for a multiselect menu from the following data sources in Google Workspace:

    • Google Workspace users: You can only populate users within the same Google Workspace organization.
    • Chat spaces: The user inputting items in the multiselect menu can only view and select spaces that they belong to within their Google Workspace organization.

    To use Google Workspace data sources, you specify the platformDataSource field. Unlike other selection input types, you omit SectionItem objects, because these selection items are dynamically sourced from Google Workspace.

    The following code shows a multiselect menu of Google Workspace users. To populate users, the selection input sets commonDataSource to USER:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "commonDataSource": "USER"
        }
      }
    }
    

    The following code shows a multiselect menu of Chat spaces. To populate spaces, the selection input specifies the hostAppDataSource field. The multiselect menu also sets defaultToCurrentSpace to true, which makes the current space the default selection in the menu:

    JSON

    {
      "selectionInput": {
        "name": "spaces",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 3,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "hostAppDataSource": {
            "chatDataSource": {
              "spaceDataSource": {
                "defaultToCurrentSpace": true
              }
            }
          }
        }
      }
    }
    
    Data sources outside of Google Workspace

    Multiselect menus can also populate items from a third-party or external data source. For example, you can use multiselect menus to help a user select from a list of sales leads from a customer relationship management (CRM) system.

    To use an external data source, you use the externalDataSource field to specify a function that returns items from the data source.

    To reduce the requests to an external data source, you can include suggested items that appear in the multiselect menu before users type in the menu. For example, you can populate recently searched contacts for the user. To populate suggested items from an external data source, specify SelectionItem objects.

    The following code shows a multiselect menu of items from an external set of contacts for the user. The menu displays one contact by default and runs the function getContacts to retrieve and populate items from the external data source:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

    For external data sources, you can also autocomplete items that users start typing in the multiselect menu. For example, if a user starts typing Atl for a menu that populates cities in the United States, your Chat app can autosuggest Atlanta before the user finishes typing. You can autocomplete up to 100 items.

    To autocomplete items, you create a function that queries the external data source and returns items whenever a user types in the multiselect menu. The function must do the following:

    • Pass an event object that represents the user interaction with the menu.
    • Identify that the interaction event's invokedFunction value matches the function from the externalDataSource field.
    • When the functions match, return suggested items from the external data source. To suggest items based on what the user types, get the value for the autocomplete_widget_query key. This value represents what the user types in the menu.

    The following code autocompletes items from an external data resource. Using the previous example, the Chat app suggests items based on when the function getContacts is triggered:

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              items: [
                {
                  value: "contact-1",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 1",
                  bottomText: "Contact one description",
                  selected: false
                },
                {
                  value: "contact-2",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 2",
                  bottomText: "Contact two description",
                  selected: false
                },
                {
                  value: "contact-3",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 3",
                  bottomText: "Contact three description",
                  selected: false
                },
                {
                  value: "contact-4",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 4",
                  bottomText: "Contact four description",
                  selected: false
                },
                {
                  value: "contact-5",
                  startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                  text: "Contact 5",
                  bottomText: "Contact five description",
                  selected: false
                },
              ]
            }
          }
        }
      };
    }
    

    Add a field in which a user can enter text

    The TextInput widget provides a field in which users can enter text. The widget supports suggestions, which help users enter uniform data, and on-change actions, which are Actions that run when a change occurs in the text input field, like a user adding or deleting text.

    When you need to collect abstract or unknown data from users, use this TextInput widget. To collect defined data from users, use the SelectionInput widget instead.

    To process the text that users input, see Receive form data.

    The following is a card consisting of a TextInput widget:

    Let a user pick a date and time

    The DateTimePicker widget lets users input a date, a time, or both a date and a time. Or, users can 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.

    To process the date and time values that users input, see Receive form data.

    The following displays a card consisting of three different types of DateTimePicker widgets:

    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.