Docs

Chat

Slack

Overview

Slack notifications with Knock

Learn how to use Knock to send Slack notifications to your users.

In this guide you'll learn how to use Knock to send notifications to Slack. Depending on your use case, there are a few different ways to approach this integration. This guide serves as a starting point and will cover the basics of setting up a Slack integration with Knock regardless of your use case.

Here's what we'll cover in this guide.

Building a Slack app for your integration
How to store Slack connection data in Knock using channel data
How to compose templates for Slack notifications using markdown and block kit UI

How to connect Slack to Knock

Knock supports multiples ways to create a Slack integration depending on your technical requirements:

Using Knock's managed approach with our SlackKit components
Using Knock's Slack-related React hooks with your own components
Building the UI and OAuth flow entirely yourself

Regardless of your approach, you'll need a Slack app to send notifications from Knock to a Slack workspace. If you haven’t built a Slack app yet, you can get started in Slack’s app documentation.

Once you create your Slack app, you’ll be routed to its app management page within the Slack dashboard. It looks like this.

If you are new to Slack apps, there are a few key concepts to understand:

A scope is a permission granted to your Slack app when it joins a Slack workspace. You configure which scopes your app asks for in the OAuth & Permissions sidebar of your app management page.
Your Slack app is installed to a customer's workspace through the Slack OAuth flow. In this flow, your app requests scopes and the user installing the app confirms which scopes to grant. You’ll need to surface this OAuth flow to your users wherever you want them to install your Slack app. Knock's SlackAuthButton component can help you with this.
A Slack app can have bot token scopes and user token scopes. For almost all use cases, you’ll be using bot token scopes (this Slack doc explains why). When you add bot token scopes to an app, you will also need to make sure your app has its display information configured. You can do this under the App Home sidebar on the app management page.

In this section we'll complete the steps for setting up your Knock account and Slack app.

1

Set up Slack app

First, you'll need to create the bot that you'll use to post notifications.

The following steps will be completed in the OAuth & Permissions sidebar of your Slack app's management page:

When using an access_token stored in Knock to power your Slack integration, that token will need to contain the correct scopes to use the Slack API. Although If you're using SlackKit, the components can help you manage your scopes, but you have to add one in your Slack application's settings to start with so that it exposes the form for you to add a redirect URL.

Here is the list of scopes we recommend adding to your app and the reasons they're required:

chat:write: This scope allows your bot to send messages to channels that the bot has been explicitly invited to, including private channels. It doesn't grant the ability to send messages to public channels without an invite.
chat:write.public: This scope extends the bot's capabilities to send messages to public channels without needing a specific invitation to those channels. It's an addition to the chat:write scope, offering broader access for the bot to interact within the workspace.
channels:read: This scope allows your bot to list all channels in a workspace and view details about specific channels (like name, topic, purpose, members), but does not grant access to private channels.
groups:read: This scope allows your app to list all private channels that the bot or user is a member of and to view details about those channels.
users:read: This scope allows your app to view all people in a workspace and is required if you want to query a user's Slack ID by email. This scope is required to use Knock's email-based user ID resolution.
users:read.email: This scope allows your app to view the email addresses of people in a workspace and is required if you want to query a user's Slack ID by email. This scope is required to use Knock's email-based user ID resolution.

Under OAuth & Permissions in the Features sidebar, you need to add a redirect URL so that Slack knows where to redirect users after they complete the OAuth handshake.

If you plan on using SlackKit, copy and paste this redirect URL:

If you are building your own OAuth flow, you'll need to use a URL in your frontend application. You can reference this guide on building a Slack OAuth flow from scratch.

Under Manage Distribution, click the "Distribute app" button which will show you a list of items to complete to activate public distribution. If you've built the app from scratch and completed the previous steps, you should see all of these complete except for "Remove hard coded information."

Check the box and then click "Activate Public Distribution."

2

Add Slack app to Knock Slack integration

Now that your Slack app is set up, you'll want to reference three attributes in the Basic Information section:

App ID
Client ID
Client secret

You need to add this data to a new or existing Slack integration in the Knock dashboard to link your app to Knock. From the dashboard, you can create a Slack integration in the Integrations tab.

Once the channel exists, you can click "Manage configuration" to access the "Provider settings" section. This is where you'll paste the three strings referenced above.

Click "Update settings" to save.

3

Use Slack channel in a workflow

In order to test this flow, you'll want to set up a workflow with a Slack channel step. Later on we'll discuss how you can design your notification templates for Slack, but for now you can just add the channel step to a workflow. To actually send a notification to Slack, you'll need to add channel data to a user or object in Knock. We'll cover that in the next section.

How to set channel data for a Slack integration in Knock

In Knock, the ChannelData concept provides you a way of storing recipient-specific connection data for a given integration. If you reference the channel data requirements for Slack, you'll see that there are two different schemas for a SlackConnection stored on a User or an Object in Knock.

Here's an example of setting channel data on an Object in Knock.

Recipient channel data requirements

Here's an overview of the data requirements for setting recipient channel data for either an incoming webhook or an access token Slack connection. Both will need to live under the connections key.

Property	Type	Description
connections	`SlackConnection[]`	One or more connections to Slack

A SlackConnection can have one of two schemas, depending on whether you're using standard Slack OAuth scopes or an incoming webhook. We cover Slack app scopes in detail in our Slack scopes guide.

If you're using standard Slack OAuth with access token scopes, your SlackConnection schema looks like this. You'll use either a channel_id or user_id depending on whether you're storing connection data to message a channel or user in Slack:

Property	Type	Description
access_token	`string`	A bot access token
channel_id	`string`	A Slack channel ID
user_id	`string`	A Slack user ID

If you're using a Slack app with the incoming-webhook scope your SlackConnection schema is quite simple:

Property	Type	Description
incoming_webhook.url	`string`	The Slack incoming webhook URL (to be used instead of the properties above)

Tenant channel data requirements

When you map a Slack workspace to a tenant in Knock (as our SlackKit components do), you'll store the access token for that workspace as channel_data on the tenant. Then, when you apply the tenant to your workflow triggers Knock will combine that access token with the recipient's channel_data to send notifications to the correct Slack workspace and channel. For this implementation method, the access_token on the recipient's SlackConnection[] data above is not required.

Here's an overview of the data requirements for setting channel data when storing an access token on a tenant.

Property	Type	Description
token	`object`	An object containing the `access_token` obtained from Slack
token.access_token	`string`	The `access_token` obtained from Slack

Choosing where to store channel data: users vs. objects

Depending on the Slack integration you build into your product, you’ll store the connection data you receive from Slack as channel_data on either a User or an Object in Knock.

If your integration involves a user opting in to receive DMs from your Slack bot, you’ll be storing the channel data on that user in Knock. When you want to notify this user, you'll include them as a recipient in a Knock workflow trigger.

For this integration, you'll store a user's Slack user_id in the SlackConnection object. You can enable email-based user ID resolution if you'd like Knock to automatically resolve these IDs on your behalf.

Alternatively, you can manually find the correct user_id by querying Slack's API:

You'll need to be sure that you request the appropriate scopes for these methods during the auth process.

If your integration involves a customer connecting a non-user resource in their product (such as a project or a page) to a Slack channel, you’ll want to store that channel data on an object in Knock, as it’s not specific to any single user.

You can find the correct channel_id and display a list of channels for your user to select from by querying the Slack API:

for a list of all of a workspace's channels

The SlackChannelCombobox component of Knock's SlackKit can help you with this.

You can learn more about the Knock object model and see an example how to use it to power Slack notifications in our Objects concept guide.

Designing notification templates for Slack

When you add a new Slack channel step to a workflow in Knock, you'll need to configure a template for that step so Knock knows how to format the message to Slack.

Markdown templates

Editing a markdown template for Slack is just like editing any other markdown-based template in Knock. You can use Liquid to inject variables and add control tags (e.g. if-then, for-loop) into your template.

Here's an example Slack template written in Knock using markdown.

In the example above we're using Liquid's for-loop tag to iterate over the activities array produced by a Knock batch function. You can learn more about Knock batch functions and the state they produce in our batch function guide.

Block-based templates

For more advanced layouts in your Slack messages, including images and buttons, you'll need to use Slack's block kit UI framework to build your notification templates. The block kit framework is a set of different JSON objects you can use together and arrange to create Slack app and notification layouts.

Designing block kit templates

To start you'll want to design your block-based Slack message template. The best way to do this today is to use Slack's block kit builder. It gives you a drag-and-drop interface for building out your Slack templates, and outputs the JSON you'll need to bring into your Knock template.

Once you've designed your Slack template, copy the JSON from the block kit builder and bring it into your Knock notification template. You'll use the "Switch to JSON editor" button at the bottom right of the Knock template editor page to switch to our JSON editor, and then paste in the JSON you copied from the block kit builder.

Knock's JSON template editor

You can use liquid in the Knock JSON template editor just as you would in the markdown editor. This is helpful for both injecting variables into the text of your Slack UI blocks, as well as for for using liquid control tags to control when certain blocks should be displayed and for iterating through an array and mapping its items into a list of Slack blocks.

Here's an example of a block kit UI template with liquid syntax added to iterate through a list of items.

In the template above, we're using the activities array produced by a batch function to iterate over a number of items that we want to display in our Slack message. For each one of those items, we're producing a section that includes both text and image blocks which reference variables from the activity from our activities array.

Here's an example of a Slack message produced with this template. Note: this template was produced by three separate workflow trigger calls to the Knock API, all of which were batched into a single message automatically using our batch function.

An example Slack message built with block kit UI