Overview

In most cases, a bot needs a service account to work with Hangouts Chat. (There are a few special cases where this isn't necessary.) This guide explains how to set up a service account for your bot.

Bots use service accounts to access Google APIs; the 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 Hangouts 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 Hangouts 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 Google Cloud documentation on service accounts shows an example of this, and of then calling a Google API using a service account.

Scopes for Hangouts Chat bots

The following table lists the scopes that can be used by Hangouts Chat bots. Bots must pass this scope when authenticating into the Hangouts 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)

The next code snipped shows how to use the authorize method of the Credentials object to apply the necessary credential headers to all requests made by an httplib2.Http instance:

from httplib2 import Http
http_auth = credentials.authorize(Http())
http = Http()

Step 3. Call the Hangouts Chat API

You'll need to use a client library to call the Hangouts Chat API. The examples in this section use the Python client library.

First, you should build a service object for the Chat API using the discoveryURL.

from apiclient.discovery import build, build_from_document
chat = build('chat', 'v1', http=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)

Example

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

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

When is a service account needed?

Although most 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...

Send feedback about...

Hangouts Chat API
Hangouts Chat API
Need help? Visit our support page.