Skip to main content

Google Chat

Google Chat is a web-based messaging application offered as part of the Google Workspace suite. Chat allows you to send direct messages and hold group conversations to power collaboration across your team.

Like Slack and Teams, you can connect Google Chat both as a communication tool, enabling you to send messages and interact with your process contributors, and as a data source, enabling you to monitor your Google Chat instance and collect user, space, and message entities—as well as invite users to spaces. However, unlike other messaging applications, Google Chat requires additional configuration in the Google Workspace and Google Admin Console. An admin must create the relevant apps in the Google Cloud Console to enable Tonkean to communicate with Google Chat.

Creating, configuring, and publishing the required apps in the Google Cloud Console requires API knowledge and Google Cloud Admin privileges. Only admins should perform the Google Cloud project setup and configuration processes.

Prerequisites

To perform the setup and configuration steps to enable using Google Chat as a communication tool and data source, you must be an administrator with the relevant permissions in your organization's Google Cloud instance.

Set Up the Google Chat App to Connect Google Chat as a Communication Tool

To set up Google Chat as a communication tool in Tonkean, you must create an app and connect the Google Chat API in the Google Cloud Console.

Enable and Configure the Google Chat API

The Google Chat API enables your workspace instance to connect to Tonkean.

Create a Project and Enable APIs

  1. Navigate to Google Cloud Console.

  2. Create a new Google Cloud project.

  3. Select the project dropdown in the top navigation bar and select your newly created project.

    console_comm_tool_select_project.png

  4. In the sidenav, select APIs & Services > Enabled APIs and services. The APIs & Services screen displays.

    console_comm_tool_enabled_apis___services.png

  5. Select + ENABLE APIS AND SERVICES. The API Library screen displays.

    console_comm_tool_apis___services_select.png

  6. In the API Library search bar, enter "Google Chat API" and select Enter. Search results display.

    console_comm_tool_search_google_chat_api.png

  7. Select the Google Chat API result. The Google Chat API product details screen displays.

    console_comm_tool_gchat_api_select.png

  8. Select ENABLE. The Google Chat API Service Details screen displays.

    console_comm_tool_gchat_api_enable.png

Configure the Google Chat App

Configure your Google Chat app, powered by the Google Chat API.

  1. On the Google Chat API Service Details screen, select the CONFIGURATION tab. The Configuration tab displays.

    console_comm_tool_api_config_select.png

  2. Enter values for the following fields:

    • App name (required) - A descriptive name for your app. Using a unique name ensures you can locate your app in the app selection menu. We recommend {Your org} Google Chat.

    • Avatar URL (required) - Tonkean logo: https://tonkean-images.s3.amazonaws.com/assets/logo-square-logo-5-gchat.png

    • Description (required) - A brief description of the app.

    console_comm_tool_api_config_app_info.png

  3. In the Interactive features section, perform the following steps:

    1. Ensure the Enable Interactive features toggle is turned on. This option is enabled by default.

    2. In the Functionality subsection, select both Receive 1:1 messages and Join spaces and group conversations checkboxes.

    3. In the App URL field, enter http://api.tonkean.com/webhooks/gchat/events.

      console_comm_tool_api_config_interactive_features.png

    4. In the Visibility section, deselect the Make this Chat app available to specific people and groups in {org} checkbox.

      console_comm_tool_api_config_vis_checkbox.png

      To test the Google Chat API app as an admin, select this checkbox and enter your email address or relevant domain. This makes the app available to add to your workspace and test in a Tonkean module.

    When finished configuring these options, select SAVE in the lower left. A success message displays: Configuration saved.

  4. Refresh the page and scroll to the top of the screen. A new field, App status, displays at the top of the Configure screen. Select the App status dropdown to set the status to LIVE - available to all users.

    console_comm_tool_api_config_app_status.png

Create a Service Account and Create API Key

With the Google Chat app created and basic configuration complete, you can create a service account and set up the credentials for the account.

Create a Service Account

  1. In the API Service Details screen, select the CREDENTIALS tab. The Credentials tab displays.

    console_comm_tool_api_creds_select.png

  2. Select Manage service accounts in the lower right. The Service accounts screen displays.

    console_comm_tool_api_creds_mng_serv_accounts.png

  3. In the top navigation bar, select + CREATE SERVICE ACCOUNT. The Create service account screen displays.

    console_comm_tool_api_serv_accounts_create.png

  4. Enter the required information in the Service account details step. For more information on Google service accounts, see Create service accounts.

    console_comm_tool_api_create_serv_accounts_acct_details.png

  5. When finished entering the service account details, select CREATE AND CONTINUE.

    console_comm_tool_api_create_serv_accounts_acct_details_cont.png

  6. Skip optional steps #2 and #3 below and select DONE. The Service accounts screen displays, featuring your newly created service account.

    console_comm_tool_api_serv_accounts_created.png

Create an API Key

  1. On the Service accounts screen, select the kebab (three-dots) icon in the Actions column of your newly created service account, then select Manage keys. The Keys screen displays.

    console_comm_tool_api_serv_accounts_mng_keys.png

  2. Select ADD KEY > Create new key. The Create private key window displays.

    console_comm_tool_api_serv_accounts_create_new_key.png

  3. Select the Key type JSON and select CREATE. The private key downloads to your computer as a JSON file.

    The downloaded key allows access to your Google Cloud resources, so make sure it's stored securely.

    console_comm_tool_api_serv_accounts_create_key_json.png

  4. Select CLOSE to close the window.

    console_comm_tool_api_serv_accounts_create_key_json_close.png

With the API key generated for your service account, you can set up a new Google Chat communication tool in Tonkean.

Add Google Chat as a Communication Tool in Tonkean

With your Google Chat app and service account set up, you can add Google Chat as a communication tool in Tonkean.

  1. In Tonkean, select the main nav icon, grid.png, in the upper left and select Enterprise Components. The Enterprise Components screen displays.

  2. Select the Communication Tools tab. The Communication Tools screen displays.

    select_comm_sources_tab.png

  3. In the Google Chat section, select New Instance. The Set Up Data Source window displays.

    new_comm_tool_instance.png

  4. Navigate to the service account private key JSON file you downloaded in Create an API Key and copy the entire contents of the file into the Service Account Key Json field.

    set_up_data_source_serivce_account_key_json.png

  5. Enter the Project Number of your Google Cloud Console project.

    set_up_data_source_project_number.png

    To locate this value in the Google Cloud Console, follow the steps below:

    1. In the Google Cloud Console, select the main nav (hamburger) icon in the upper left.

    2. Select Cloud overview > Dashboard. The Dashboard screen displays.

      console_dashboard_select.png

    3. The Project number displays in the Project info section in the upper left.

      console_proj_number.png

    The project number also displays on the Welcome screen. Select the Google Cloud logo in the upper left to navigate to the Welcome screen and ensure you select the desired project in the project dropdown.

  6. When finished, select Connect. A new Google Chat instance displays.

    google_chat_new_instance.png

  7. Select the more arrow beside the Edit button and select Set Default.

    Due to a known issue, Google Chat must be set as your default communication tool in order to work properly.

    google_chat_instance_set_as_default.png

Sync Process Contributors from Google Chat

After you configure the Google Chat app in the Google Cloud Console and connect it as a communication tool, you can sync users from your Google Workspace and add them as process contributors in Tonkean. This ensures your Google Workspace users can receive Google Chat messages through Tonkean workflows.

To sync Google Chat users to Tonkean as process contributors, see Add Process Contributors through a Communication Tool.

You must sync users from Google Chat before you install the Google Workspace Marketplace app for your org.

Add the App to your Google Chat Workspace

Add your app to your workspace to allow your Tonkean workflows to send messages to that workspace.

An admin must publish and install the app internally for it to be available to add to your workspace.

Add the App to your Chat Section

  1. Navigate to your Google Chat workspace.

  2. In the sidenav, select the plus icon, +, and select Find apps. The Find apps window displays.

    chat_wkspc_find_apps.png

  3. In the provided field, search for your app name and select your app. The app displays.

    chat_wkspc_find_apps_search.png

  4. Select Chat. The app is added to the Chat section in the sidenav.

    chat_wkspc_find_apps_chat.png

Add the App to your Spaces

You must have an existing space to add the app to.

  1. Navigate to your Google Chat workspace.

  2. In the sidenav, select the plus icon, +, and select Find apps. The Find apps window displays.

    chat_wkspc_find_apps_spaces.png

  3. In the provided field, search for your app name and select your app. The app displays.

    chat_wkspc_find_apps_search.png

  4. Select Add to space. Your available spaces display.

    chat_wkspc_find_apps_add_to_space.png

  5. Select the space you want to add the app to, then select Add. The app is added to your space.

    chat_wkspc_find_apps_add_to_space_select.png

Set Up Google Admin App to Connect Google Chat as a Data Source

In addition to adding Google Chat as a communication tool, you can add it as a data source, enabling you to collect users, space, and messages—as well as create spaces.

To set up Google Chat as a data source in Tonkean, you must create an app and connect the Admin SDK API in the Google Cloud Console. This app enables Tonkean to connect to your Google Chat Workspace and collect the necessary entities.

You must complete the setup process for the Google Chat app before creating the Admin SDK app.

Enable and Configure the Admin SDK API

Set up the Google Admin SDK app.

  1. Navigate to Google Cloud Console.

  2. Create a new Google Cloud project or, if you already have a project in which you created and configured an app to add Google Chat as a communication tool, open that same project.

    If you want to enable the use of Google Chat as both a communication tool and a data source, you must create and configure the respective APIs in the same project.

  3. In the sidenav, select APIs & Services > Enabled APIs and services. The APIs & Services screen displays.

    console_comm_tool_enabled_apis___services.png

  4. Select + ENABLE APIS AND SERVICES. The API Library screen displays.

    console_comm_tool_apis___services_select.png

  5. In the API Library search bar, enter "Admin SDK API" and select Enter. Search results display.

    console_data_src_api_lib_search_admin_sdk.png

  6. Select the Admin SDK API result. The Admin SDK API product details screen displays.

    console_data_src_admin_sdk_api_select.png

  7. Select ENABLE. The Admin SDK API Service Details screen displays.

    console_data_src_admin_sdk_api_enable.png

Configure the Admin SDK App Credentials and Scopes

Configure your Admin SDK app, powered by the Admin SDK API.

  1. In the API Service Details screen, select the CREDENTIALS tab. The Credentials tab displays.

    console_data_src_admin_sdk_credentials_select.png

  2. Select CONFIGURE CONSENT SCREEN. The OAuth consent screen displays.

    console_data_src_admin_sdk_config_consent_select.png

  3. Set the User Type to Internal and select CREATE. The Edit app registration screen displays, beginning on Step #1 of the app registration process: OAuth consent screen.

    console_data_src_admin_sdk_oauth_user_type_internal.png

  4. Complete the required App information fields:

    • App name - The name of the app asking for consent.

    • User support email - The address where users can contact you with questions regarding their consent.

    console_data_src_admin_sdk_edit_app_reg.png

  5. Enter one or more Email addresses in the Developer contact information section.

    console_data_src_admin_sdk_edit_app_reg_dev_contact.png

  6. When finished, select SAVE AND CONTINUE. The app registration process moves to Step #2: Scopes.

  7. Select ADD OR REMOVE SCOPES. The Update selected scopes panel displays.

    console_data_src_admin_sdk_edit_app_reg_scopes_select.png

  8. Select the following scopes, to include all Google Chat and available user directory scopes.

    We recommend adding scopes that are not currently required for setting up Tonkean as a data source in order to support future Tonkean data actions.

    • chat.messages

    • chat.messages.readonly

    • chat.spaces

    • chat.spaces.readonly

    • chat.memberships

    • chat.memberships.readonly

    • chat.messages.reactions

    • chat.messages.reactions.readonly

    • chat.messages.create

    • chat.spaces.create

    • chat.delete

    • chat.memberships.app

    • chat.messages.reactions.create

    • chat.admin.spaces.readonly

    • admin.directory.user.security

    • admin.directory.user

    • admin.directory.user.readonly

    When finished, select UPDATE. The added scopes display on the Edit app registration screen.

  9. When finished adding scopes, select SAVE AND CONTINUE. The app registration process moves to Step #3: Summary.

  10. Confirm the information is correct, then scroll to the bottom of the screen and select BACK TO DASHBOARD. The OAuth consent screen displays.

  11. In the sidenav, select Credentials. The Credentials screen displays.

    console_data_src_admin_sdk_creds_select.png

  12. Select + CREATE CREDENTIALS > OAuth client ID. The Create OAuth client ID screen displays.

    console_data_src_admin_sdk_creds_create_creds_oauth.png

  13. Set Application type to Web application and enter a Name for your OAuth 2.0 client.

    console_data_src_admin_sdk_create_oauth_client.png

  14. In the Authorized JavaScript origins section, select + ADD URI and enter the relevant URI. For most users, this is https://tracks.tonkean.com.

    This URI may vary for users on a private deployment of Tonkean. Contact customer support for more information if you're unsure.

    console_data_src_admin_sdk_create_oauth_client_js_origin.png

  15. In the Authorized redirect URIs section, select + ADD URI and enter https://tracks.tonkean.com/oauth.html.

    console_data_src_admin_sdk_create_oauth_client_redirect_uri.png

  16. When finished, select CREATE. The OAuth client created window displays.

  17. Copy the Client ID and Client secret and paste these into a separate document. When finished, select OK.

    console_data_src_admin_sdk_create_oauth_client_created.png

  18. Retrieve your Customer ID:

    1. Navigate to the Google Admin Console.

    2. Select the Menu > @ Account > Account settings > Profile. The Profile screen displays.

    3. Your organization's unique ID displays beside the Customer ID field.

Your Google Chat admin app is created and configured. You're ready to add Google Chat as a data source in Tonkean.

Add Google Chat as a Data Source in Tonkean

To add Google Chat as a data source, follow the steps below:

  1. Select the main nav icon, grid.png, in the upper left and select Enterprise Components. The Enterprise Components screen displays.

  2. Select + New Data Source in the upper right.

    connect_data_sources_add_data_source.png

  3. Select Cloud Application from the dropdown. The Add New Data Source window displays.

    add_cloud_application.png

  4. Enter "Google Chat" in the search field, then select Google Chat. The Set Up Integration window displays.

    data_source_add_gchat.png

  5. Enter the Connection Parameters, retrieving the values you retrieved in Step #17 and #18 of the Configure the Admin SDK API App section:

    • Client ID

    • Client Secret

    • Customer ID

    • Space ID (Optional) - The space ID enables users to collect the Message entity. To locate the space ID, navigate to your Google Chat instance and select a space. The space ID is the last string in the URL, after space/.

      chat_wkspc_find_space_id.png
    data_source_gchat_set_up_integration.png

    When finished, select Create. The Google authentication window displays.

  6. Sign in using the appropriate Google account with admin privileges. The permissions window for your Admin OAuth app displays.

  7. Review the permissions and select Allow. The window closes and the Google Chat data source screen displays.

    {Must be Google Cloud Console admin}

    data_source_gchat_set_up_integration_grant_oauth_app_perms.png

Create and Publish Workspace Marketplace App

To enable users in your org to find and add your Tonkean app to their workspace, you must create and publish the app for all workspace users in the Google Workspace Marketplace.

You must have created and configured your Google Chat API app before beginning this process.

Enable the Workspace Marketplace SDK API

  1. Navigate to Google Cloud Console.

  2. In the search bar, enter "Google Workspace Marketplace SDK" and select Search. Search results display.

  3. Select Google Workspace Marketplace SDK. The Google Workspace Marketplace SDK product details screen displays.

    console_workspace_mrktplc_sdk_results.png

  4. Select ENABLE. The service is enabled and the Google Workspace Marketplace SDK Service Details screen displays.

    console_workspace_mrktplc_sdk_enable.png

Configure the Workspace Marketplace SDK App

  1. On the Google Workspace Marketplace SDK Service Details screen, select the APP CONFIGURATION tab. The App Configuration tab displays.

    console_workspace_mrktplc_sdk_app_config_select.png

  2. Enter the relevant information for your app:

    • App Visibility - Private.

    • Installation Settings - Individual + Admin Install

    • App Integration - Chat App

    console_workspace_mrktplc_sdk_app_config_options.png

  3. Enter your developer information:

    • Developer Name - Enter your name so users know who to contact if they encounter problems with the app.

    • Developer Website URL - Enter your organization's website or other relevant URL.

    • Developer Email - Enter the email Google can use to contact you about your app.

    console_workspace_mrktplc_sdk_app_config_dev_info.png

  4. When finished, select SAVE.

Set Up OAuth and Scopes

If you already set up the OAuth consent as part of configuring the Admin SDK app, some parts of this process are already complete, such as the App Visibility being set to Private.

  1. In the sidenav, select OAuth consent screen. The OAuth consent screen screen displays.

    console_workspace_mrktplc_sdk_oath_consent_select.png

  2. Set the User Type to Internal and select CREATE. The Edit app registration screen displays, beginning on Step #1 of the app registration process: OAuth consent screen.

    console_data_src_admin_sdk_oauth_user_type_internal.png

  3. Complete the required App information fields:

    • App name - The name of the app asking for consent.

    • User support email - The address where users can contact you with questions regarding their consent.

    console_data_src_admin_sdk_edit_app_reg.png

  4. Enter one or more Email addresses in the Developer contact information section.

    console_data_src_admin_sdk_edit_app_reg_dev_contact.png

  5. When finished, select SAVE AND CONTINUE. The app registration process moves to Step #2: Scopes.

  6. Select SAVE AND CONTINUE.

    console_workspace_mrktplc_sdk_oauth_consent_scopes.png
Configure the App Store Listing

  1. In the sidenav, select Enabled APIs & services. The Enables APIs & services screen displays.

    console_workspace_mrktplc_sdk_oauth_enabled_apis_select.png

  2. Select Google Workspace Marketplace SDK. The Google Workspace Marketplace SDK Service Details screen displays.

    console_workspace_mrktplc_sdk_app_select.png

  3. Select the STORE LISTING tab. The Store Listing tab displays.

    console_workspace_mrktplc_sdk_app_store_listing_select.png

  4. Select the Edit Language dropdown. the Edit Language section displays.

    console_workspace_mrktplc_sdk_app_store_listing_edit_lang.png

  5. Enter a Detailed Description for your app, then select DONE.

    console_workspace_mrktplc_sdk_app_store_listing_edit_lang_desc.png

  6. Select a Category.

    The specific category you select is irrelevant when publishing the app internally, but Category is a required field.

    console_workspace_mrktplc_sdk_app_store_listing_edit_category.png

  7. Add an Application Icon 32x32. We recommend this Tonkean logo.

    console_workspace_mrktplc_sdk_app_store_listing_edit_icon.png

  8. Upload a Screenshot.

    console_workspace_mrktplc_sdk_app_store_listing_screenshot.png

  9. Add the support links provided below:

    console_workspace_mrktplc_sdk_app_store_listing_support_links.png

  10. In the Distribution section, select the All Regions checkbox.

    console_workspace_mrktplc_sdk_app_store_listing_distribution.png

  11. When finished, select SAVE, then select PUBLISH to publish your app. Your app is published.

    When successfully published, the UNPUBLISH button displays.

Install the Workspace Marketplace SDK App for Internal Users

With your workspace marketplace app published, you can install it for users in your organization.

Users must log in to their Google Chat instance to complete the installation of the app and allow Tonkean to collect relevant events.

  1. Navigate to the Google Workspace Admin Console and sign in using your admin account.

  2. In the sidenav, select Apps > Google Workspace Marketplace apps > Apps list. Your installed Workspace Marketplace apps display.

    admin_console_apps_select.png

  3. Select INSTALL APP. The Google Workspace Marketplace displays.

    admin_console_apps_install_app.png

  4. In the provided field, search for your app by name or keyword and select your app from the results. The app detail screen displays.

  5. Select ADMIN INSTALL. An installation confirmation window displays.

  6. Select CONTINUE.

  7. Select which users to install the app for:

    • Everyone at your organization - Install the app for all users.

    • Certain groups or organized units - Install the app for selected users.

    When finished, a success message displays. Select DONE.

Your app is installed for users in your organization.

In this section: