Build an HTTP Google Chat app

This page explains how to build a Google Workspace add-on that works in Google Chat using an HTTP service.

Note: In Google Chat, add-ons appear to users as Google Chat apps. You can also build your Chat app using Google Chat API interaction events . To learn more, see the Extend Google Chat overview .

This quickstart shows you how to build an HTTP service using Google Cloud services. To build the Chat app, you write and deploy a Cloud Run function that the Chat app uses to respond to a user's message.

With an HTTP architecture, you configure Chat to integrate with Google Cloud or an on-premises server by using HTTP, as shown in the following diagram:

Architecture of a Chat app using a web service in an on-premises server.

In the preceding diagram, a user interacting with an HTTP 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.
An HTTP request is sent to a web server that is either a cloud or on-premises system that contains the Chat app logic.
Optionally, the Chat app logic can integrate with Google Workspace services (like Calendar and Sheets), other Google services (like Maps, YouTube, and Vertex AI), or other web services (like a project management system or ticketing tool).
The web server sends an HTTP response back to the Chat app service in Chat.
The response is delivered to the user.
Optionally, the Chat app can call the Chat API to asynchronously post messages or perform other operations.

This architecture provides you the flexibility to use existing libraries and components that already exist in your system because these Chat apps can be designed using different programming languages.

Objectives

Set up your environment.
Create and deploy a Cloud Run function.
Configure a Google Workspace add-on for the Chat app.
Test the app.

Prerequisites

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 .

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 Cloud Build API, Cloud Functions API, Cloud Pub/Sub API, Cloud Logging API, Artifact Registry API, and Cloud Run API.

Enable the APIs

Create and deploy a Cloud Run function

Create and deploy a Cloud Run function that generates a Chat card with the sender's display name and avatar image. When the Chat app receives a message, it runs the function and responds with the card.

To create and deploy the function for your Chat app, complete the following steps:

Node.js

In the Google Cloud console, go to the Cloud Run page:

Go to Cloud Run

Make sure that the project for your Chat app is selected.
Click Write a function.
On the Create servicepage, set up your function:
1. In the Service namefield, enter addonchatapp .
2. In the Regionlist, select a region.
3. In the Runtimelist, select the most recent version of Node.js.
4. In the Authenticationsection, select Require authentication.
5. Click Create, and wait for Cloud Run to create the service. The console redirects you to the Sourcetab.

In the Sourcetab:

In Entry point, delete the default text and enter avatarApp .
Replace the contents of index.js with the following code:

  /** 
 * Google Cloud Run function that responds to messages sent from a 
 * Google Chat space. 
 * 
 * @param {Object} req Request sent from Google Chat space 
 * @param {Object} res Response to send back 
 */ 
 import 
  
 { 
  
 http 
  
 } 
  
 from 
  
 '@google-cloud/functions-framework' 
 ; 
 http 
 ( 
 'avatarApp' 
 , 
  
 ( 
 req 
 , 
  
 res 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 req 
 . 
 method 
  
 === 
  
 'GET' 
  
 || 
  
 ! 
 req 
 . 
 body 
 . 
 chat 
 ) 
  
 { 
  
 return 
  
 res 
 . 
 send 
 ( 
 'Hello! This function is meant to be used ' 
  
 + 
  
 'in a Google Chat Space.' 
 ); 
  
 } 
  
 // Stores the Google Chat event as a variable. 
  
 const 
  
 chatMessage 
  
 = 
  
 req 
 . 
 body 
 . 
 chat 
 . 
 messagePayload 
 . 
 message 
 ; 
  
 // Replies with the sender's avatar in a card. 
  
 const 
  
 displayName 
  
 = 
  
 chatMessage 
 . 
 sender 
 . 
 displayName 
 ; 
  
 const 
  
 avatarUrl 
  
 = 
  
 chatMessage 
 . 
 sender 
 . 
 avatarUrl 
 ; 
  
 res 
 . 
 send 
 ({ 
  
 hostAppDataAction 
 : 
  
 { 
  
 chatDataAction 
 : 
  
 { 
  
 createMessageAction 
 : 
  
 { 
  
 message 
 : 
  
 { 
  
 text 
 : 
  
 'Here\'s your avatar' 
 , 
  
 cardsV2 
 : 
  
 [{ 
  
 cardId 
 : 
  
 'avatarCard' 
 , 
  
 card 
 : 
  
 { 
  
 name 
 : 
  
 'Avatar Card' 
 , 
  
 header 
 : 
  
 { 
  
 title 
 : 
  
 `Hello 
 ${ 
 displayName 
 } 
 !` 
 , 
  
 }, 
  
 sections 
 : 
  
 [{ 
  
 widgets 
 : 
  
 [{ 
  
 textParagraph 
 : 
  
 { 
  
 text 
 : 
  
 'Your avatar picture: ' 
  
 } 
  
 }, 
  
 { 
  
 image 
 : 
  
 { 
  
 imageUrl 
 : 
  
 avatarUrl 
  
 } 
  
 }] 
  
 }] 
  
 } 
  
 }] 
  
 }}}}}); 
 });

Replace the contents of package.json with the following code:

  { 
  
 "name" 
 : 
  
 "avatar-app" 
 , 
  
 "version" 
 : 
  
 "1.0.0" 
 , 
  
 "description" 
 : 
  
 "Google Chat Avatar App" 
 , 
  
 "main" 
 : 
  
 "index.js" 
 , 
  
 "type" 
 : 
  
 "module" 
 , 
  
 "scripts" 
 : 
  
 { 
  
 "start" 
 : 
  
 "node index.js" 
  
 }, 
  
 "dependencies" 
 : 
  
 { 
  
 "@google-cloud/functions-framework" 
 : 
  
 "^3.0.0" 
  
 } 
 }

Click Save and redeploy.

Python

In the Google Cloud console, go to the Cloud Run page:

Go to Cloud Run

Make sure that the project for your Chat app is selected.
Click Write a function.
On the Create servicepage, set up your function:
1. In the Service namefield, enter addonchatapp .
2. In the Regionlist, select a region.
3. In the Runtimelist, select the most recent version of Python.
4. In the Authenticationsection, select Require authentication.
5. Click Create, and wait for Cloud Run to create the service. The console redirects you to the Sourcetab.

In the Sourcetab:

In Entry point, delete the default text and enter avatar_app .
Replace the contents of main.py with the following code:

  from 
  
 typing 
  
 import 
 Any 
 , 
 Mapping 
 import 
  
 flask 
 import 
  
 functions_framework 
 @functions_framework 
 . 
 http 
 def 
  
 avatar_app 
 ( 
 req 
 : 
 flask 
 . 
 Request 
 ) 
 - 
> Mapping 
 [ 
 str 
 , 
 Any 
 ]: 
  
 """Google Cloud Run Function that handles requests from Google Chat 
 Args: 
 flask.Request: the request 
 Returns: 
 Mapping[str, Any]: the response 
 """ 
 if 
 req 
 . 
 method 
 == 
 "GET" 
 : 
 return 
 "Hello! This function must be called from Google Chat." 
 request_json 
 = 
 req 
 . 
 get_json 
 ( 
 silent 
 = 
 True 
 ) 
 # Stores the Google Chat event as a variable. 
 chat_message 
 = 
 request_json 
 [ 
 "chat" 
 ][ 
 "messagePayload" 
 ][ 
 "message" 
 ] 
 # Replies with the sender's avatar in a card. 
 display_name 
 = 
 chat_message 
 [ 
 "sender" 
 ][ 
 "displayName" 
 ] 
 avatar_url 
 = 
 chat_message 
 [ 
 "sender" 
 ][ 
 "avatarUrl" 
 ] 
 return 
 { 
 "hostAppDataAction" 
 : 
 { 
 "chatDataAction" 
 : 
 { 
 "createMessageAction" 
 : 
 { 
 "message" 
 : 
 { 
 "text" 
 : 
 "Here's your avatar" 
 , 
 "cardsV2" 
 : 
 [{ 
 "cardId" 
 : 
 "avatarCard" 
 , 
 "card" 
 : 
 { 
 "name" 
 : 
 "Avatar Card" 
 , 
 "header" 
 : 
 { 
 "title" 
 : 
 f 
 "Hello 
 { 
 display_name 
 } 
 !" 
 }, 
 "sections" 
 : 
 [{ 
 "widgets" 
 : 
 [{ 
 "textParagraph" 
 : 
 { 
 "text" 
 : 
 "Your avatar picture:" 
 } 
 }, 
 { 
 "image" 
 : 
 { 
 "imageUrl" 
 : 
 avatar_url 
 } 
 }] 
 }] 
 } 
 }] 
 }}}}}

Click Save and redeploy.

Java

In the Google Cloud console, go to the Cloud Run page:

Go to Cloud Run

Make sure that the project for your Chat app is selected.
Click Write a function.
On the Create servicepage, set up your function:
1. In the Service namefield, enter addonchatapp .
2. In the Regionlist, select a region.
3. In the Runtimelist, select the most recent version of Java.
4. In the Authenticationsection, select Require authentication.
5. Click Create, and wait for Cloud Run to create the service. The console redirects you to the Sourcetab.

In the Sourcetab:

In Entry point, delete the default text and enter AvatarApp .
Rename the default Java file to src/main/java/gcfv2/AvatarApp.java .
Replace the contents of AvatarApp.java with the following code:

  import 
  
 java.util.List 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.CardWithId 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1Card 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1Image 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1Section 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget 
 ; 
 import 
  
 com.google.api.services.chat.v1.model.Message 
 ; 
 import 
  
 com.google.cloud.functions.HttpFunction 
 ; 
 import 
  
 com.google.cloud.functions.HttpRequest 
 ; 
 import 
  
 com.google.cloud.functions.HttpResponse 
 ; 
 import 
  
 com.google.gson.Gson 
 ; 
 import 
  
 com.google.gson.JsonObject 
 ; 
 public 
  
 class 
 AvatarApp 
  
 implements 
  
 HttpFunction 
  
 { 
  
 private 
  
 static 
  
 final 
  
 Gson 
  
 gson 
  
 = 
  
 new 
  
 Gson 
 (); 
  
 @Override 
  
 public 
  
 void 
  
 service 
 ( 
 HttpRequest 
  
 request 
 , 
  
 HttpResponse 
  
 response 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 JsonObject 
  
 body 
  
 = 
  
 gson 
 . 
 fromJson 
 ( 
 request 
 . 
 getReader 
 (), 
  
 JsonObject 
 . 
 class 
 ); 
  
 if 
  
 ( 
 request 
 . 
 getMethod 
 (). 
 equals 
 ( 
 "GET" 
 ) 
  
 || 
  
 ! 
 body 
 . 
 has 
 ( 
 "chat" 
 )) 
  
 { 
  
 response 
 . 
 getWriter 
 (). 
 write 
 ( 
 "Hello! This function is meant to be used " 
  
 + 
  
 "in a Google Chat Space.." 
 ); 
  
 return 
 ; 
  
 } 
  
 // Stores the Google Chat event as a variable. 
  
 JsonObject 
  
 chatMessage 
  
 = 
  
 body 
 . 
 getAsJsonObject 
 ( 
 "chat" 
 ) 
  
 . 
 getAsJsonObject 
 ( 
 "messagePayload" 
 ). 
 getAsJsonObject 
 ( 
 "message" 
 ); 
  
 // Replies with the sender's avatar in a card. 
  
 String 
  
 displayName 
  
 = 
  
 chatMessage 
 . 
 getAsJsonObject 
 ( 
 "sender" 
 ). 
 get 
 ( 
 "displayName" 
 ). 
 getAsString 
 (); 
  
 String 
  
 avatarUrl 
  
 = 
  
 chatMessage 
 . 
 getAsJsonObject 
 ( 
 "sender" 
 ). 
 get 
 ( 
 "avatarUrl" 
 ). 
 getAsString 
 (); 
  
 Message 
  
 message 
  
 = 
  
 createMessage 
 ( 
 displayName 
 , 
  
 avatarUrl 
 ); 
  
 JsonObject 
  
 createMessageAction 
  
 = 
  
 new 
  
 JsonObject 
 (); 
  
 createMessageAction 
 . 
 add 
 ( 
 "message" 
 , 
  
 gson 
 . 
 fromJson 
 ( 
 gson 
 . 
 toJson 
 ( 
 message 
 ), 
  
 JsonObject 
 . 
 class 
 )); 
  
 JsonObject 
  
 chatDataAction 
  
 = 
  
 new 
  
 JsonObject 
 (); 
  
 chatDataAction 
 . 
 add 
 ( 
 "createMessageAction" 
 , 
  
 createMessageAction 
 ); 
  
 JsonObject 
  
 hostAppDataAction 
  
 = 
  
 new 
  
 JsonObject 
 (); 
  
 hostAppDataAction 
 . 
 add 
 ( 
 "chatDataAction" 
 , 
  
 chatDataAction 
 ); 
  
 JsonObject 
  
 dataActions 
  
 = 
  
 new 
  
 JsonObject 
 (); 
  
 dataActions 
 . 
 add 
 ( 
 "hostAppDataAction" 
 , 
  
 hostAppDataAction 
 ); 
  
 response 
 . 
 getWriter 
 (). 
 write 
 ( 
 gson 
 . 
 toJson 
 ( 
 dataActions 
 )); 
  
 } 
  
 Message 
  
 createMessage 
 ( 
 String 
  
 displayName 
 , 
  
 String 
  
 avatarUrl 
 ) 
  
 { 
  
 GoogleAppsCardV1CardHeader 
  
 cardHeader 
  
 = 
  
 new 
  
 GoogleAppsCardV1CardHeader 
 (); 
  
 cardHeader 
 . 
 setTitle 
 ( 
 String 
 . 
 format 
 ( 
 "Hello %s!" 
 , 
  
 displayName 
 )); 
  
 GoogleAppsCardV1TextParagraph 
  
 textParagraph 
  
 = 
  
 new 
  
 GoogleAppsCardV1TextParagraph 
 (); 
  
 textParagraph 
 . 
 setText 
 ( 
 "Your avatar picture: " 
 ); 
  
 GoogleAppsCardV1Widget 
  
 avatarWidget 
  
 = 
  
 new 
  
 GoogleAppsCardV1Widget 
 (); 
  
 avatarWidget 
 . 
 setTextParagraph 
 ( 
 textParagraph 
 ); 
  
 GoogleAppsCardV1Image 
  
 image 
  
 = 
  
 new 
  
 GoogleAppsCardV1Image 
 (); 
  
 image 
 . 
 setImageUrl 
 ( 
 avatarUrl 
 ); 
  
 GoogleAppsCardV1Widget 
  
 avatarImageWidget 
  
 = 
  
 new 
  
 GoogleAppsCardV1Widget 
 (); 
  
 avatarImageWidget 
 . 
 setImage 
 ( 
 image 
 ); 
  
 GoogleAppsCardV1Section 
  
 section 
  
 = 
  
 new 
  
 GoogleAppsCardV1Section 
 (); 
  
 section 
 . 
 setWidgets 
 ( 
 List 
 . 
 of 
 ( 
 avatarWidget 
 , 
  
 avatarImageWidget 
 )); 
  
 GoogleAppsCardV1Card 
  
 card 
  
 = 
  
 new 
  
 GoogleAppsCardV1Card 
 (); 
  
 card 
 . 
 setName 
 ( 
 "Avatar Card" 
 ); 
  
 card 
 . 
 setHeader 
 ( 
 cardHeader 
 ); 
  
 card 
 . 
 setSections 
 ( 
 List 
 . 
 of 
 ( 
 section 
 )); 
  
 CardWithId 
  
 cardWithId 
  
 = 
  
 new 
  
 CardWithId 
 (); 
  
 cardWithId 
 . 
 setCardId 
 ( 
 "avatarCard" 
 ); 
  
 cardWithId 
 . 
 setCard 
 ( 
 card 
 ); 
  
 Message 
  
 message 
  
 = 
  
 new 
  
 Message 
 (); 
  
 message 
 . 
 setText 
 ( 
 "Here's your avatar" 
 ); 
  
 message 
 . 
 setCardsV2 
 ( 
 List 
 . 
 of 
 ( 
 cardWithId 
 )); 
  
 return 
  
 message 
 ; 
  
 } 
 }

Replace the contents of pom.xml with the following code:

 <project  
xmlns="http://maven.apache.org/POM/4.0.0"  
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0  
http://maven.apache.org/xsd/maven-4.0.0.xsd">  
<modelVersion>4.0.0</modelVersion>  
<groupId>com.google.chat</groupId>  
<artifactId>avatar-app</artifactId>  
<version>1.0-SNAPSHOT</version>  
<properties>  
<maven.compiler.target>17</maven.compiler.target>  
<maven.compiler.source>17</maven.compiler.source>  
</properties>  
<dependencies>  
<dependency>  
<groupId>com.google.cloud.functions</groupId>  
<artifactId>functions-framework-api</artifactId>  
<version>1.0.4</version>  
</dependency>  
<!--  
https://mvnrepository.com/artifact/com.google.code.gson/gson  
-->  
<dependency>  
<groupId>com.google.code.gson</groupId>  
<artifactId>gson</artifactId>  
<version>2.9.1</version>  
</dependency>  
<!--  
https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat  
-->  
<dependency>  
<groupId>com.google.apis</groupId>  
<artifactId>google-api-services-chat</artifactId>  
<version>v1-rev20230115-2.0.0</version>  
</dependency>  
</dependencies>  
<!--  
Required  
for  
Java  
functions  
in  
the  
inline  
editor  
-->  
<build>  
<plugins>  
<plugin>  
<groupId>org.apache.maven.plugins</groupId>  
<artifactId>maven-compiler-plugin</artifactId>  
<version>3.8.1</version>  
<configuration>  
<excludes>  
<exclude>.google/</exclude>  
</excludes>  
</configuration>  
</plugin>  
</plugins>  
</build>
</project>

Click Save and redeploy.

The Cloud Run service details page opens. Wait for the function to deploy.

Configure the add-on

After the Cloud Run function is deployed, follow these steps to create a add-on and deploy the Google Chat app:

In the Google Cloud console, go to the Cloud Run page:

Go to Cloud Run

Make sure that the project for which you enabled Cloud Run is selected.
In the list of functions, click addonchatapp.
On the Service detailspage, copy the URLfor the function. The URL ends in run.app .
In the Google Cloud search field, search for "Google Chat API", then click Google Chat API, and click Manage.

Go to Chat API
Click Configurationand set up the Google Chat app:
1. In App name, enter Add-on Chat app .
2. In Avatar URL, enter https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png .
3. In Description, enter Add-on Chat app .
4. Under Functionality, select Join spaces and group conversations.
5. Under Connection settings, select HTTP endpoint URL.
6. Copy the Service account email. You need this email when you authorize your add-on to invoke your function.
7. Under Triggers, select Use a common HTTP endpoint URL for all triggers, and paste the URL for the Cloud Run function trigger into the box.
8. Under Visibility, select Make this Google Chat app available to specific people and groupsin your domain and enter your email address.
9. Under Logs, select Log errors to Logging.
Click Save.

Next, authorize the Chat app to invoke the Cloud Run function.

Authorize Google Chat to invoke your function

To Authorize Google Workspace add-on to invoke your function, add the Google Workspace add-on service account with the Cloud Run Service Invokerrole.

In the Google Cloud console, go to the Cloud Run page:

Go to Cloud Run
In the Cloud Run services list, select the checkbox next to the receiving function. (Don't click the function itself.)
Click Permissions. The Permissionspanel opens.
Click Add principal.
In New principals, enter the email address of the Google Workspace add-on service account associated to your Chat app.

The service account email address is on the Chat API configuration page, under Connection settings> HTTP endpoint URL> Service Account Email:

Go to Chat API configuration
In Select a role, select Cloud Run> Cloud Run Service Invoker.
Click Save.

The Chat app is ready to receive and respond to messages on Chat.

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.

Go to Google Chat
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.

Note: If you don't see your Chat app in the list of results, ensure that you've included your Google Workspace account in the Visibility settings of the Chat API Configuration page in the Google Cloud console.
In the new direct message with the app, type Hello and press enter .

The Chat app's message contains a card that displays the sender's name and avatar image, as demonstrated in the following image:

Chat app responding with a card featuring the sender's display name and avatar
image

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 .
Go to Resource Manager
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.

Build an HTTP Google Chat app Stay organized with collections Save and categorize content based on your preferences.

Objectives

Prerequisites

Set up the environment

Create and deploy a Cloud Run function

Node.js

Python

Java

Configure the add-on

Authorize Google Chat to invoke your function

Test your Chat app

Troubleshoot

Clean up

Build an HTTP Google Chat app