Using service accounts

In many cases, bots respond to user requests synchronously; synchronous response payloads can be sent by the bot application directly without using the Google Chat API. However, some cases require out-of-band messages. For example, a bot might want to notify users asynchronously after a long-running background job they requested has completed. A bot needs to use the Google Chat API to send out-of-band messages to Google Chat.

Bots use service accounts to access Google APIs; in most cases a bot needs service account to use the Google Chat API. This guide explains how to set up and use a service account for your bot. Python is used in the sample, but this can be implemented in any language supported by our API Client Libraries.

A service account acts as the bot's own identity when accessing protected resources and methods. This means that bots act like special Google users: they have their own ID, they authenticate using their own credentials, and make calls to Google Chat with their own level of authorization.

Creating and using a service account

To use a service account with your bot, follow these steps:

  1. Create the service account and private key
  2. In your bot code, create and authorize a credential
  3. In your bot code, invoke Google Chat API

The remaining sections of this guide explain these steps in greater detail.

Step 1. Create service account and private key

To create a service account and private key, follow the steps below. You may also want to refer to the detailed Cloud documentation on this topic.

  1. Open the Developer Console
  2. Choose IAM & Admin > Service acounts
  3. Click Create service account
  4. Name it, leave Role blank
  5. Choose Furnish a new Private key
  6. Choose JSON
  7. Click Create
  8. The private key will be downloaded
    • The ID of this private key will also appear in APIs & services > Credentials
    • This is the only copy of the key. Do not lose it!

Step 2. Applying credentials to HTTP request headers

Next, you need to apply necessary credential headers to all requests made by an httplib2.Http instance. The documentation on service accounts shows an example of this, and of then calling a Google API using a service account.

Scopes for Google Chat bots

The following table lists the (only) available scope for Google Chat bots. Bots must pass the selected scope(s) when authenticating to the Google Chat API.

Scope Description
https://www.googleapis.com/auth/chat.bot Allows bots to view chats and send messages.

The following code snippet shows how to create a credential object, using a private key like the one created in step 1.

from oauth2client.service_account import ServiceAccountCredentials
scopes = 'https://www.googleapis.com/auth/chat.bot'
credentials = ServiceAccountCredentials.from_json_keyfile_name(
    '/path/to/keyfile.json', scopes)

Step 3. Build service endpoint and call API

You'll need to use a client library to call the Google Chat API. As mentioned above, we're using the Google APIs Client Library for Python in this example, but you can use any language supported by our client libraries.

Here's a code snippet that creates a service endpoint to the Google Chat API. The calls must be authorized, so we create a new HTTP client Http() and authorize/sign it with the service account credentials. This is passed, along with the API name and version, as the communication mechanism for talking to the API.

from apiclient.discovery import build
chat = build('chat', 'v1', http=credentials.authorize(Http()))

Next, create a new message with the room ID as the parent and JSON payload in the message body, and call the execute method:

resp = chat.spaces().messages().create(
    parent='spaces/AAAA2CiqVDM',
    body={'text': 'Test message'}).execute()
print(resp)

Complete example

The following code sends a message to Google Chat using a service account:

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build
scopes = 'https://www.googleapis.com/auth/chat.bot'
credentials = ServiceAccountCredentials.from_json_keyfile_name(
    'service-account.json', scopes)
chat = build('chat', 'v1', http=credentials.authorize(Http()))
resp = chat.spaces().messages().create(
    parent='spaces/AAAA2CiqVDM', # use your space here
    body={'text': 'Test message'}).execute()
print(resp)

When is a service account needed?

Although some bots need to use service accounts, some may not. See the table below for guidance.

Behavior Service account not required Service account required
Receive messages from...
  • HTTP POST requests
  • Apps Script callbacks
Respond to messages...
  • synchronously, via the HTTP response
  • synchronously, via the Apps Script callback return value
Send new messages...