This page explains how to create a Chat app using Pub/Sub. This type of architecture for a Chat app is useful if your organization has a firewall, which can prevent Chat from sending messages to your Chat app, or if the Chat app uses the Google Workspace Events API. However, this architecture has the following limitations due to the fact that these Chat apps can only send and receive asynchronous messages:
- Can't use dialogs in messages. Instead, use a card message.
- Can't update individual cards with a synchronous response. Instead, update
the entire message by calling the
patch
method.
The following diagram shows the architecture of a Chat app built with Pub/Sub:
In the preceding diagram, a user interacting with a Pub/Sub Chat app has the following flow of information:
A user sends a message in Chat to a Chat app, either in a direct message or in a Chat space, or an event happens in a Chat space for which the Chat app has an active subscription.
Chat sends the message to a Pub/Sub topic.
An application server, that is either a cloud or on-premises system that contains the Chat app logic, subscribes to the Pub/Sub topic in order to receive the message through the firewall.
Optionally, the Chat app can call the Chat API to asynchronously post messages or perform other operations.
Prerequisites
Java
- A Business or Enterprise Google Workspace account with access to Google Chat.
- A Google Cloud project with billing enabled. To check that an existing project has billing enabled, see Verify the billing status of your projects. To create a project and set up billing, see Create a Google Cloud project.
- Java 11 or greater
- The Maven package management tool
Python
- A Business or Enterprise Google Workspace account with access to Google Chat.
- A Google Cloud project with billing enabled. To check that an existing project has billing enabled, see Verify the billing status of your projects. To create a project and set up billing, see Create a Google Cloud project.
- Python 3.6 or greater
- The pip package management tool
Node.js
- A Business or Enterprise Google Workspace account with access to Google Chat.
- A Google Cloud project with billing enabled. To check that an existing project has billing enabled, see Verify the billing status of your projects. To create a project and set up billing, see Create a Google Cloud project.
- Node.js 14 or greater
- The npm package management tool
-
An initialized Node.js project. To initialize a new project, create and
switch into a new folder, then run the following command in your command-line interface:
npm init
Set up the environment
Before using Google APIs, you need to turn them on in a Google Cloud project. You can turn on one or more APIs in a single Google Cloud project.In the Google Cloud console, enable the Google Chat API and the Pub/Sub API.
Set up Pub/Sub
Create a Pub/Sub topic that the Chat API can send messages to. We recommend that you use a single topic per Chat app.
Grant Chat permission to publish to the topic by assigning the Pub/Sub Publisher role to the following service account:
[email protected]
Create a service account for the Chat app to authorize with Pub/Sub and Chat and save the private key file to your working directory.
Create a pull subscription to the topic.
Assign the Pub/Sub Subscriber Role on the subscription for the service account that you previously created.
Write the script
Java
In a CLI, provide service account credentials:
export GOOGLE_APPLICATION_CREDENTIALS=SERVICE_ACCOUNT_FILE_PATH
In a CLI, provide the Google Cloud project ID:
export PROJECT_ID=PROJECT_ID
In a CLI, provide the subscription ID for the Pub/Sub subscription that you previously created:
export SUBSCRIPTION_ID=SUBSCRIPTION_ID
In your working directory, create a file named
pom.xml
.In the
pom.xml
file, paste the following code:In your working directory, create the directory structure
src/main/java
.In the
src/main/java
directory, create a file namedMain.java
.In
Main.java
, paste the following code:
Python
In a CLI, provide service account credentials:
export GOOGLE_APPLICATION_CREDENTIALS=SERVICE_ACCOUNT_FILE_PATH
In a CLI, provide the Google Cloud project ID:
export PROJECT_ID=PROJECT_ID
In a CLI, provide the subscription ID for the Pub/Sub subscription that you previously created:
export SUBSCRIPTION_ID=SUBSCRIPTION_ID
In your working directory, create a file named
requirements.txt
.In the
requirements.txt
file, paste the following code:In your working directory, create a file named
app.py
.In
app.py
, paste the following code:
Node.js
In a CLI, provide service account credentials:
export GOOGLE_APPLICATION_CREDENTIALS=SERVICE_ACCOUNT_FILE_PATH
In a CLI, provide the Google Cloud project ID:
export PROJECT_ID=PROJECT_ID
In a CLI, provide the subscription ID for the Pub/Sub subscription that you previously created:
export SUBSCRIPTION_ID=SUBSCRIPTION_ID
In your working directory, create a file named
package.json
.In the
package.json
file, paste the following code:In your working directory, create a file named
index.js
.In
index.js
, paste the following code:
Publish the app to Chat
In the Google Cloud console, go to Menu > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration.
Configure the Chat app for Pub/Sub:
- In App name, enter
Quickstart App
. - In Avatar URL, enter
https://developers.google.com/chat/images/quickstart-app-avatar.png
. - In Description, enter
Quickstart app
. - Under Functionality, select Receive 1:1 messages and Join spaces and group conversations.
- Under Connection settings, select Cloud Pub/Sub and paste the name of the Pub/Sub topic that you previously created.
- Under Visibility, select Make this Google Chat app available to specific people and groups in your domain and enter your email address.
- Under Logs, select Log errors to Logging.
- In App name, enter
Click Save.
The app is ready to receive and respond to messages on Chat.
Run the script
In a CLI, switch into your working directory and run the script:
Java
mvn compile exec:java -Dexec.mainClass=Main
Python
python -m venv env
source env/bin/activate
pip install -r requirements.txt -U
python app.py
Node.js
npm install
npm start
When you run the code, the application starts listening to messages published to the Pub/Sub topic.
Test your Chat app
To test your Chat app, open a direct message space with the Chat app and send a message:
Open Google Chat using the Google Workspace account that you provided when you added yourself as a trusted tester.
- Click New chat.
- In the Add 1 or more people field, type the name of your Chat app.
Select your Chat app from the results. A direct message opens.
- In the new direct message with the app, type
Hello
and pressenter
.
To add trusted testers and learn more about testing interactive features, see Test interactive features for Google Chat apps.
Troubleshoot
When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.
Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, see Troubleshoot and fix Google Chat errors.
Clean up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, we recommend that you delete the Cloud project.
- In the Google Cloud console, go to the Manage resources page. Click Menu > IAM & Admin > Manage Resources.
- In the project list, select the project you want to delete and then click Delete .
- In the dialog, type the project ID and then click Shut down to delete the project.
Related topics
To add more features to your Chat app, see the following: