Receive and respond to interactions with your Google Chat app

This page describes how your Google Chat app can receive and respond to user interactions, also known as Google Chat app interaction events.

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. For example, Google Chat uses the event type MESSAGE for any interaction where a user invokes the Chat app in a message. For details, see Types of Google Chat app interaction events.

This page describes how to do the following:

  • Configure your Chat app to receive events.
  • Process the interaction event on your infrastructure.
  • If appropriate, respond to interaction events.

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.

If you've built an interactive Chat app, you must configure the Google Chat API so that Google Chat can send you interaction events:

  1. In the Google Cloud console, open the Google Chat API page:

    Go to Google Chat API page

  2. Click the Configuration tab.
  3. In the Interactive features section, click the Enable interactive features toggle to the on position.
  4. In Functionality, select one or both of the following checkboxes:
    1. Receive 1:1 messages: Lets users interact with your Chat app in direct messages (DM) spaces. Your Chat app receives interaction events any time a user sends a message in the DM space.
    2. Join spaces and group conversations: Lets users add and remove your Chat app to spaces with more than one person. Your Chat app receives interaction events whenever it's added or removed from the space, and whenever users @mention or use a slash command in the space.
  5. In Connection settings, specify where Google Chat sends Chat app interaction events.
  6. Optional: In Slash commands, add and configure one or more slash commands. For more information, see Set up slash commands.
  7. Optional: In Link previews, add and configure one or more URL patterns that your Chat app previews. For more information, see Preview links.
  8. Click Save.

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.

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:

Architecture of how Google Chat apps process interaction events.

Respond in real time

Interaction events let Chat apps respond in real time, or synchronously. Synchronous responses don't require authentication.

To create synchronous responses to interaction events, see the following guides:

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.

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.