Slack integration setup

Follow the series of instructions on this page to set up the Slack integration with your intranet.

For administrator information about the Slack integration and how to use it once it is set up, see Slack integration.

Create app on the Slack site

1. Go to api.slack.com/apps. Click Create New App to create the app.
2. In the Create an app window that appears, select From scratch, enter an App Name. This name will be visible throughout the Slack integration, eg. activity messages are posted by the App Name rather than a person's name. We recommend using or incorporating your intranet name in the App Name.
3. Select your company Slack Workspace from the dropdown menu. (You will need to log in to the Slack website to see it listed as an option).
4. Click Create App. You will be redirected to the Settings: Basic information screen.

Copy credentials to the intranet

1. On your intranet, go to the Admin panel: Integrations section > Slack page. Change the Enable toggle to ON. (Slack integration can be enabled at any time, but must be enabled in order to set up Event Subscriptions/Link previews later in this process.)
2. In Settings: Basic information on the Slack website, scroll down to App credentials.
3. Copy the following values and paste them into the corresponding fields on your intranet on the Admin panel: Integrations section > Slack page, in the App configuration tab.
   • App ID
   • Client ID
   • Client secret (click Show to be able to copy the value)
   • Signing secret (click Show to be able to copy the value)
4. Click Save at the bottom of the Slack integration screen on your intranet. You should see a notification at the top of the screen that the App configuration saved successfully.

Add display information (optional)

These settings are optional and can be set up at any time.

1. In Settings: Basic information, scroll down to Display information.
   1. In the Short description field, enter a description of what the app does. eg. [App name] pushes helpful content from [intranet name] to Slack. Search for and share [intranet name] content right from Slack.
   2. Under App icon & Preview, click Add App Icon to upload an icon for your app in Slack. This icon displays beside the App Name whenever an activity message is posted or a link is unfurled in Slack. We recommend using your intranet logo or favicon here.
   3. Click in the Background color field and select a color. This color appears in the header of the window that pops up when the app name is clicked on in Slack.

Add scopes

1. Navigate to Features: OAuth & Permissions.
2. Scroll down to Scopes. Here you will specify exactly how the app needs to access a Slack user's account.
   1. Under Bot Token Scopes, click Add an OAuth Scope. In the field that appears, start typing the scope you want to add, and click on it in the dropdown menu when it appears to add it. Repeat to add more scopes. Add the following scopes:
      1. links:read
      2. links:write
      3. team:read
      4. commands
      5. chat:write
      6. channels:read
   2. Under User Token Scopes, click Add an OAuth Scope. You will need to add the following scopes:
      1. links:read
      2. links:write
      3. team:read
      4. identify. 

Copy token to intranet

1. Scroll to the top of Features: OAuth & Permissions and click Install to Workspace. Click Allow to allow the Slack App to access the Slack workspace.
2. You will be redirected to the Features: OAuth & Permissions screen. Under OAuth Tokens, copy the Bot User OAuth Access Token.
3. Open your ThoughtFarmer Admin Panel and navigate to the Slack integration page. Under the App configuration tab, paste the Bot token.
4. Click Save at the bottom of the Slack integration screen on your intranet. You should see a notification at the top of the screen that the App configuration saved successfully.

Add a Redirect URL

1. Go back to the Slack website under Features: OAuth & Permissions.
2. Under Redirect URLs, click Add New Redirect URL. Enter your site's URL, e.g. https://mysite.thoughtfarmer.com
   • NOTE: Please refrain from adding a forward slash after the ".com" in the redirect URL option to avoid encountering CORS errors.
3. Click Add.
4. Click Save URLs.

Configure event subscriptions to enable link previews (optional)

Setting up event subscriptions allows users to post intranet URLs in Slack and have them expand, or unfurl, to show the page title, thumbnail image (if available) and a summary or excerpt of the page content.

1. Navigate to Event Subscriptions to enable Link previews.
2. Turn the Enable Events toggle to On.
   1. In the Request URL field, enter your intranet URL and add /slack/action to the end. eg. https://mysite.thoughtfarmer.com/slack/action
3. Click on the App unfurl domains section to expand it.
   1. Click Add Domain and enter your site's domain in the field that appears. eg. https://mysite.thoughtfarmer.com 
   2. Click Done.
   3. Click Save Changes at the bottom of the screen.
4. A message may appear at the top of the screen to reinstall your app for these changes to take effect. We'll do that step later in the process.

Configure slash command to enable intranet search (optional)

Setting up a slash command allows users to search the intranet and post a search result directly in Slack.

1. Navigate to Features: Slash Commands to enable Search.
2. Click Create New Command. You will be taken to the Create New Command screen.
   1. In the Command field, enter a /command that users will type to perform a search of your intranet from Slack. eg. /searchintranet.
      • On your intranet at Admin panel: Integrations section > Slack page, under the Link previews and search tab, there is a field called Search: slash command. This field is available as a place to record your search slash command. Copy your slash command into this field for later reference. Note that this field is not connected to the Slack app, and any changes to the command must be made in Slack and updated manually on the intranet.
   2. In the Request URL field, enter the request URL. eg. https://mysite.thoughtfarmer.com/slack/search
   3. In the Short Description field, enter a description of what the slash command does. eg. Searches [your intranet name]
   4. Click Save at the bottom of the screen.

Configure interactive components

1. Navigate to Features: Interactivity & Shortcuts.
   1. Turn the Interactivity toggle to On.
   2. In the Request URL field, enter your intranet URL and add /slack/interaction to the end, eg. https://mysite.thoughtfarmer.com/slack/interaction
2. Click Save Changes at the bottom.

Reinstall the App

1. Navigate to Features: OAuth & Permissions.
2. Under Tokens for Your Workspace, click Reinstall App.
3. Click Allow to allow the Slack App to access the Slack workspace.

For administrator information about the Slack integration and how to use it once it is set up, see Slack integration.