Build Google Chat interfaces

This page provides an overview of how to build user interfaces (UIs) for Google Workspace add-ons that extend Google Chat.

To build interfaces for Chat apps, you use the following add-on components:

  • Triggers: The ways that Google Chat users can invoke a Chat app, such as adding it to a space or sending it a message.
  • Event objects: The data that Chat apps receive from triggers or UI interactions.
  • Actions: The ways that Chat apps can respond to interactions, such as sending messages or returning a card-based user interface.
Chat app receives an event object from an Added to space trigger
Figure 1: When a user adds a Chat app to a space, the Added to space trigger fires and sends an event object. To respond with a message, the Chat app handles the event object and returns an action that creates the message.

Chat apps can build and display cards in the following interfaces:

  • Messages that can contain text, static or interactive cards, and buttons.
  • Dialogs which are cards that open in a new window and typically prompt users to submit information.
  • Link previews which are cards that preview information about an external service.

Triggers

This section explains the triggers that Google Workspace add-ons use in Chat.

Triggers are the specific ways that users invoke a Chat app using the Chat UI, such as using @mentions or app commands.

The following table shows Chat triggers, a description, and how Chat apps typically respond:

Trigger Description Typical response
Added to space

A user adds the Chat app to a space, or a Google Workspace administrator installs the Chat app in direct message spaces for users in their organization. To learn about Chat apps installed by administrators, see Install Marketplace apps in your domain in the Google Workspace Admin Help documentation.

 The Chat app sends an onboarding message that explains what it does and how users in the space can interact with it.
Message

A user interacts with the Chat app in a message one of the following ways:

  • Sends a message in a direct message (DM) space with the Chat app.
  • @mentions the Chat app in any type of space.
  • Sends a message that contains a link that matches the URL pattern for link previews.
  • Types text into the multiselect menu of a selectionInput widget.
 The Chat app responds based on the content of the message. For example, a Chat app replies to the slash command /about with a message that explains the tasks that the Chat app can do.
Removed from space

A user removes the Chat app from a space, or a Google Workspace administrator uninstalls the Chat app for a user in their organization.

Users can't remove Chat apps that were installed by their administrator. If a user had previously installed the Chat app, Chat app remains installed regardless of whether an Google Workspace administrator tries to uninstall.

 The Chat app removes any incoming notifications configured for the space (such as deleting a webhook) and clears up any internal storage. Chat apps can't respond with messages to this trigger, because they're no longer a member of the space.
App command

A user uses a Chat app command.

 The Chat app responds to the command. For example, replies with a message or opens a dialog.

Unlike other Google Workspace add-ons, you must configure any callback functions for these triggers using the Google Chat API. For guidance, see Configure a Google Chat app.

To respond to a trigger, see the following guides:

Event objects

Chat apps receive event objects when a Chat trigger fires, or when Chat users interact with a UI from the Chat app (such as clicking a button). The event object contains data about the interaction that the Chat app can use to respond or update a UI.

To learn about handling event objects, see the following guides:

To learn about add-on event objects within Chat and other Google Workspace applications, see Event objects.

Chat actions

This section explains how Chat apps can use add-on actions to respond to user interactions.

To respond with an add-on action, a Chat app must respond within 30 seconds, and the response must be posted in the space where the interaction occurred. Otherwise, the Chat app must set up authentication and call the Google Chat API to respond.

Chat apps can handle and respond to interactions in many ways. In many cases, Chat apps reply with a message. Chat apps can also look up some information from a data source, record the event object information, or just about anything else. This processing behavior is essentially what defines the Google Chat app.

To respond to user interactions, Chat apps must handle the corresponding event object and return one of the following JSON objects:

Chat app response Required action to return
Send or update a message. DataActions
Open, update, or close a dialog. RenderActions
To collect information from a card or dialog, suggest selection items based on what users type into a multiselect menu. RenderActions
Preview links in messages that Chat users send in a space. DataActions

Respond using the Google Chat API

Instead of returning an add-on action, Chat apps might need to use the Google Chat API respond to an interaction. For example, Chat apps must call the Google Chat API to do any of the following:

  • Respond to an interaction after 30 seconds.
  • Perform tasks outside of the space where the interaction took place.
  • Perform tasks in Chat that aren't available as add-on actions. For example, list spaces that a user or Chat app is a member of, or add users to space.
  • Perform tasks on behalf of the Chat user (which requires user authentication).

To learn about authenticating and calling the Chat API, see the Chat API overview.