Overview

Build Google Chat apps that bring your services and resources right into Google Chat, letting users get information and take action without leaving the conversation.

Google Chat supports team collaboration by providing the following:

Direct messages between users.
Threaded conversations within spaces.
Chat spaces that let you dedicate discussion space on a per-project, per-team, or other basis.
Chat apps that can participate in spaces or respond to direct messages.

Messages and spaces

Interactions between Google Chat and Chat apps take place using messages in the context of particular spaces. For example, a Chat app can send a text (a type of message) to a specific Chat space.

Messages include Chat app interactions, text, or cards while spaces include chat rooms and direct messages.

The preceding diagram shows the different types of interactions and contexts available for messages and spaces:

Messages between Google Chat and a Chat app follow a defined message format, where each message consists of a JSON object whose components specify the user ID, style, content, and other aspects of the message. Chat apps can send the following types of messages:
- Text messages contain plain text content with limited text formatting.
- Card messages define the format, content, and behavior of cards to be displayed in a space. For example, a card message can include a button with a link that opens a dialog to collect information from a user.
In Google Chat, spaces can have the following contexts:
- A named or group space is visible to multiple users.
- A direct message is visible only to the user in that space.

Use cases

Adding Chat apps to a conversational platform like Chat lets people ask questions, and issue commands, without changing context. On its backend, a Chat app can access other systems, acting as an intermediary to those systems.

This ability to provide access to a wide range of resources and tools, while maintaining a unified cognitive experience, can provide a framework for many types of applications, including the following:

Workflow management
Setup and configuration
Order generation
Search
Data collection

Some examples of things you might ask a Chat app to do from within the Chat space include the following:

Look up information — A Chat app can retrieve information based on structured or free text queries entered by the user.
File tickets — A Chat app can generate incident reports or other artifacts, using information provided by the user.
Coordinate efforts — A Chat app can enhance the way that team members interact with each other, such as providing "team memory" or scheduling resources.

Build interactive Chat apps

Many Chat apps let users message and interact with the Chat app directly. Interactive Chat apps can do any of the following:

Respond to @mentions, slash commands, or direct messages with a text message or card message.
Open a dialog to help users complete multi-step processes, like filling in form data.
Preview links by attaching cards with helpful information that let users take action directly from the conversation.

To interact with users, your Chat app must be able to receive and respond to interaction events. To build an interactive Chat app, see Receive and respond to Google Chat app interaction events.

Build non-interactive Chat apps

Google Chat apps can also be non-interactive for users where users can't directly interact with the Chat app, but the Chat app calls the Google Chat API directly. For example, you can create a Chat app that sends a message in a space but users can't respond to the Chat app. This type of Chat app architecture is useful for things like alarm reporting. For more information, see the Google Chat API overview.

Build event-driven Chat apps

A Chat app can subscribe to events about Chat resources using the Google Workspace Events API. A subscription lets your Chat app receive information about events, which represent changes to a subscribed Google Workspace resource. For example, a Chat app can respond to changes to a space that the Chat app is subscribed to, such as sending a welcome message to new members added to the space. For more information, see Subscribe to Google Chat events.

Choose a Chat app architecture

The Chat API provides a number of ways that you can integrate your apps into Chat spaces, but doesn't provide or dictate any particular way to implement the Chat app logic. You can create a command-driven Chat app or use any kind of language processing and AI services or modules that you like, and you can do this on a variety of platforms, including the following:

AppSheet
Google Apps Script
Pub/Sub
Google Cloud or an on-premises HTTP server

For more information, see Choose a Chat apps architecture.

App access to user data

When a Chat app is invoked, it needs to know who is invoking it, in what context, and how to address the invoker. To access data beyond this basic identity data, the Chat app must be granted access through authentication.

By default, Chat apps can only read the basic identity of users that invoke them or users being @mentioned in the same message that invokes the app. This information includes the user's display name, user ID, email address, and avatar image.
For Chat apps that preview links, the Chat app can read URLs added to the message that match the Chat app's configured URL patterns.
If a Chat app needs to access other data to provide enhanced capabilities to users, such as reading all messages or the list of members in a space, set up authentication so it can access that data. If accessing user data, the Chat app prompts the user to ask for access, and the user must grant it. To learn more, see Connect a Chat app with other services & tools.