Setup

Step 1: Create a Slack team integration with Recall

Use this guide to create and setup a Slack team integration with Recall if you do not have an active integration already setup.

Step 2: Create your Slack application

1. Navigate to https://api.slack.com/apps?new_app=1 and select “From scratch”
2. Enter your Slack application’s name. This should reflect your brand as it will be visible to all end-users.
3. Select a workspace to develop it in. This will just be for testing–you’ll be able to add it to all your end-users’ workspaces.
4. Click “Create App”

Step 3: Update Slack application permissions

1. Navigate to “OAuth & Permissions”
2. In “Redirect URLs”, add your product’s redirect URL to process the Slack authorization grant
3. Click "Save URLs"
4. Under “User Token Scopes” in “Scopes”, click “Add an OAuth Scope” and add the following: channels:read, groups:read, im:read, mpim:read, team:read and users:read

🚧

You may need to go through Slack app review

If your Slack application is already listed on the Slack Marketplace, changes to your scopes requires going through app review. This process can take up to 8 weeks and requires constant feedback. We cannot guarantee that your app will pass the app review due to stringent demonstration requirements and potential non-compliance with Slack's regulations, even if justifications are provided. If your app already uses some or all of the mentioned scopes, you won't need to provide additional justifications or make changes to your app if they are satisfactory.

If your app already requests the above scopes, then you’re all set–you can benefit from the full functionality of our integration. Otherwise, you can still benefit from our integration if you have at least one of these permissions. E.g. channels:read still allows the integration to detect huddles in private channels.

📘

Note about changing scopes in distributed Slack applications

Modifying Slack application scopes requires your end-users to re-authorize your application to grant updated permissions. This process may not be simple for all use cases, so we encourage you to think about what is most appropriate for your product's user base. You may choose to only work with private channels for existing end-users, but grant extended functionality to private group and direct message channels for new users who authorize your Slack application.

Step 4: Onboard Users

1. In your Slack application's dashboard, navigate to "Manage Distribution"
2. Under "Share Your App with Other Workspaces", expand all collapsible sections and follow the steps to prepare your application for public unlisted distribution
3. Click "Activate Public Distribution"
4. Navigate to "Basic Information" and take note of the following values: Client ID and Client Secret
5. Navigate to "OAuth & Permissions" and take note of all the scopes listed
6. Programmatically generate your OAuth URL to allow users to authorize your application into their workspace, separating your scopes with a : character and properly URL escaping them

   https://slack.com/oauth/v2/authorize?scope={{YOUR APPLICATION BOT SCOPES}}&user_scope={{YOUR APPLICATION USER SCOPES}}&redirect_uri={{YOUR REDIRECT URI}}&client_id={{YOUR CLIENT ID}}&state={{CRYPTOGRAPHICALLY SECURE RANDOM IDENTIFIER}}
   

7. Give this URL to your end-users, such as through a button in your product

❗️

Ensure state is unique and securely verifiable

As is with all OAuth integrations, the state query parameter must be unique and securely verifiable by your product. Common approaches include using CSPRNG-generated values or JSON Web Tokens. Upon redirect to your product after the end-user authorizes your Slack application, you must be able to verify the authenticity of the state value and ensure it cannot be replayed. Failing to do so opens your product up to security vulnerabilities.

Step 5: Forward user credentials to Recall

1. On redirect to your app, get the authorization code and call our user OAuth token API

def slack_oauth_redirect_page(request):
  query_params = request.query
  state = query_params["state"]
  if not verify_state_securely(state):
		return StatusCode(401)
  authorization_code = query_params["code"]
  oauth_data = {
    "code": code,
    "client_id": "{{YOUR CLIENT ID}}",
    "client_secret": "{{YOUR CLIENT SECRET}}",
  }
  response = requests.post(
       "https://slack.com/api/oauth.v2.access", data=oauth_data
  )
  response_data = response.json()
	if not response_data.get("ok"):
    return StatusCode(400)
  access_token = authed_user.get("access_token")
	send_code_to_recall_oauth_token_api(access_token)

After adding your user’s OAuth token, we’ll automatically start detecting applicable channels and monitoring for new private huddles in them periodically (may take up to several minutes).

📘

Authorizing your app to detect private huddles is inherently a crowdsourced initiative. Even if not all users in a workspace authorize your app, all private channels that your authorized users are in will be monitored. In other words, the more adoption your app gains throughout a Slack workspace, the better the integration becomes–but it’s not strictly necessary that all users adopt it. A handful of users can be enough to get majority coverage.