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.

In Google Chat, add-ons appear to users as Google Chat apps. To learn more, see the Extend Google Chat overview.

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 /about command 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 quick command or a slash command from the Chat app.

 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

This section defines and explains all elements of Chat event objects. To learn more, see Event objects.

Event object
commonEventObject object (CommonEventObject)
An object containing information common to all event objects, regardless of the host application.
chat object (Chat)
An object containing all information about Chat interactions.

Chat

Chat
chat.user object (User)
The Chat user that interacted with the Chat app.
chat.space object (Space)
The Chat space where a user interacted with the Chat app.
chat.eventTime

string (Timestamp format)

The time when the interaction occurred.

Union field payload.

payload can be only one of the following:
chat.messagePayload

object (MessagePayload)

The payload that Chat apps receive from a Message trigger.
chat.addedToSpacePayload

object (AddedToSpacePayload)

The payload that Chat apps receive from an Added to space trigger.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

The payload that Chat apps receive from a Removed from space trigger.
chat.buttonClickedPayload

object (ButtonClickedPayload)

The payload that Chat apps receive when users click a button from a message or card. If a user clicks a button to submit information, the commonEventObject.formInputs object contains the values collected from the user. For details, see Collect information from Google Chat users.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

The payload that Chat apps receive when users type text into the multiselect menu of a selectionInput widget. Chat apps can use this event object to populate suggested items from a dynamic data source. For example, to populate support cases from an external data source, a Chat app can query the data source based on what the user types into the menu, and then return any matching support cases as selectable items.

The CommonEventObject.parameters['autocomplete_widget_query'] object contains the string value that the user types into the menu.

chat.appCommandPayload

object (AppCommandPayload)

The payload that Chat apps receive when a user uses a command from the Chat app.

Payload

Depending on the type of interaction, the event contains a payload with one or more Chat API resources.

Message payload
MessagePayload
chat.messagePayload.message object (Message)
The Chat message that triggered the event.
chat.messagePayload.space object (Space)
The Chat space in which a user sent the message that invoked the Chat app.

Added to space payload
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
The Chat space to which the user added or installed the Chat app.

When administrators install Chat apps, the space.adminInstalled field is set to true.

chat.addedToSpacePayload.interactionAdd boolean
Whether a user adds the Chat app to a space using a message. For example, @mentions the Chat app or uses a slash command. If true, Chat sends another event object with a messagePayload that contains information about the message.

Removed from space payload
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
The Chat space from which the user removed or uninstalled the Chat app.

When administrators uninstall Chat apps, the space.adminInstalled field is set to false.

Button clicked payload
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
The Chat message that contains the button that a user clicked.
chat.buttonClickedPayload.space object (Space)
The Chat space where the user clicked a button from a Chat app message.
chat.buttonClickedPayload.isDialogEvent boolean
Whether the user clicked the button to interact with a dialog.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
If isDialogEvent is true, the type of interaction in a dialog.

Enum DialogEventType.

Value of dialogEventType can be only one of the following:
TYPE_UNSPECIFIED Default value. Unspecified.
REQUEST_DIALOG A user requests a dialog. For example, they use a slash command or click a button from a message.
SUBMIT_DIALOG A user clicks an interactive element within a dialog. For example, a user fills out information in a dialog and clicks a button to submit the information.

Widget updated payload
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
The Chat space where the interaction occurred.

App command payload
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadata about which command the user used, and how they triggered the command.
chat.appCommandPayload.space object (Space)
The Chat space in which a user used the command.
chat.appCommandPayload.thread object (Thread)
If the interaction occurred in a thread, the Chat thread where the user used the command.
chat.appCommandPayload.message object (Message)
The message that the user sent with the slash command.
chat.appCommandPayload.configCompleteRedirectUri string
If authorization or configuration is required for the command, a URL to redirect the user to after they complete the process outside of Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Whether the command opens a dialog.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
The type of interaction with a dialog.

Enum DialogEventType.

Value of dialogEventType can be only one of the following:
TYPE_UNSPECIFIED Default value. Unspecified.
REQUEST_DIALOG A user requests a dialog. For example, they use a slash command or click a button from a message.
SUBMIT_DIALOG A user clicks an interactive element within a dialog. For example, a user fills out information in a dialog and clicks a button to submit the information.
App Command Metadata
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

The command ID.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
The type of command.

Enum AppCommandType.

Value of AppCommandType can be only one of the following:
APP_COMMAND_TYPE_UNSPECIFIED Default value. Unspecified.
SLASH_COMMAND A user uses the command by sending a message that begins with a slash /.

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 desired 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.