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.

Authenticate requests from Google Chat

For apps built on HTTP endpoints, this section explains how to verify that the requests to your endpoint are coming from Google Chat.

To dispatch interaction events to your Chat app's endpoint, Google makes requests to your service. To verify that the request is coming from Google, Google Chat includes a bearer token in the Authorization header of every HTTPS request to your endpoint. For example:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

The string AbCdEf123456 in the example above is the bearer authorization token. This is a cryptographic token produced by Google. You can verify your bearer token using an open source Google API client library:

For the bearer tokens sent in Google Chat requests, the issuer is chat@system.gserviceaccount.com and the audience field is set to the number of the Google Cloud project that you used to build your Chat app. For example, if your Chat app's Cloud project number is 1234567890, then the audience field in the bearer token is 1234567890.

If the token doesn't verify for the Chat app, your service should respond to the request with an HTTPS response code 401 (Unauthorized).

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

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 retries delivery twice, with at least a ten-second delay between each retry. As a result, a Chat app might receive the same message up to three 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.