Build a Google Chat app with Google Apps Script

Create a Google Chat app that you can directly message and that responds by echoing your messages.

The following diagram shows the architecture and messaging pattern:

In the preceding diagram, a user interacting with an Apps Script Chat app has the following flow of information:

1. A user sends a message to a Chat app, either in a direct message or in a Chat space.
2. The Chat app logic that's implemented in Apps Script, which resides in Google Cloud, receives and processes the message.
3. Optionally, the Chat app logic can integrate with Google Workspace services, such as a Calendar or Sheets, or other Google Services, such as Google Maps or YouTube.
4. The Chat app logic sends a response back to the Chat app service in Chat.
5. The response is delivered to the user.

Objectives

• Set up your environment.
• Set up the script.
• Publish the Chat app.
• Test the Chat app.

Prerequisites

• A Business or Enterprise Google Workspace account with access to Google Chat.
• A Google Cloud project. To create one, see Create a Google Cloud project.

Set up your environment

Open your Cloud project in the Google Cloud console

If it's not open already, open the Cloud project that you intend to use for this sample:

1. In the Google Cloud console, go to the Select a project page.

   Select a Cloud project

2. Select the Google Cloud project you want to use. Or, click Create project and follow the on-screen instructions. If you create a Google Cloud project, you might need to turn on billing for the project.

Turn on the Chat API

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.

  Enable the API

Configure the OAuth consent screen

All apps using OAuth 2.0 require a consent screen configuration. Configuring your app's OAuth consent screen defines what is displayed to users and app reviewers, and registers your app so you can publish it later.

1. In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.

   Go to OAuth consent screen

2. For User type select Internal, then click Create.
3. Complete the app registration form, then click Save and Continue.

4. For now, you can skip adding scopes and click Save and Continue. In the future, when you create an app for use outside of your Google Workspace organization, you must change the User type to External, and then, add the authorization scopes that your app requires.

5. Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.

Set up the script

To set up the script, you use a template and then set your Cloud project in Apps Script.

Create the script from the template

1. Go to the Apps Script Getting Started page.
2. Click the Chat App template. You might have to scroll down to see this template.
3. Click Untitled project, type Quickstart app, and click Rename.

Copy the Cloud project number

1. In the Google Cloud console, go to Menu > IAM & Admin > Settings.

   Go to IAM & Admin Settings

2. In the Project number field, copy the value.

Set the Apps Script project's Cloud project

1. In the Chat app Apps Script project, click Project Settings .
2. Under Google Cloud Platform (GCP) Project, click Change project.
3. In GCP project number, paste the Google Cloud project number.
4. Click Set project.

You now have working app code that you can try out (as described in the following steps) and then customize to meet your requirements.

Make sure that you're signed in to the correct Google Account when you open the Apps Script template. The current account can sometimes switch to your default account without you noticing.

Create a test deployment

You need a deployment ID for this Apps Script project, so that you can use it in the next step.

To get the head deployment ID, do the following:

1. In the Chat app Apps Script project, click Deploy > Test deployments.
2. Copy the Head deployment ID for use in a later step and click Done.

Publish the Chat app

Publish the Chat app from the Google Cloud console.

1. In the Google Cloud console, search for Google Chat API, and click Google Chat API.
2. Click Manage.

3. Click Configuration and set up the Chat app:

   1. In the App name field, enter Quickstart app.
   2. In the Avatar URL field, enter https://developers.google.com/chat/images/quickstart-app-avatar.png.
   3. In the Description field, enter Quickstart app.
   4. Under Functionality, select Receive 1:1 messages and Join spaces and group conversations.
   5. Under Connection settings, select Apps Script.
   6. In the Deployment ID field, paste the Head deployment ID that you previously copied.
   7. Under Visibility, select Specific people and groups in your domain, and enter your email.

4. Click Save.

The Chat app is ready to respond to messages.

Test the Chat app

To test your Chat app, open a direct message space with the Chat app and send a message:

1. Open Google Chat using the Google Workspace account that you provided when you added yourself as a trusted tester.

   Go to Google Chat

2. Click New chat.
3. In the Add 1 or more people field, type the name of your Chat app.

4. 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.

5. In the new direct message with the app, type Hello and press enter.

   The Chat app thanks you for adding it and echoes your message.

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.

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as a URL on appspot.com, delete the selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page. Click Menu > IAM & Admin > Manage Resources.

   Go to Resource Manager

2. In the project list, select the project you want to delete and then click Delete .
3. In the dialog, type the project ID and then click Shut down to delete the project.

Next steps

• Create interactive cards–Card messages support a defined layout, interactive UI elements like buttons, and rich media like images. Use card messages to present detailed information, gather information from users, and guide users to take a next step.
• Support slash commands–Slash commands let you register and advertise specific commands that users can give your app by typing a command that begins with a forward slash (/), like /help.
• Launch dialogs–Dialogs are windowed, card-based interfaces that your app can open to interact with a user. Multiple cards can be strung together sequentially, which helps users complete multi-step processes, like filling in form data.
• Codelab: Ready to build a more advanced Chat app? See the feedback Chat app from the codelab Build apps for Google Chat with Gemini.