Google Chat

Integration version: 2.0

Product Permissions

Create a service account

In the Google Cloud console, select an existing Google Cloud project or create a new one. Note that the selected Google Cloud project should be a part of the Organization in Google Cloud.
Click the ☰ Menu and select the APIs & Services > Credentials menu item.
At the top of the page, click + CREATE CREDENTIALS > Service Account.
Enter a service account name to display in the console.
Optional: Enter a description of the service account.
Click CREATE, followed by CONTINUE, and DONE to finish creating the service account.

Create service account credentials

After creating the service account, you will be redirected to the list of credentials you can use for the Google Cloud project. Under the Service Accounts section, click your 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 click CREATE.

This initiates downloading the credentials file that you will need to access the API as this service account.

Set up a new Apps Script project

Go to Google Apps Script.
Create a new Apps Script project.

To execute the integration functionality, add the following code to the newly created project:

var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Open the service account credentials file downloaded from the Google Cloud console.
Copy the private_key value (the one that starts with -----BEGIN PRIVATE KEY-----) and paste it into SERVICE_ACCOUNT_PRIVATE_KEY in the Apps Script project.
Copy the client_email value from the credentials file, and paste it into the SERVICE_ACCOUNT_EMAIL in the Apps Script project.
Link the Apps Script project to the Google Cloud project you created.
Go back to the Google Cloud console, and select the ☰ > IAM & Admin > Settings menu item.
Copy the project number defined on this page.
In your Apps Script Project, select the Project Settings > Google Cloud Project menu item and paste the project number into the Enter Project Number here dialog.
Click Set Project.

Enable the Google Chat API

Go to ☰ > APIs & Services, and select Library.
Search for Google Chat API and click the only result.
Click ENABLE.

This enables the API for your project.

Deploy a bot

In the Apps Script UI, go to Deploy > New Deployment.
Select Add On for the new deployment type.
Enter a deployment name and description, and click Save.
Once saving is finished, click Get ID next to the deployment you just created, and copy the deployment ID value.

Configure the Google Chat bot:

In the Google Cloud console, go to ☰ > APIs & Services > Dashboard.
In the list of enabled APIs, select Google Chat API.
Click Manage to open the Google Chat API page.
On the opened page, select the Configuration tab and set up your bot configuration:
- In the App name field, enter Google Security Operations SOAR Chat App.
- In the Avatar URL field, enter https://developers.google.com/chat/images/chat-product-icon.png.
- In the Description field, enter Google Security Operations SOAR Chat App that can be used to send messages from Google Security Operations SOAR to a Google Chat Spaces.
- In the Functionality section, select App works in spaces with multiple users.
- In the Connection settings section, select Apps Script project and paste the deployment ID obtained from the Deploy a bot procedure.
- In the Permissions section, select Specific people and groups in your domain and specify who should be able to interact with the bot.
- Click Save. App configuration is completed.

As the Google Chat app can't create spaces (initiate conversations), the Google Security Operations SOAR Chat app needs to be added to the spaces it should send messages to.

After the integration is configured, the "List Spaces" action can be used to fetch the spaces that the Google Security Operations SOAR app has access to (can send messages to).

If the "List Spaces" action shows no available spaces, it means your app will not be able to send messages in any space. Please go back to the detailed instructions above and make sure you followed each step carefully

Configure Google Chat integration in Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

Parameter Display Name	Type	Default Value	Is Mandatory	Description
API Root URL	String	https://chat.googleapis.com/	Yes	API Root URL the integration uses to connect to the Google Chat service.
Service Account	Password	N/A	Yes	Service account JSON file content that the chatbot uses to work with the Google Chat service.
Verify SSL	Checkbox	Checked	Yes	If enabled, verify that the SSL certificate for the connection to the Google Chat service is valid.

Actions

Ping

Description

Test connectivity to Google Chat with parameters provided at the integration configuration page in the Google Security Operations Marketplace tab.

Run On

This action doesn't run on entities, nor has mandatory input parameters.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result type	Value/Description	Type
Output message*	The action should not fail nor stop a playbook execution: If successful: "Successfully connected to the Google Chat service with the provided connection parameters!" The action should fail and stop a playbook execution: If critical error, like wrong credentials or lost connectivity is reported: "Failed to connect to the Google Chat service! Error is {0}".format(exception.stacktrace)"	General

Result type

Value/Description

Type

Output message*

The action should not fail nor stop a playbook execution:

If successful: "Successfully connected to the Google Chat service with the provided connection parameters!"

The action should fail and stop a playbook execution:

If critical error, like wrong credentials or lost connectivity is reported: "Failed to connect to the Google Chat service! Error is {0}".format(exception.stacktrace)"

General

List Spaces

Description

List spaces that the currently configured Google Chat bot was added to.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Filter Key	DDL	Select One Possible Values: Name Display Name Type	No	Specify the key that needs to be used to filter Google Chat spaces.
Filter Logic	DDL	Not Specified Possible Values: Not Specified Equal Contains	No	Specify what filter logic should be applied. Filtering logic is working based on the value provided in the "Filter Key" parameter.
Filter Value	String	N/A	No	Specify what value should be used in the filter. If "Equal" is selected, action tries to find the exact match among results. If "Contains" is selected, action tries to find results that contain the specified substring. If nothing is provided in this parameter, the filter is not applied. Filtering logic is working based on the value provided in the "Filter Key" parameter.
Max Records To Return	Integer	50	No	Specify the number of records to return. If nothing is provided, action returns 50 records.
Include User Memberships	Checkbox	Unchecked	No	If enabled, user memberships information is added to the action Case Wall table and JSON result.

Run on

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If data is available (is_success=true): "Successfully found added spaces for the provided criteria in Google Chat." If data is not available (is_success=false): "No spaces were found for the provided criteria in Google Chat" If the "Filter Value" parameter has no value (is_success=true): "The filter was not applied, because parameter "Filter Value" has an empty value." The action should fail and stop a playbook execution: If the Filter Key parameter is set to "Select One" and the Filter Logic parameter is set to "Equal" or "Contains": "Error executing action "List Spaces". Reason: you need to select a field from the "Filter Key" parameter." If an invalid value is provided for the Max Records to Return parameter: "Error executing action "List Spaces". Reason: "Invalid value was provided for "Max Records to Return". Positive number should be provided." If a fatal error, like wrong credentials, no connection to server, other is reported: "Error executing action "List Spaces". Reason: {0}''.format(error.Stacktrace)	General
Case Wall Table	Table Name: Available Spaces Bot was Added to Table Columns: {fields} Note: If the "Include User Memberships" checkbox is checked, additional column that have a Display Name for the space members are added.	General

Result Type

Value / Description

Type

Output message*

The action should not fail nor stop a playbook execution:

If data is available (is_success=true): "Successfully found added spaces for the provided criteria in Google Chat."

If data is not available (is_success=false): "No spaces were found for the provided criteria in Google Chat"

If the "Filter Value" parameter has no value (is_success=true):

"The filter was not applied, because parameter "Filter Value" has an empty value."

The action should fail and stop a playbook execution:

If the Filter Key parameter is set to "Select One" and the Filter Logic parameter is set to "Equal" or "Contains":

"Error executing action "List Spaces". Reason: you need to select a field from the "Filter Key" parameter."

If an invalid value is provided for the Max Records to Return parameter:

"Error executing action "List Spaces". Reason: "Invalid value was provided for "Max Records to Return". Positive number should be provided."

If a fatal error, like wrong credentials, no connection to server, other is reported:

"Error executing action "List Spaces". Reason: {0}''.format(error.Stacktrace)

General

Case Wall Table

Table Name: Available Spaces Bot was Added to Table Columns: {fields}

Note: If the "Include User Memberships" checkbox is checked, additional column that have a Display Name for the space members are added.

General

Send Message

Description

Send a message to a Google Chat space that the Google Security Operations SOAR application was added to.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Space Name	String	N/A	Yes	Specify the space name to send the message to. Example space name: AAAAdaTsel0
Message Text	String	N/A	Yes	Specify the text of the message to send.

Parameter Display Name

Type

Default Value

Is Mandatory

Description

Space Name

String

N/A

Yes

Specify the space name to send the message to.

Example space name: AAAAdaTsel0

Message Text

String

N/A

Yes

Specify the text of the message to send.

Run on

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If a message is sent successfully (is_success=true): "Message was sent successfully." The action should fail and stop a playbook execution: If a critical error, like no connection or wrong credentials is reported: "Error executing action "Send Message". Reason: {0}''.format(error.Stacktrace)	General

Result Type

Value / Description

Type

Output message*

The action should not fail nor stop a playbook execution:

If a message is sent successfully (is_success=true): "Message was sent successfully."

The action should fail and stop a playbook execution:

If a critical error, like no connection or wrong credentials is reported: "Error executing action "Send Message". Reason: {0}''.format(error.Stacktrace)

General

Send Advanced Message

Description

Send an advanced message to a Google Chat space based on the provided message JSON payload.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Space Name	String	N/A	Yes	Specify the space name to send the message to. Example space name: AAAAdaTsel0
Message JSON Payload	String	{"cards":[{"sections":[{"widgets":[{"image":{"imageUrl":"https://..."}},{"buttons":[{"textButton":{"text":"OPEN IN GOOGLE MAPS","onClick":{"openLink":{"url":"https://..."}}}}]}]}]}]}	Yes	Specify the JSON payload to send with the message. For examples of a messages payload, see this article.

Parameter Display Name

Type

Default Value

Is Mandatory

Description

Space Name

String

N/A

Yes

Specify the space name to send the message to.

Example space name: AAAAdaTsel0

Message JSON Payload

String

{"cards":[{"sections":[{"widgets":[{"image":{"imageUrl":"https://..."}},{"buttons":[{"textButton":{"text":"OPEN IN GOOGLE MAPS","onClick":{"openLink":{"url":"https://..."}}}}]}]}]}]}

Yes

Specify the JSON payload to send with the message.

For examples of a messages payload, see this article.

Run on

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If a message is sent successfully (is_success=True): "Message was sent successfully." The action should fail and stop a playbook execution: If the provided JSON payload is not valid: "Error executing action "Send Advanced Message". Reason: the provided message JSON payload is not valid. " If a critical error, like no connection or wrong credentials is reported: "Error executing action "Send Advanced Message". Reason: {0}''.format(error.Stacktrace)	General

Result Type

Value / Description

Type

Output message*

The action should not fail nor stop a playbook execution:

If a message is sent successfully (is_success=True): "Message was sent successfully."

The action should fail and stop a playbook execution:

If the provided JSON payload is not valid: "Error executing action "Send Advanced Message". Reason: the provided message JSON payload is not valid. "

If a critical error, like no connection or wrong credentials is reported: "Error executing action "Send Advanced Message". Reason: {0}''.format(error.Stacktrace)

General