Slack notifications with Knock

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:

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.

Slack app management page

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.

🤖
Prepare existing Slackbot

If you already have a Slackbot you want to use, you'll just need to make sure it has its redirect URL set and that it's publicly distributed, which is described below.

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

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:

  1. App ID
  2. Client ID
  3. 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.

A Slack message

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.

A Slack message

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.

workflow with a Slack step

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.


🚨
Potential confusion alert. In the example above, the KNOCK_SLACK_CHANNEL_ID variable is the id of the Knock channel you've created to represent your Slack app within the Knock dashboard. You can find it by going to Integrations > Channels in the Knock dashboard and then copying the ID of your Slack app channel.

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

PropertyTypeDescription
connectionsSlackConnection[]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.

Setting 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.

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.

🌠
Knock fun fact. Slack uses a markdown-variant syntax called mrkdwn, but Knock handles this for you automatically, so you can write your templates in good old markdown .

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.

🛣
Knock roadmap alert. In the future you'll be able to use a visual, drag-and-drop editor within Knock to build these block-based Slack templates without having to leave the Knock product.

If you're interested in trying this functionality, please shoot us a note at support@knock.app or use the feedback button at the top of this page.

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