Overview

Reveal Hold supports integration with Slack for data collection. This document describes the prerequisites for integrating Reveal Hold with Slack.

Information Required for Integration

Reveal Hold Slack connectors integrate with Slack through APIs and require a service account.

Create a Slack App

Follow the below steps to create an app with the required permissions.

1. Navigate to https://api.slack.com/apps with a user having Admin privileges to the Slack workspaces.

2. After successful sign in, Create New App button will be displayed as shown in image below. Click on Create new app button to create an application.

Figure: Slack API - Apps

3. Enter the App Name and select the Slack workspace in which this app will be created and click on the Create App button.

Figure: Create a Slack App

4. On successful creation of the application, click on OAuth & Permission tab on the left side menu. Scroll upto the Scopes section and click on Add an OAuth Scope button.

Figure: Scopes

5. Under the Scopes section, select following scopes for the different categorized scopes.

   1. Bot Token Scopes:

      1. users:read.email

      2. users:read

      3. channels:read

      4. groups:read

      5. im:read

      6. mpim:read

      7. channels:history

      8. Groups:history

      9. im:history

      10. Mpim:history

      11. files:read

   2. User Token Scopes:

      1. users:read.email

      2. users:read

      3. channels:read

      4. groups:read

      5. im:read

      6. mpim:read

      7. channels:history

      8. Groups:history

      9. im:history

      10. Mpim:history

      11. files:read

6. Click on Install App to workspace.

Figure: Install App to Workspace

7. Click the Allow button to grant permission to the app to access workspace.

Figure: Allow Permission to Workspace

8. The application is now installed successfully in the workspace and OAuth access token is provided.

Figure: OAuth Access Token

9. Copy the OAuth Access Token and share it to configure it in the Reveal Hold system.

10. If there are multiple workspaces, repeat above steps for each workspace.

Create Slack App in Enterprise

1. Open https://api.slack.com/.  The below portal will be launched.

Figure: Slack API

2. Click on the StartBuilding button and the Create a Slack App popup appears.

Figure: Create a Slack App Popup

3. Enter an App Name and select the Workspace on which to create the app. On successful creation of the app, the following page appears.

Figure: Basic Information Page

4. Select the OAuth & Permissions option under the Features menu.

5. Add the following scopes to the User Token Scopes and Bot Token Scopes.

   1. users:read.email

   2. users:read

   3. channels:read

   4. groups:read

   5. im:read

   6. mpim:read

   7. channels:history

   8. Groups:history

   9. im:history

   10. Mpim:history

   11. files:read

Figure: Bot Token and User Token Scopes

6. Click on the Install App to Workspace button to install the app in the respective workspace.

Figure: Install App to Workspace

7. On clicking the Install App to Workspace button, the following popup will be displayed. Click on the Allow button to grant the permission for the app to install in the workspace.

Figure: Allow Permission

8. On successful installation, the Oauth Access Token and Bot User OAuth Access Token will be generated as shown below. The OAuth Access Token can be used to get the conversation details of a user belonging to the respective workspace.

Figure: OAuth Tokens

Create Slack ORG Token

Follow the steps given below to generate an Org API Token.

1. Go to https://api.slack.com/apps/ and click the Create New App button.

2. In the modal that appears, enter the App Name and select a Workspace that belongs to your Org from the dropdown. (Any workspace can be chosen from the list. It does not matter which one is chosen).

Figure: Create a Slack App Modal

3. Click the Create App button to proceed.

4. Go to OAuth & Permissions in the left navigation menu. Scroll down to the Redirect URLs section and click the Add New Redirect URL option.

5. Enter  https://localhost in the input box and click Add. Then click Save URLs.

Figure: OAuth Tokens and Redirect URLs

6. Scroll down to the Scopes section. The appropriate scopes can be added to the app from this section. Add the appropriate scopes to the User Token Scopes section. The required scopes For Org APP include:

   1. Discovery:read (includes Data Hold feature; this scope can only be added by Slack Team)

   2. Files:read

   3. Admins.teams.read

Figure: User Token Scopes

7. Now that proper Permission Scopes and OAuth Redirect URLs have been configured for the app, the app distribution needs to be activated. This is a necessary step to activate the app on an Org level to generate the token. Go to Manage Distribution in the left navigation and scroll down to the Share your App with Other Workspaces section.

Figure: Share App with Workspaces

8. Click on Remove Hard Coded Information to expand the field and access the last required checkbox. Tick the box that says I’ve reviewed and removed any hard-coded information.

Figure: Remove Hard Coded Information

9. Verify that all four green tick marks are available next to the required steps under the Share Your App with Other Workspaces section. The Activate Public Distribution button should become enabled. Click on the button to active public distribution and the page will reload.

Figure: Activate Public Distribution

10. After the page reloads, copy the Shareable URL.

Figure: Shareable URL

11. Open a new incognito/private browser window and log into the enterprise grid URL <organization-domain>.enterprise.slack.com using the Org Owner credentials. Org Owner login is needed in most cases to install the app to the Enterprise Grid Org.

12. From the Workspace Directory landing page, click the Launch in Slack button to open any workspace in a new tab.

Figure: Workspaces Directory

13. After logging in and loading a workspace, open an additional browser tab and enter the Shareable URL (copied in step 10) into the browser’s address bar to initiate the OAuth handshake that will install the app on Org. On the OAuth page, verify that the dropdown in the upper right corner of the installation screen reflects the Enterprise Grid Organization and not an individual workspace within the organization. Click Allow once it is confirmed.

Figure: Allow Access to Org Workspace

14. Once the OAuth process is completed the user is redirected back to the localhost. The page will most likely show a 404 error. However this is expected and the needed information is in the URL address bar. Copy and save the value for code from the URL. Do not include the preceding equal sign (=) nor the terminating ampersand (&).

Figure: LocalHost

15. Navigate back to the Basic Information section in the left navigation of the Slack App and copy the Client ID and Client Secret.

Figure: Basic Information

16. Build a URL string using the three pieces of information that have been collected so far: Code, Client ID and the Client Secret (copied from steps 14 and 15).

https://slack.com/api/oauth.v2.access?code=8351753648.22312133905.eb189 d3a499f74989c3ba9bf6aa9c7802616df9dd87015be638bd5fb793128ce&client_id=1

6115454624.23409468640&client_secret=63f4fc0bee2d0eaa2fa83c7a25bed7de

Be sure to replace only the bold sections in the URL above with the appropriate values. The other elements such as the base URL, argument names, and symbols should remain as presented above.

17. Paste the newly built URL into a new browser tab and hit enter.

18. Once the OAuth process is complete, a page appears with the following example response:

{"ok":true,"access_token":"xoxp-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXX","scope":"admin,identify","user_id":"WXXXXXXXX","tea m_name":"Org Sandbox","team_id":"TXXXXXXXX","enterprise_id":"EXXXXXXXX"}

19. The access_token value (xoxp-*) in the response is the Org API token. Store this token securely.