Google Chat

Integration version: 2.0

Product Permissions

Create a service account

1. 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.
2. Click the ☰ Menuand select the APIs & Services > Credentialsmenu item.
3. At the top of the page, click + CREATE CREDENTIALS > Service Account.
4. Enter a service account name to display in the console.
5. Optional: Enter a description of the service account.
6. Click CREATE, followed by CONTINUE, and DONEto finish creating the service account.

Create service account credentials

1. 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 Accountssection, click your newly-created service account. This will be called: service-account-name@project-name-XXXXXX.iam.gserviceaccount.com .
2. Click ADD KEY > Create new key.
3. 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

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

3. 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 
    ), 
     
    }); 
    } 
    
   

4. Open the service account credentials file downloaded from the Google Cloud console.

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

6. Copy the client_email value from the credentials file, and paste it into the SERVICE_ACCOUNT_EMAIL in the Apps Script project.

7. Link the Apps Script project to the Google Cloud project you created.

8. Go back to the Google Cloud console, and select the ☰ > IAM & Admin > Settingsmenu item.

9. Copy the project number defined on this page.

10. In your Apps Script Project, select the Project Settings > Google Cloud Projectmenu item and paste the project number into the Enter Project Number here dialog.

11. Click Set Project.

Enable the Google Chat API

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

This enables the API for your project.

Deploy a bot

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

Configure the Google Chat bot:

1. In the Google Cloud console, go to ☰ > APIs & Services > Dashboard.
2. In the list of enabled APIs, select Google Chat API.
3. Click Manageto open the Google Chat API page.

4. On the opened page, select the Configurationtab and set up your bot configuration:

   • In the App namefield, enter Google Security Operations Chat App.
   • In the Avatar URLfield, enter https://developers.google.com/chat/images/chat-product-icon.png.
   • In the Descriptionfield, enter Google SecOps Chat App that can be used to send messages from Google SecOps to a Google Chat Spaces.
   • In the Functionalitysection, select App works in spaces with multiple users.
   • In the Connection settingssection, select Apps Script projectand paste the deployment ID obtained from the Deploy a bot procedure.
   • In the Permissionssection, select Specific people and groups in your domainand 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 SecOps 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 SecOps 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 SecOps

For detailed instructions on how to configure an integration in Google SecOps, 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

List Spaces

Description

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

Parameters

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

Send Message

Description

Send a message to a Google Chat space that the Google SecOps 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.

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

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 .

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

Need more help? Get answers from Community members and Google SecOps professionals.