This guide explains how to set up and use a service account to access the Google Chat REST API on behalf of a Chat app. First, it walks you through how to create a service account. Then, it demonstrates how to write a script that uses the service account to authenticate with the Chat API and post a message in a Chat space.
Chat apps can use service accounts to authenticate when asynchronously calling the Google Chat REST API so they can:
- Send messages to Google Chat with
spaces.messages.create
to:- Notify users when a long-running background job finishes running.
- Alert users that a server has gone offline.
- Ask a customer support person to tend to a newly opened customer case.
- Update previously sent messages with
spaces.messages.update
to:- Change the status of on ongoing operation.
- Update a task's assignee or due date.
- List users in a space with
spaces.members.list
to:- See who is in a space.
- Verify space membership includes everyone on a team.
When authenticated with a service account, to get data about or perform actions in a Chat space, Chat apps must have membership in the space. For example, to list members of a space, or to create a message in a space, the Chat app has to itself be a member of the space.
If your Chat app needs to access user data or perform actions on a user's behalf, authenticate as a user instead.
If you're a domain administrator, you can grant domain-wide delegation of authority to authorize an application's service account to access your users' data without requiring each user to give consent. After you configure domain-wide delegation, you can make API calls using your service account to impersonate a user account. Although a service account is used for authentication, domain-wide delegation impersonates a user and is therefore considered user authentication. Any functionality that requires user authentication, you can use domain-wide delegation.
To learn more about when Chat apps require authentication and what kind of authentication to use, see Types of required authentication in the Chat API authentication and authorization overview.
Prerequisites
To run the example in this guide, you need the following prerequisites:
Python
- Python 3.6 or greater
- The pip package management tool
The Google client libraries for Python. To install them, run the following command in your command line interface:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
A Google Workspace account with access to Google Chat.
A Google Cloud project with the Chat API enabled. To create a project and enable an API, refer to Create a project and enable the API.
A published Chat app with membership in a Chat space:
- To create and publish a Chat app, see Build a Google Chat app with Cloud Functions.
- To add a Chat app to a Chat space, see Add apps to spaces or conversations in Google Chat.
Step 1: Create a service account in Google Cloud Console
Create a service account that your Chat app will use to access Google APIs.
Create a service account:
To create a service account, follow these steps:
- In the Google Cloud console, go to Menu > IAM & Admin > Service Accounts.
- Click Create service account.
- Fill in the service account details, then click Create and continue.
- Optional: Assign roles to your service account to grant access to your Google Cloud project's resources. For more details, refer to Granting, changing, and revoking access to resources.
- Click Continue.
- Optional: Enter users or groups that can manage and perform actions with this service account. For more details, refer to Managing service account impersonation.
- Click Done. Make a note of the email address for the service account.
The service account appears on the service account page. Next, create a private key for the service account.
Create a private key
To create a private key for the service account, follow these steps:
- In the Google Cloud console, go to Menu > IAM & Admin > Service Accounts.
- Select your service account.
- Click Keys > Add key > Create new key.
- Select JSON, then click Create.
Your new public/private key pair is generated and downloaded to your machine as a new file. This file is the only copy of this key. For information about how to store your key securely, see Managing service account keys.
- Click Close.
For more information about service accounts, see service accounts in the Google Cloud IAM documentation.
Step 2: Write a script that uses the service account to authenticate with Chat REST API
The following code authenticates with the Chat REST API using a service account, then posts a message to a Chat space:
Python
- In your working directory, create a file named
chat_app_auth.py
. Include the following code in
chat_app_auth.py
:from httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'service_account.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE_NAME with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE_NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
In the code, replace
SPACE_NAME
with a space name, which you can obtain from thespaces.list
method in Chat API, or from a space's URL.
Step 3: Run the complete example
In your working directory, build and run the sample:
Python
python3 chat_app_auth.py
Your script makes an authenticated request to the Chat REST API, which responds by posting a message in a Chat space as a Chat app.
Troubleshoot the example
This section describes common issues that you might encounter while attempting to run this sample.
You are not permitted to use this app
When running chat_app_auth.py
, you might receive an error that says:
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">
This error message means that the Chat app doesn't have permission to post Chat messages in the Chat space it's trying to post to.
To resolve the error, add the Chat app to the Chat space
specified in chat_app_auth.py
.
Next step
Learn what else Chat API can do by reviewing the Chat API reference documentation.