Connect a Chat app with other services and tools

This page describes how to connect a Google Chat app with a service or tool that is outside of Google Chat. While Chat apps are powerful on their own, they often work in concert with other systems and require companion applications to connect accounts, authorize data access, display additional data, or configure user preferences.

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:

Request Chat app configuration from a user

If completing a request requires additional configuration that can't be completed directly in the Chat app, return a configuration URL to the user as part of a normal reply, or present it privately, in the following form:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

This tells Google Chat to present the user with a private prompt, where CONFIGURATION_URL is a link for the user to visit for additional authentication, authorization, or configuration. A REQUEST_CONFIG response is mutually exclusive with a regular response message. Any text, cards, or other attributes are ignored.

Complete the configuration request

Every MESSAGE interaction event that your Chat app receives also includes the field configCompleteRedirectUrl. You must encode this URL in your configuration URL to be used on completion of the process. Redirecting to this URL signals to Google Chat that the configuration request was fulfilled.

When your Chat app starts, the flow depends on the specific message received. In response to a message like @app help, a Chat app should respond with a message without requiring additional configuration.

When a user is successfully redirected to the configCompleteRedirectUrl provided in the original message, Google Chat performs the following steps:

  1. Erase the prompt that was displayed to the initiating user.
  2. Convert the original message to public, making it visible to other members of the space.
  3. Send the original message to the same Chat app a second time.

Visiting a configCompleteRedirectUrl only affects a single user message. If a user has tried to message a Chat app multiple times and as a result received multiple prompts, clicking through a particular prompt and completing the authentication and configuration process only affects that particular message. Other messages aren't changed.

When a MESSAGE interaction event is resent in this way, it should be identical to the original event; however, there are some situations where MESSAGE interaction events can differ. For example, when a message mentions both Chat app A and Chat app B, the user is able to edit the message if Chat app A responds with a regular message before authenticating with Chat app B. In this case, Chat app B receives the edited message text after the user completes authentication and configuration.

Authenticate the Chat user outside of Chat

In some cases, such as requesting OAuth authorization for an API, your app needs to link to a URL outside of Chat while maintaining the user identity. The best way to identify the user in these cases is to guard the destination app with Google Sign-in.

Use the identity token issued during sign-in to get the user ID. The sub claim contains the user's unique ID and can be correlated with the user ID from Google Chat.

While the two IDs aren't exactly identical, they can be coerced. To coerce the value of the sub claim to a Google Chat users/{user}, prepend the value with users/. For example, the claim value of 123 is equivalent to the username users/123 in messages to your Chat app.