Documentation

Google Chat

Suggest Edits

You can connect Opal to Google Chat in order to send notifications to users about access reviews and requests. Follow the steps below for setting up an Opal Google Chat app that can send messages to your users.

Create a Project

In the GCP console, create a new project where your chat app will live.

Setup Service Account Credentials

Create a service account for the project, giving it an appropriate name.

Then go to the 'Keys' tab of your service account and create a new JSON key. The key will be downloaded after creation.

Opal uses the non-sensitive https://www.googleapis.com/auth/chat.bot scope for most operations. However, the chat app also needs domain-wide delegation for the readonly directory scope in order to find users and send them direct messages.

To do that, head to domain-wide delegation, select 'Add New', and enter your service accounts client ID, granting it the below scope:

https://www.googleapis.com/auth/admin.directory.user.readonly

Setup Google Chat App

Enable the Google Chat API for the project in the APIs library.

Then go to configure the chat app settings. Set the Application Info as the following:

  • App Name: Opal
  • Avatar URL: https://opal-logos.s3.us-east-2.amazonaws.com/opal-thumbnail-logo.png
  • Description: Chat app for Opal notifications.

Self-hosted

For self-hosted customers, Opal supports interaction through Google Chat messages directly to take actions like approving or denying requests. To do so, we will use pub/sub.

First, create a pub/sub topic in your project here, keep Add a default subscription enabled and leave the other options as the defaults.

  • Name your topic opal-chat.
  • This will create a topic and an associated subscription named opal-chat-sub.
  • Edit the subscription and ensure that the retry policy is Retry after exponential backoff.

Assign the Pub/Sub Publisher role on your project to the following service account :chat-api-push@system .gserviceaccount.com.

Assign the Pub/Sub Subscriber role on the subscription to the service account you created for the chat app above.

Head back to the Google Chat API configuration, toggle on Enable Interactive Features and enter the following settings:

  • Enable Receive 1:1 messages and Join spaces and group conversations.
  • Select Cloud Pub/Sub and enter your topic's name, ie projects/<project-name>/topics/opal-chat.

Leave everything else default and save.

Cloud

For cloud customers, Opal's Google Chat integration does not yet support interactivity. To allow the app to be published and installed into your workspace, head to the Google Chat API configuration, toggle on Enable Interactive Features and enter the following settings:

  • Enable Receive 1:1 messages and Join spaces and group conversations.
  • Select Cloud Pub/Sub and enter the topic name, ie projects/<project-name>/topics/opal-uninteractive-chat.

Leave everything else default and save.

Publish the Chat App

Enable the Google Workspace Marketplace SDK API on your project.

On the App configuration tab, enter the following:

  • App Visibility: Private
  • Installation Settings: Individual + Admin Install
  • App Integration: Chat app
  • For the OAuth scopes, enter https://www.googleapis.com/auth/admin.directory.user.readonly.

For Developer info, enter:

  • Developer Name: Opal
  • Developer Website URL: https://www.opal.dev/
  • Developer Email: [email protected]

Save the draft.

There will be a prompt at the top of the App configuration section about setting up the OAuth consent screen, use it to navigate to the setup page. For the settings, enter:

  • User Type: Internal
  • App Name: Opal
  • User Support Email: Select an appropriate support contact from the dropdown.
  • Developer Contact Information: [email protected]
  • Press Save and continue, then skip the scope section for now by pressing it again.

Navigate back to the Google Workspace Marketplace SDK API page, the warning about the OAuth screen should be gone now. Head to the Store Listing tab to publish the app. Enter the following:

  • Category: Communication
  • Graphics Assets: Use the logo and banner below.
  • Screenshots: Use this screenshot.
  • Terms of Service URL: https://www.opal.dev/tos
  • Privacy Policy URL: https://www.opal.dev/privacy-policy
  • Support URL: https://opal.instatus.com/
  • Regions: Select All Regions.

Save the draft and then publish!

Install the Chat App to Your Workspace

Navigate to the admin console to view the list of apps installed in your workspace.

Search for Opal and select the app. Click on Admin Install, make sure Everyone at your organization is selected, and click Finish

Connect Google Chat To Opal

Navigate to the settings page in the Opal web app and go to the Productivity Integrations tab. There you will see an option to connect a Google Chat Integration. This will prompt you for two pieces of credentials:

  • The service account key JSON that you downloaded earlier
  • The email of an admin user which the chat app can authenticate as to use the domain wide delegated scopes you granted earlier.

Then you're all set! Users will begin to receive notifications about access requests and reviews and can toggle their notifications in their account settings:

Updated 7 days ago