Slack

This is a step-by-step guide to integrate and send notifications to users on Slack.

Prerequisites

For sending notifications through Slack, you'll need to create a Slack App. This App will basically be responsible for sending notifications to users / channels in their Slack workspace. To create Slack App, you'll need a Slack account and a Slack workspace where you'll be configuring the App. You will also need permission to create a Slack app. If you do not have access already, you can create your own free Slack workspace.

• Create a Slack Account
• Create a Slack Workspace
• Create a Slack App - Refer section for creating a slack app
  
  

Overview

In this documentation, we'll create an app to send direct messages to users or channels in a slack workspace. Here's an overview of the steps required to integrate and send messages to a slack workspace:

1. Enable Slack Channel on SuprSend Platform
2. Create Slack App - You'll use this app to send direct messages to a user or channel
3. Building OAuth flow to get the user permission and access token to send them notifications. This information will be stored as user's slack channel information. Unlike email where if you know user's email id, you can send email to that user. In case of Slack, your users have to authenticate and allow your app to send them notifications on Slack.

By following the above steps, your Slack integration will be setup. The next steps will be to

4. Update slack channel information in user or channel profile to send message
5. Create a Slack template and trigger workflow

Step 1. Enable Slack Channel

Go to SuprSend dashboard -> Slack Vendor Settings page. Enable Slack channel

Step 2. Create a Slack App

You’ll need to create a Slack app and assign required OAuth Scopes to that App to send notifications via SuprSend. If you have an existing Slack app, you can directly go to OAuth Scopes.

Here's how you can create a basic app in Slack.

Step 1. Sign in to Slack. Navigate to Apps page and click on "Create New App" button

Step 2. Select Create an App "From scratch"

Step 3. Give your App a suitable name and select the workspace you will be using to develop this app. For your test app, you can use something like "SuprSend Test App" for app name

Step 3. Assigning OAuth Scopes to App

OAuth is a protocol that lets your app request authorization to private details in a user's Slack account without getting their password. It's also the vehicle by which Slack apps are installed on a team. You can authorize your app using one of the below methods:

1. Give scoped access using OAuth V2 method
2. Give access to a particular channel / user using incoming webhook

1. OAuth V2 method

Whenever a user joins a slack workspace or adds your slack app in their existing workspace, your app asks for specific permission scopes and is rewarded with access upon a user's approval.

This is how a typical OAuth flow works:

1. You give a button somewhere on your product to add slack channel. The easiest way to enable workspaces to install your app is with the Add to Slack button. Another way is to give the option to Sign in with Slack in your onboarding flow (which is not very common)
2. This will redirect the user to an authorization link https://slack.com/oauth/authorize. Refer OAuth V2 documentation to add slack authorization flow in your product.
3. The user will be asked to give permissions to access their profile information based on the scopes that you define in the OAuth & Permissions sidebar of your app management page.

We'll need access to following scopes to be able to send direct message to user's Slack workspace.

Navigate to "Features" -> "OAuth & Permissions" page from the left sidebar menu. Scroll down to the Scopes section and add the above scopes as Bot Token Scopes.

2. Incoming webhook

Another way to send slack message is using incoming webhooks. Incoming webhook is a quick and easy way to send message to a particular channel. During the OAuth flow that uses incoming_webhook scope, your user can connect to a particular channel (public, private, or even the direct message channel for that individual user) they have access to in their Slack workspace.

We recommend using OAuth V2 method for authentication, since incoming webhook requires your users to explicitly give permission to every channel that you want to send message to and restricts your access to limited channels in users' workspace.

It is best suited for use cases where you want to just update users on a particular channel such as

• Sending announcements and product updates in #announcement channel
• Setting up an internal channel to send a message in case of anomaly detection in a product.

Navigate to "Features" -> "Incoming webhooks" page from the left sidebar menu to activate incoming webhook. Once enabled, you can use this scope in your OAuth flow to get user access to send messages on a particular channel

Step 4. Update slack channel in user profile

The information required in the user profile is dependent on the type of message you are sending.

Sending a direct message

To send a direct message to a user, you’ll need to add the slack user_id or email along with bot access token in user profile. You can pass this information in a json format using user.add_slack method as below:

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

// using slack email
user.add_slack(
  {
    "email": "[email protected]",
    "access_token": "xoxb-xxxxx"
  })

//using slack user_id
user.add_slack(
  {
    "user_id": "U/WXXXXXXXX",
    "access_token": "xoxb-xxxxx"
  })

const response = user.save()
response.then((res) => console.log("response", res));

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

# using slack email
user.add_slack(
  {
    "email": "[email protected]",
    "access_token": "xoxb-xxxxx"
  })

# using slack user_id
user.add_slack(
  {
    "user_id": "U/WXXXXXXXX",
    "access_token": "xoxb-xxxxx"
  })

response = user.save()
print(response)

Sending to a channel

To send a message to a public or private channel, you’ll need to pass its channel_id along with access token. You can get channel_id by opening slack in a browser, select the desired channel and copy the channel_id from the URL

We recommend creating a separate user for identifying channels and not mix it in user profile. You can create a slack channel user with distinct_id as channel_<channel_name> so it's easy for you to remember and pass in your workflow calls whenever you want to send message on a slack channel.

Refer below example to add slack channel shown in above screenshot

const distinct_id = "channel_general"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_slack(
  {
    "channel_id": "CXXXXXXXX",
    "access_token": "xoxb-xxxxx"
  })

const response = user.save()
response.then((res) => console.log("response", res));

distinct_id = "channel_general"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_slack(
  {
    "channel_id": "CXXXXXXXX",
    "access_token": "xoxb-xxxxx"
  })

response = user.save()
print(response)

Sending message using incoming webhook

To send a direct message using incoming webhook, just pass the webhook URL in user profile. You can pass this information in a json format using user.add_slack method as below:

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    }
  })

const response = user.save()
response.then((res) => console.log("response", res));

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    }
    
  })

response = user.save()
print(response)

Order of Precedence

The Slack profile should only contain incoming_webhook->url, or the access_token with one of these keys: channel_id, user_id, or email. If there are multiple keys in user.add_slack() call, the order of precedence is as follows:

incoming_webhook->url > channel_id > user_id > email. For example, if your add_slack argument is as follows:

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

user.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    },
    "email": "[email protected]",
    "user_id": "U/WXXXXXXXX",
    "channel_id": "CXXXXXXXX",
    "access_token": "xoxb-xxxxx",
  })

const response = user.save()
response.then((res) => console.log("response", res));

distinct_id = "__uniq_user_id__"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

user.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    },
    "email": "[email protected]",
    "user_id": "U/WXXXXXXXX",
    "channel_id": "CXXXXXXXX",
    "access_token": "xoxb-xxxxx",
  })

response = user.save()
print(response)

The profile will be saved as {"incoming_webhook": { "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX" } }

Step 5. Create a Slack Template

Refer section to create slack template using JSONNET editor.