Slack Integration Setup

Administration: Slack Integration

Overview

During a Hackathon, it is important to have an easy and efficient way to stay in contact with the participants. A reliable and easy-to-use tool is Microsoft's Slack, which offers real-time chat, notifications, and channels for hackers at the event to post in.

Dashboard takes this one step further by seamlessly integrating with Slack to manage Mentorship Requests, Hardware Checkouts, and more. We strongly encourage all events to take advantage of this feature, and will go over the steps to initially set up Dashboard's integration with Slack.

Creating the Slack Bot

First, you must create a public Slack workspace for your desired hackathon. If you already have a Slack workspace for the event, you can use that.

Process

• Go to the Workspace settings page and click 'configure apps'.

• Click the sidebar 'Menu' tab that is located on the page. In that sidebar under the account subheader, click the option Configure apps.

• On this new page, select the Build button in the top right of the header

• Click the button Start Building

• Click the button Create an App

• On the form, fill out the following fields:
  • Set app name to anything (such as HackathonBot for example)
  • Select the Slack workspace for your event.

• You will now be at the Slack settings page for this application...

• Go to 'Settings' > 'Install App'. You'll see a grayed out 'Install App to Workspace' button, scroll down.

• Add the following scopes:
  • chat:write:bot
  • channels:history
  • groups:history
  • groups:read
  • users:read
  • users:read.email

• Scroll up on the same page and hit the now-enabled 'Install App to Workspace.'

• Click Allow on the permission request for your Slack workspace.

• Navigate back to your Slack app's admin interface.
  • Navigate to Bot Users
  • Create a new bot user. The username and display name will be visible to all people in your Slack so choose a nice name that is easy to remember!
  • For versions 2023 and above, there aren’t bot users anymore in Slack, so you should be able to skip this step.

• Reinstall the app to your workspace.

• Log into heroku with the appropriate credentials (you may have to ask someone from last year for this). Click on the appropriate dashboard for your hackathon pipeline view.

• Select your hackathon’s production view.

• In the app dashboard, go to Settings and click “Reveal Config Vars”. Over here, you can proceed accordingly and replace the config vars with the created Tokens. For example, under OAuth and Permissions, set the "Bot User OAuth Access Token" as the "SLACKINTEGRATION_BOT_ACCESS_TOKEN" environment variable for Dashboard.

NOTE: This will begin with xoxb-.

• Under Basic Information -> App Credentials, set the "Verification Token" as the "SLACKINTEGRATION_TOKEN" environment variable for Dashboard.

---

• Now go back to the regular Slack admin interface for your workspace, not the app you created. There, hit the Invitations tab.

• Hit Invite People -> Share Invite Link.

• Uncheck "send me a slackbot message" and, if a link currently exists with an expiration duration that is too short, deactivate it.

NOTE: If you used this join link anywhere else, it will no longer be valid! It is, however, important to ensure that your invite link doesn't expire before the day of the hackathon.

• Hit "Get an Invite Link to Share", and select "Never Expires".

• Save the generated invite link as the "SLACK_JOIN_URL" Dashboard environment variable.

---

• If you're using Heroku with Dashboard, the Heroku environment variables should now be set like the following:

• Update your app with the new configuration variables ("Restart all dynos" in Heroku).

---

Go to the "Event Subscriptions" tab of your Slack application (api.slack.com -> Your Apps -> choose the application name).

Enable events, and enter the URL "https://[YOUR DASHBOARD URL]/slackintegration/index". The verification should succeed; if it does not, check your server logs and Slack's error message.

Under "Subscribe to Events on Behalf of Users", add the "team_join" event and hit Save. This team_join event will be what causes Slack to notify Dashboard that a user joined your workspace, and it is how Dashboard associates a Dashboard user with a Slack user (aka the slack_id field on user).

---

You should now test your integration. Because of the reliance on the "team_join" event to link a Dashboard user and a Slack user, you need to join the slack from a Dashboard user who isn't already in the slack. For example:

Create a new Dashboard user. You don't have to apply to the event, you just need that user's email address in the system. Then, while logged in to that account, go to https://[YOUR DASHBOARD URL]/join_slack

Once you've finished creating your Slack account, you should see a message from your bot. If this message was sent, then the Dashboard-Slack integration has been completed successfully!

Reassociating Users

The way the Slack integration as described above works is that Slack sends a HTTP message to Dashboard with a user's details whenever they join the workspace. Dashboard then takes the user's email and associates the Slack user ID with it in the users table. However, for currently unknown reasons, this transiently fails.

In order to resolve this, a user can press the "I already joined" button when in Dashboard prompted to join the Slack workspace before they are able to access portions of the app.

As an administrator, you can go to the "Admin > Slack Integration" section and force a reassociation of all Slack workspace users with Dashboard users. This should resolve any issues with users' Slack accounts and Dashboard accounts not being linked with each other, as long as all of your participants use the same email for their Slack account as they did on Dashboard (they are prompted to do so when joining the Slack).