This page describes how your Google Chat app can receive and respond to user interactions, also known as Google Chat app interaction events.
This page describes how to do the following:
- Configure your Chat app to receive interaction events.
- Process the interaction event on your infrastructure.
- If appropriate, respond to interaction events.
Prerequisites
A Google Chat app that's enabled for interactive features. To create an interactive Chat app, complete one of the following quickstarts based on the app architecture that you want to use:
- HTTP service with Google Cloud Functions
- Google Apps Script
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
How interaction events work
A Google Chat app interaction event represents any action that a user takes to invoke or interact with a Chat app, such as @mentioning a Chat app or adding it to a space. When users interact with a Chat app, Google Chat sends the Chat app an interaction event. The Chat app can use the event to process the interaction and create a response.
For example, Chat apps use interaction events to do any of the following:
Example of an interaction event | Typical response from a Chat app |
---|---|
A user invokes a Chat app by @mentioning it or using a slash command. | The
Chat app processes what the message says to
create a message. For example, a Chat app replies to
the /about command with a message that explains the tasks that
the Chat app can do. |
A user adds a Chat app to a space. | The Chat app sends an onboarding message that explains what it does and how users in the space can interact with it. |
A user removes a Chat app from a space. | The Chat app removes any incoming notifications configured for the space (such as deleting a webhook) and clears up any internal storage. |
A user clicks a button on a card or dialog sent by the Chat app. | The Chat app either processes and stores any data that the user submitted, or returns another card or dialog. |
For each type of user interaction, Google Chat sends a different type of
interaction event which helps your Chat app handle each
event type accordingly. For example, Google Chat uses the event type
ADDED_TO_SPACE
for any interaction where a user adds the
Chat app to a space, so that the
Chat app can handle a response, such as posting a
welcome message to the space. To see all supported interaction events, see the
EventType
reference
documentation.
Receive Chat app interaction events
This section describes how to receive and process interaction events for your Chat app.
Configure your Chat app to receive interaction events
Not all Chat apps are interactive. For example, incoming webhooks can only send outgoing messages and can't respond to users. If you're building an interactive Chat app, you must choose an endpoint that lets your Chat app receive, process, and respond to interaction events. To learn more about designing your Chat app, see Chat apps implementation architectures.
For each of the interactive features that you want to build, you must update your configuration in the Chat API so that Google Chat can send related interaction events to your Chat app:
In the Google Cloud console, go to the Chat API page and click the Configuration page:
Under Interactive features, review the settings and update based on the features that you want to build:
Field Description Functionality Required. A set of fields that determine how Chat app can interact with users: - Receive 1:1 messages: Users can find and message the Chat app directly in Google Chat.
- Join spaces and group conversations: Users can add the Chat app to spaces and group conversations.
Connection settings Required. The endpoint for the Chat app, which is one of the following: - App URL: An HTTPS endpoint that hosts the Chat app implementation.
- Apps Script project: A deployment ID for an Apps Script project that implements a Chat app.
- Cloud Pub/Sub topic name: A Pub/Sub topic that the Chat app subscribes to as an endpoint.
- Dialogflow: Registers the Chat app with a Dialogflow integration. For more information, see Build a Dialogflow Google Chat app that understands natural language.
Slash commands Optional. Commands that can be surfaced to users within Google Chat. Allows users to see core actions for your Chat app within Google Chat, and choose a specific action they want to interact with. For more information, see Respond to slash commands as a Chat app. Link previews Optional. URL patterns that the Chat app recognizes and provides additional content for when users send links. For more information, see Preview links. Visibility Optional. Up to five individuals, or one or more Google Groups that can view and install your Chat app. Use this field to test your Chat app, or to share the Chat app with your team. For more information, see Test interactive features. Click Save. When you save the Chat app configuration, your Chat app is available to the specified users in your Google Workspace organization.
Your Chat app is now configured to receive interaction events from Google Chat.
Handle HTTP call retries to your service
If an HTTPS request to your service fails (such as a timeout, temporary network failure, or non-2xx HTTPS status code), Google Chat might retry delivery a few times within a few minutes (but this isn't guaranteed). As a result, a Chat app might receive the same message a few times in certain situations. If the request completes successfully but returns an invalid message payload, Google Chat doesn't retry the request.
Process or respond to interaction events
This section explains how Google Chat apps can process and respond to interaction events.
After your Chat app receives an interaction event from Google Chat, they can respond in many ways. In many cases, interactive Chat apps reply to the user with a message. Google Chat app can also look up some information from a data source, record the interaction event information, or just about anything else. This processing behavior is essentially what defines the Google Chat app.
To respond synchronously, 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 can respond asynchronously.
For each interaction event, Chat apps receive a request body, which is the JSON payload that represents the event. You can use the information to process a response. For examples of event payloads, see Types of Chat app interaction events.
The following diagram demonstrates how Google Chat app typically process or respond to different types of interaction events:
Respond in real time
Interaction events let Chat apps respond in real time, or synchronously. Synchronous responses don't require authentication.
Respond to joining a space
In this example, your Chat app creates and sends a text message whenever it's added to a space. To learn about best practices for onboarding users, see Introduce users to your Chat app.
To send a text message when a user adds your Chat app
to a space, your Chat app
responds to an ADDED_TO_SPACE
interaction event. To respond to
ADDED_TO_SPACE
interaction events with a text message, use the following code:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The event object from Chat API.
* @param {Object} res The response object from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
The code sample returns the following text message:
Other examples of responding to interactions
To create synchronous responses to interaction events, see the following guides:
Respond asynchronously
Sometimes Chat apps must respond to an interaction event after 30 seconds or perform tasks outside of the space where the interaction event was generated. For example, a Chat app might need to respond to the user after completing a long-running task. In this case, Chat apps can respond asynchronously by calling the Google Chat API.
To create a message using the Chat API, see Create a message. For guides on using additional Chat API methods, see the Chat API overview.
Related topics
- Send a message
- Open interactive dialogs
- Preview links
- Read form data input by users on cards
- Respond to slash commands
- Build a homepage for a Chat app
- Verify requests from Chat
- Test interactive features for Google Chat apps