Send message to Google Chat using the REST API (Google example not working in 2020)

Question

Where do I even begin... (Google, why must you hurt me this way?)

Background Info

I have created a new chatbot using Google Apps Script, which receives messages from users in Google Chat and responds synchronously with a single message (each message can only have one response from the chatbot).

Now I need a way to send asynchronous messages so that the bot can send messages on its own, or send multiple separate responses at a time.

The problem

The Google Chat REST API has a method to create a message asynchronously, but this method (spaces.messages.create) does not work! There are no working examples of this method from 2020.

Here is Google's example code for creating a message using the REST API.

The problem is that in their example, the SCOPE is set to a URL that no longer exits:

var SCOPE = 'https://www.googleapis.com/auth/chat.bot';

If you navigate to that URL, you will see this 404 error:

Not Found
Error 404

Furthermore, if you check the list of available OAuth2 scopes, you will notice that there are no scopes related to Hangouts or Chat, and there is no mention of the chat.bot the scope which was used in the example code.

What have I tried?

I have read through every question on StackOverflow that is related to this Chat API, plus every tutorial for the REST API.

• The official Apps Script tutorial from Google does not work because the chat.bot scope no longer exists:
  • Async Messages using Apps Script
• These StackOverflow solutions all make use of the same non-existant chat.bot scope:
  • Send private message without event
  • Asynchronously Respond in new Hangout Chat using rest API
  • 404 truncated server response on Apps Script Bot
• This StackOverflow user says they were able to use the chat scope (i.e. googleapis.com/auth/chat), but that scope does not exist either:
  • Error 400: invalid_scope

In conclusion

How to send messages from Google Apps Script to Google Chat using the Google Chat REST API?

It seems that Google's documentation is outdated, and none of the examples for this API work as of August 2020. They are either unaware that their REST API does not work, or they deprecated the REST API without telling anyone.

Answer 1

Answer:

I can confirm that the chat.bot scope does indeed exist. To set up a chat bot with the REST API, you must use a service account.

More Information:

As per the documentation you linked on Developing bots with Apps Script, for sending async messages on trigger:

...the only way to achieve this currently is via the external HTTP API (see documentation). This requires the use of a Cloud service account (see documentation) via the OAuth2 for Apps Script library.

This means, that you must first set up a service account in the GCP console so that the chat.bot scope can be used for these messages. The whole process can be quite arduous for the unintitiated, so I will provide the steps from start to finish here.

The Process:

Creating a Service Account:

• Navigate to the Google Cloud Console and create a new GCP Project. Hit Select a project at the top of the page and click NEW PROJECT.
  • You will need to provide a Project name, the other fields should be filled out for you automatically.
• Press CREATE - a new pop-up will appear in the top-right of the screen confirming that a new project is being created. Once loaded, you can click VIEW.
• Click the ☰ icon in the top-left, and follow the APIs & Services > Credentials menu item.
• At the top of this page, click + CREATE CREDENTIALS > Service Account.
  • Give the service account a name and a description, and press CREATE, followed by CONTINUE, and finally DONE.

Your service account has now been created.

Creating Service Account Credentials:

These will be needed for the code provided in the example from the Developing bots with Apps Script page.

• After creating the Service Account, you will be redirected back to the list of Credentials you can use for the GCP Project. Under the Service Accounts section, click you newly-created service account. This will be called [email protected]
• Click ADD KEY > Create new key
• Keep JSON selected, and press CREATE.
  • This will initiate a download of a credentials file which you will need to use to access the API as this service account. DO NOT LOSE OR SHARE THIS FILE. If lost, you will need to delete and create new credentials for this account.

Enabling the Hangouts Chat API:

• Going back to ☰ > APIs & Services, and select Library.
• Search for Hangouts Chat API and click the only result.
• Click ENABLE. This will enable the API for your project.

Note: Do not close this tab yet! We will still need to use the GCP console later.

Setting up the Apps Script Project:

• Create a new Apps Script project.
• Now, you can copy + paste the example from the Async messages page into the new project.
• Open up that credentials file that you downloaded from the GCP console.
  • Copy the private_key value (the one that starts with -----BEGIN PRIVATE KEY----- and paste it into value of SERVICE_ACCOUNT_PRIVATE_KEY in the Apps Script project.
  • Also copy the client_email value from the credentials file, and paste it into the SERVICE_ACCOUNT_EMAIL in the Apps Script project.

In order to use the Google Apps Script OAuth2 library as in the example, you will need to add the library to the project using the library's script ID.

• In the Apps Script project UI, follow the Resources > Libraries... menu item, and copy paste the OAuth2 script ID into the Add a library box
  • The script ID is 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
  • This, and the rest of the library can be found on the the OAuth2 for Apps Script GitHub repository
• Make sure to select the latest stable version of the library (at time of writing, this is version 38)
• Press Save.

Next, you will need to link the Apps Script project to the GCP project you created earlier.

• Go back to the GCP Console tab, and follow the ☰ > IAM & Admin > Settings menu item.
• Copy the Project number defined on this page.
• In your Apps Script Project, follow the Resources > Cloud Platform project... menu item, and paste the Project number into the Enter Project Number here dialog.
• Click Set Project.

Setting up the Project Manifest: In order to use a chat bot in Apps Script, you must include the chat key in the project's manifest.

• In the Apps Script UI, click View > Show manifest file.
• After the last key-value pair, add the following:

  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  }

Your full manifest file will now look something like this:

{
  "timeZone": "Europe/Paris",
  "dependencies": {
    "enabledAdvancedServices": [{
      "userSymbol": "Drive",
      "serviceId": "drive",
      "version": "v2"
    }],
    "libraries": [{
      "userSymbol": "OAuth2",
      "libraryId": "1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF",
      "version": "38"
    }]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  }
}

• Save your project.

Final Steps:

You're nearly done! Now, you will need to deply the bot from manifest, and set up the configuration in GCP and set up the trigger which will make the actual call.

Deploying the bot:

• In the Apps Script UI, go to Publish > Deploy from manifest... and hit Create in the newly opened dialog.
  • Note: You can not use the Head deployment if you want to use this for your whole domain, so a new deployment must be created.
• Give the deployment a name and description, and press Save.
• Once this has finished saving, press Get ID next to the deployment you just created, and copy the Deployment ID.

Setting up GCP configuration:

• Going back to the Cloud console, you will need to now navigate to ☰ > APIs & Services > Dashboard.
• In the list of enabled APIs at the bottom of this page, select the Hangouts Chat API.
• On the left menu, select Configuration.
• Set up your bot configuration. You will need to provide a Bot name, Avatar URL, and Description. Set up the functionality settings so that it works in rooms.
• Under Connection Settings, select Apps Script project, and paste in your deployment ID from the previous section.
• Give your Apps Script bot the relevant permissions, and press Save.

The Elusive Trigger:

• The only thing you now need to do is set up your trigger. This is done like a normal Apps Script trigger - from the Edit > Current project's triggers menu item in Apps Script. To complete the example, click the + Add Trigger button in the bottom right and set up the trigger settings as follows:

• Choose which function to run: onTrigger

• Choose which deployment should run: Head

• Select event source: Time-driven

• Select type of time based trigger: Minutes timer

• Select minute interval: Every minute

And press save.

And you're done! This created bot will now post to all rooms that it is in the current time, every minute.

References:

• Service accounts | Cloud IAM Documentation
• Understanding service accounts | Cloud IAM Documentation
• Developing bots with Apps Script | Google Chat API | Google Developers
• Bot-initiated messages - Creating new bots | Google Chat API | Google Developers
• GitHub - gsuitedevs/apps-script-oauth2: An OAuth2 library for Google Apps Script.

---

• Google Cloud Console