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 service-account-name@project-name-XXXXXX.iam.gserviceaccount.com
- 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
- 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!"
}
}
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:
