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:
- Create the service account and private key
- In your bot code, create and authorize a credential
- 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.
- Open the Developer Console
- Choose IAM & Admin > Service acounts
- Click Create service account
- Name it, leave Role blank
- Choose Furnish a new Private key
- Choose JSON
- Click Create
- 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... |
|
|
Respond to messages... |
|
|
Send new messages... |
|
|