Quickstart

Building a basic Slack integration with Paragon.

Introduction

This guide walks you through how to setup a basic Slack integration with Paragon. For demonstrative purposes, let's assume we're building a project management app, and want to provide a Slack integration that:

  • Allows users to connect their Slack account to our app

  • Sends a notification to our users' Slack workspace when a new task is created

This integration should take about 20-30 minutes to build with Paragon. Of course, this is just a basic example of an integration you can build on Paragon, and concepts from this guide can be used for other integrations as well.

Prerequisites

  1. Create your Paragon account

  2. Register a Slack app

1. Connect your Slack app to Paragon

We'll start by connecting our Slack app to Paragon to allow our users to sign into their Slack accounts in our application.

Create a new workflow in Paragon and switch the trigger to OAuth. Connect your registered Slack app to your Paragon OAuth trigger, making sure to add the Redirect URL from Paragon to your Slack app configuration.

2. Add the Sign-in URL to your app

Add the Sign-in URL to your client-side application (e.g. a "Connect Slack" button). When a user clicks on the Sign-in URL, they will be redirected to the Slack login page to connect their Slack account.

After a user connects their Slack account, their Slack credentials (e.g. access and bot tokens) will be passed into your Paragon workflow via the OAuth trigger. You can then use their tokens in Paragon to send messages to their Slack workspace.

To simulate this interaction, you can click Test Step in your OAuth trigger to launch the Slack login page and sign in to a Slack account to receive Slack tokens that we can test with.

3. Send a message to your user's Slack workspace

Now that we have our user's Slack tokens, let's add a Slack step to our Paragon workflow. Under Connect to your Slack account, choose your Slack app. You can then pass your user's Slack token into the App Authentication field by typing {{ and selecting their token from the OAuth trigger step.

Under Choose an action, choose Send message in channel. Under Channel, we recommend entering a channel name that's specific to your app.

Note: Paragon will automatically create the Slack channel if it doesn't already exist.

Under Message, you can enter a welcome message to introduce your users to their new Slack channel. You can also choose the name and icon of your Slack bot.

4. Redirect user back to your app and persist their Slack tokens

After your user signs into their Slack account, we want to redirect them back to your client-side app. To do this, add a Redirect step to your Paragon workflow and enter the URL of your app that users should be redirected to.

To save your user's Slack token for later use, we'll also pass their tokens back to your client-side application in the Redirect step's URL parameters. In your application, you should then associate the tokens with the current user and persist them to your database.

Once you've saved a user's Slack tokens, you can then recall them anywhere in Paragon to send messages to their Slack workspace.

5. Trigger a new workflow when tasks are created

Now that we've allowed users to connect their Slack accounts to our app, we'll setup a second workflow to send them a Slack message when a new task is created in our example app.

To do this, we'll create a new workflow that triggers whenever a new task is created in our app. There are two main ways we can achieve this:

  • Use the Event-based trigger to automatically trigger your workflow when a new task is created in your database

  • Use the API Endpoint trigger, and send a webhook to Paragon whenever a new task is created

6. Fetch user's Slack tokens from your database

Next, we'll fetch the Slack tokens of the user whose task was just created. Add a Database to your second workflow to fetch the user's tokens that we persisted in Step 4, or use a Request step to fetch them from your API.

7. Send notification to user's Slack workspace

Finally, we'll add a Slack step to our second workflow to send a notification about their new task to their Slack workspace.

Connect your Slack app and pass in the user's Slack token that was fetched in the previous step. We can choose the same channel that we created in Step 3, and include information about their new task in the message by typing {{ to pass in data from the new task event received by the workflow's trigger.

8. Deploy your workflows

Now that we've finished setting up our Slack integration, we can Deploy our Paragon workflows to set the integration live.

That's it! You've just built a Slack integration that authenticates your user's Slack accounts and posts messages to their Slack workspaces. You can now monitor your integration's activity in your Task History, which can be found in your Paragon dashboard.