Connect with external web applications

While bots 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.

Request bot configuration with an external app

In addition to presenting URLs as part of a normal reply, bots can privately present a configuration URL to the user in response to a message.

Return a configuration URL

If completing a request requires additional configuration that can't be completed directly in the bot, return a response of the following form:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

This tells Google Chat to present the user with a private prompt, with a link to visit the provided config URL for authentication, authorization, or configuration. A request-config response is mutually exclusive with a regular response message. Any text, cards, or other attributes are ignored.

Every event to your bot also includes a configCompleteRedirectUrl parameter. This URL should be encoded 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 bot starts the flow can depend on the specific message received. In response to a message like @bot help, a bot 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 room
  3. Dispatch the original message to the same bot a second time

Visiting a configCompleteRedirectUrl only affects a single user message. If a user has tried to message a bot multiple times and as a result received multiple prompts, clicking through a particular prompt and completing the auth / config process only affects that particular message / prompt. Other messages and prompts remain unchanged.

When an event is re-dispatched in this way, it normally should be identical to the original event; however, there are some situations where the events may differ. For example, when a message mentions both bot A and bot B, the user will be able to edit the message text if bot A responds with a regular message before authenticating with bot B. In this case, bot B will receive the edited message text after the user completes authentication.

Identify the user in bot messages

Each message sent to your bot includes the identity of the user interacting with the bot.

The example JSON fragment below shows the expected format of the user identity in a message to your bot.

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Chuck Norris",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "chuck@example.com"
  }
}

Use the value of the users.name property as the primary ID for the user. The value is a stable and unique ID for each user.

Identify the chat user outside of Google Chat.

In some cases, such as requesting OAuth authorization for an API, your bot needs to link to a URL outside of Google 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 ID from Google Chat.

While the two IDs are not exactly identical, they are easily coerced. To coerce the value of the sub claim to a Google Chat user name, prepend the value with "users/". For example, the claim value of 123 is equivalent to the user name users/123 in messages to your chat bot.

Full Example

The MyProfile bot demonstrates how to use the REQUEST_CONFIG response to initiate bot configuration and uses the identity token from the Google Sign-in response to identify the user.