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 slash commands.

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

Trigger Description Typical response

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 slash command in any type of space. Sends a message that contains a link that matches the URL pattern for link previews.	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.

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 slash command in any type of space.
Sends a message that contains a link that matches the URL pattern for link previews.

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.

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.

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.

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:

DataActions: Creates or updates Google Workspace data. To send or update Chat messages, the object must contain the markup that defines the changes to the Message data, represented as chatDataActionMarkup.
RenderActions: Displays or navigates between cards in messages and dialogs.
basic_authorization_prompt: Prompts users with an authorization card to sign in or authenticate to a service that's external to Google. For details, see Connect your Google Workspace add-on to a third-party service.

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.