DEV Community: Knock

We analyzed a billion email API requests—here's what we learned

Jeff Everhart — Thu, 12 Mar 2026 18:07:59 +0000

At Knock, we get asked "which email provider should I use?" all the time.

Until now, comparing email provider performance has been harder than it should be. The existing resources are mostly vibes—"Best of" articles, anonymous Reddit threads, or LLM recommendations trained on that same content. Objective performance data is always missing.

We believe evaluating a vendor should look the same as profiling a production system: data collected at scale, aggregated over time, under real-world conditions. So we turned to our own data. Every year, Knock sends billions of API requests to downstream email providers.

With this data, we built email API benchmarks, a real-time dashboard that aggregates performance metrics across 10 major email providers. Here's what we learned.

API response time: speed matters for transactional email

Most email APIs had a median response time of less than 500ms, which is fast enough for most use cases. But the variance between providers tells a more interesting story.

The three fastest providers on average were:

SendGrid at 22ms (p50)
Postmark at 33ms (p50)
Resend at 79ms (p50)

Response time becomes critical for time-sensitive notifications like one-time passwords, fraud alerts, and two-factor authentication codes. At the p99 percentile, the long tail of requests where performance degrades, SendGrid maintained an average of 157ms, outperforming other providers.

We measure response time as the time to receive a 200 from a provider, computed across multiple percentiles (p50, p90, p95, and p99) using exact quantile calculations in ClickHouse. This includes HTTP connection pooling, latency, service time, and any automatic retries, making it a useful indicator of system resilience.

Error rates: reliability under real-world conditions

Most email APIs have an average daily error rate close to 0.00%, which sounds good until you look at peak error rates. During our 90-day observation window, peak daily error rates were grouped between 0.02% and 3.41%, which is a significant spread.

AWS SES stood out here, with the most days showing error rates below 0.01%, covering the entire 90-day window. This consistency matters when you're sending millions of transactional emails and can't afford degraded delivery.

We track error rate as the ratio of 5XX responses to total requests for each provider over the period. Since Knock's retry logic treats most 5XX codes as retriable, a single request can produce multiple error entries if the full backoff sequence runs—meaning our error rates may be higher than what you'd see without retry logic (but your emails get sent 😉).

Provider adoption trends

Looking at both sending volume and channel growth on Knock's platform revealed some interesting trends:

SendGrid dominated by volume, with users sending over 500 million messages through the service in the last 90 days
Resend led in new channel connections, continuing its upward trend in adoption

This split between volume leaders and growth leaders suggests the market is evolving. Established providers maintain massive install bases, while newer developer-focused alternatives are capturing new projects.

We rank providers from one to ten based on new channel connections created during the period, then compare the first and second halves of the window to detect directional trends.

Status page correlation: incident transparency matters

On each provider detail page, we integrate with the provider's public status page via RSS or API and overlay reported incidents on the performance data we collect.

Our view is that observed degradation should correspond with a status page entry. The degree of correlation between measured performance and public incidents is a useful signal for how a provider handles incident management. If you've ever been on-call, this is something that matters when you're debugging production issues at 2am.

Pricing at scale

We've modeled each provider's price curve so you can see how costs scale with volume. The comparison view puts two providers side by side, making it straightforward to weigh pricing alongside performance when evaluating a switch or new integration.

At 5 million emails per month, pricing differences become significant. AWS SES remains the lowest-cost option at scale, while providers like SendGrid, Postmark, and Resend price higher but include additional features and support.

What's next for email API benchmarks

We launched with this subset of metrics because they were the most useful and the easiest for us to obtain. We're already exploring the best way to include deliverability and time-to-inbox metrics.

Knock collects a wide variety of downstream message events, like opens, reads, and link clicks. We'd love to hear from the developer community about what would be valuable to see in a resource like this.

Try it yourself

If you're evaluating email providers today, explore the benchmarks and see how your current provider stacks up.

And if you're looking for a notification platform that gives you the flexibility to use any email provider—or switch between them without changing your code—sign up for Knock for free.

What email provider are you currently using? Have you experienced the performance differences we measured? Drop a comment below with your experiences.

Building a translation CI/CD pipeline with Lingo.dev

Jeff Everhart — Tue, 04 Mar 2025 19:03:15 +0000

A common challenge for applications serving a global user base is providing content and notifications in multiple languages. Manual translation is not only time-consuming but prone to errors and inconsistencies in style and tone of voice.

In this post, I'll walk you through how to build an automated CI/CD translation pipeline using Lingo.dev and Knock that will handle localized notifications for your app without requiring any manual translation work from your team. We’ll introduce some tools that can help you scale your application to a global audience, automate translations locally using Lingo.dev's CLI, and finally integrate that CLI into a CI/CD pipeline so that translations are automatically created when developers open a pull request.

Video walkthrough

If you prefer to learn with video, watch it here.

Tools for scaling your application to a global audience

Lingo.dev is an AI-powered translation service that's relatively new but incredibly powerful. It allows you to specify a particular brand voice for your translations, which we've done for our sample application called Globe Wander, an adventure marketplace.

You can fine-tune translations for your specific context and add custom words to your glossary to ensure consistent translations across your application.

Knock is a notification infrastructure platform with built-in localization support. When you attach a locale to a user object, Knock automatically handles localizing your notification templates when provided with the appropriate translation files. It uses translation tags in message templates to display the right content based on the user's preferred language.

How localization works in Knock

Let's take a closer look at how localization works in Knock. In our Knock dashboard, I've created a "New User Signup" workflow with a Postmark email template that uses translation filters in liquid. If we look at our Postmark email template, you'll see I'm using these translation filters that reference translated string stored in our translation files.

If you preview this template and switch between locales you can see how the message automatically changes to the appropriate language.

When you pull translation files into your codebase with the Knock CLI, they’re organized in a specific folder structure. We have a main "translations" folder with subfolders for each locale like "en-US", "es" for Spanish, and "fr" for French. Inside each locale folder are JSON files containing translation keys and values.

translations/
├── en-US/
│   ├── cancellation.en-US.json
│   ├── en-US.json
│   ├── payments.en-US.json
│   └── shipping.en-US.json
├── es/
│   ├── cancellation.es.json
│   ├── es.json
│   ├── payments.es.json
│   └── shipping.es.json
└── fr/
    ├── cancellation.fr.json
    ├── fr.json
    ├── payments.fr.json
    └── shipping.fr.json

We can also use namespacing to organize our translations by feature or notification type. This makes it easier to manage translations for different parts of your application, such as separating payment notifications from cancellation updates.

Translating files locally

To set up our pipeline, we first need to install and authenticate with Lingo.dev, which you can do by running this auth command in your terminal.

npx lingo.dev@latest auth --login

After installing the package, we run the initialization command which creates an "i18n.json" configuration file.

npx lingo.dev@latest init

In this configuration file, we can specify our source locale as English and define our target locales as Spanish and French. We also configure the file paths for our translation buckets, pointing to our Knock translations directory.

{
  "version": 1.3,
  "locale": {
    "source": "en-US",
    "targets": ["es", "fr"]
  },
  "buckets": {
    "json": {
      "include": [
        "./knock/translations/[locale]/[locale].json",
        "./knock/translations/[locale]/*.[locale].json"
      ]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}

Because Knock requires a specific file naming convention, I've created two include paths to target both the top-level translation file and any namespaced files. This locale placeholder can be used to extract a locale from a file path name that can be used in the newly produced files.

This helps ensure compatibility with Knock's expected structure and gives you flexibility if your translation files are stored differently.

You can test Lingo.dev by running the i18n command.

npx lingo.dev@latest i18n

In the terminal you should be able to see the output. The CLI connects to Lingo.dev, translates all the files, and writes them to the paths specified in the config object. Lingo uses the i18n.lock file to create checksums, so that it only translates files that have changed.

Creating a CI/CD pipeline

For production use, we want this process to run automatically whenever changes are made to our translation files, and ideally we’d push those updated translations back into Knock. I've created two GitHub Action workflows to handle different parts of this.

The first workflow triggers when a pull request is opened to the main branch. It checks out the repository, installs dependencies, runs our translation process on any changed files, and then commits the translated files back to the PR branch. This way, reviewers can see both the original changes and the resulting translations before merging.

name: i18n Knock Automation

on:
  pull_request:
    branches:
      - main

jobs:
  prepare_translations:
    name: Prepare Translation Files
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.ref }}
          fetch-depth: 0 # Ensure full branch history

      - name: Install Dependencies
        run: npm ci # Ensures a clean install using package-lock.json

      - name: Process Translations
        run: npx lingo.dev@latest i18n # Adjust to your relevant command
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}

      - name: Commit and Push Changes
        env:
          BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          git checkout "${BRANCH_NAME}"
          git add .
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: rename translation files"
          git push origin "${BRANCH_NAME}"
        continue-on-error: true

The second workflow runs when a PR is merged to main. It uses the Knock CLI to upload all translation files to your Knock development environment and commit them, making them immediately available for use in testing.

name: Push Translations to Knock

on:
  pull_request:
    types:
      - closed
    branches:
      - main

jobs:
  push_translations:
    if: github.event.pull_request.merged == true
    name: Push Translations to Knock
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Install Knock CLI
        run: npm install -g @knocklabs/cli

      - name: Push Translations to Knock
        run: knock translation push --commit --all --translations-dir=./knock/translations --service-token=$KNOCK_SERVICE_TOKEN
        env:
          KNOCK_SERVICE_TOKEN: ${{ secrets.KNOCK_SERVICE_TOKEN }}

Let's see this in action. I'll add a new translation key for payment reasons to payments.en-US.json with options like "no payment," "insufficient funds," and "invalid method."

{
  "update": "Hey, your payment was successful!",
  "issue": "Sorry, your payment didn't go through. Please contact support.",
  "reasoning": {
    "no_payment": "We couldn't process your payment.",
    "insufficient_funds": "You don't have enough funds in your account.",
    "invalid_payment_method": "The payment method you provided is invalid.",
    "cancelled_by_customer": "You cancelled the order yourself.",
    "cancelled_by_seller": "The seller cancelled the order."
  }
}

After committing these changes to a new branch and opening a PR, we can watch the automated translation process happen. Our GitHub Action starts running, connecting to Lingo.dev to translate our new content into Spanish and French.

Once complete, it commits these files back to our PR branch. Notice how it only updates files that have actually changed, thanks to the checksum system in the i18n.lock file.

Pushing translations back to Knock

After merging the PR, our second workflow automatically uploads the translations to Knock. In the Actions tab of GitHub you can open up the Knock translations workflow and see that output.

Now if we check our Knock dashboard under Translations, we can confirm that our new payment reason translations have been uploaded in all three languages: our original English content, plus the AI-translated Spanish and French versions.

Conclusion

This pipeline provides significant benefits for your development workflow. Developers can focus on adding content in one language, with translations handled automatically through CI/CD. You're able maintain a single template in Knock with dynamic content that changes based on the user's language preference. All changes are version-controlled alongside your code, providing a clear history of translations.

While the setup I've shown is somewhat opinionated, you can adapt it to fit your specific workflow. Lingo.dev also offers their own GitHub Action, and one of the major advantages of using Knock for notifications is that you're not creating separate templates for each language. Instead, you scale through translation files in a much more manageable way than what many other notification providers offer.

I encourage you to check out Lingo.dev for AI-based translations and Knock for notification infrastructure that makes localization straightforward and efficient.

Thanks for reading! Happy coding!

Building a Notion-style activity feed with Next.js and shadcn/ui

Jeff Everhart — Thu, 02 May 2024 14:59:31 +0000

In this post, we'll explore how to build a custom in-app feed using the Knock JavaScript client. This project is modeled visually on the Notion in-app feed, and we'll use Next.js and shadcn/ui to build out the interface. We'll look at how to configure an in-app channel and workflow in Knock, fetch a user's feed from the Feed API, and update message engagement statuses as a user marks things as read and archived. Finally, we'll explore some of the small details that make Notion's feed such a great example.

Video walkthrough

If you prefer to learn with video, watch it here.

Getting started

Before we dive in too deep, let's take a look at what the end product will look like:

We'll end up with a tabbed feed where users can mark things as read, archive them, and switch between different views of the feed. This whole example project can be downloaded from the Knock GitHub account in the notion-feed-example repo. It has two branches:

main: The finished version
start: What we'll be starting with for this project

We'll cover adding the functionality to read from the Feed API and update message engagement statuses.

Cloning the repository

First, clone the repository from the GitHub repo using this command:

git clone https://github.com/knocklabs/notion-feed-example.git

Next, install the dependencies and make a copy of the .env.sample file:

npm install
cp .env.sample .env.local

Then, we can open it up and see what values we need, as there are a few things we'll want to retrieve from the Knock dashboard:

Knock User ID
Knock Feed Channel ID
Public API Key

Let's head into the Knock dashboard to grab those values.

Configuring the Knock client

The first thing we'll grab is our public API key. Under the "Developers > API Keys" heading, we can copy the public key and paste it into our .env.local file.

Next, we'll need our Feed Channel ID. If you go to "Integrations" and find the in-app channel feed that gets created automatically (or another one you've created for your own projects), you can copy that ID and paste it into your environment file as well.

Lastly, we'll need a user ID. Go ahead and copy a user ID and paste it into the .env.local file. If you don't have a user, you can create one from the dashboard under "Users."

Now we should be all set, as long as we've installed the project's dependencies. Let's fire up the development server:

npm run dev

This should start our local server on localhost:3000. If you click the link to open it, you should see a project that looks like this:

Right now, there's nothing in either of the tabs, and the inbox says we don't have any messages. That's what we'll be adding in the next steps.

Seeding messages

Before we go any further, let's hop back into the Knock dashboard and take a look at an in-app workflow.

Creating a workflow

If you don't have one already, you can create one on the 'Workflows' screen of the dashboard. Then you can use the in-app channel that's created automatically when you create an account by dragging it onto the workflow canvas. You'll need to save your changes and commit them to the development branch.

Sending test messages

As you can see, we've got a really basic in-app workflow set up for this project:

If we click into the workflow itself and go to the workflow editor canvas, we can see that we've got a simple message template. Let's go ahead and seed a bunch of messages by clicking "Run a test."

You can pick a user ID, select an actor, and we'll pass in a different message as our message property in our data payload.

Click "Run test" a couple of times to seed that in-app feed with some stuff we can work with.

It's worth noting that this example app doesn't actually go through the sending or triggering of workflows. It's just showing you how to read from an in-app feed. You can explore our docs on triggering workflows to build that into your project.

Now that we have a couple of example messages in this in-app feed for our user, let's hop back into the code editor and figure out how we can read that user's Feed API.

Configuring the Knock client in our app

Open up the ActivityFeed component. We'll configure a new instance of the Knock client. We can see that we're already importing a couple of things from the @knocklabs/client package, which should have been installed as a project dependency.

Right below FeedItemCard, create a new constant variable called knockClient. This will store a new configured instance of the client:

const knockClient = new Knock(
  process.env.NEXT_PUBLIC_KNOCK_PUBLIC_API_KEY as string,
);

Below that, since we've created a new instance of the Knock client, we also need to authenticate it by passing a user ID:

knockClient.authenticate(process.env.NEXT_PUBLIC_KNOCK_USER_ID as string);

Now that we've created a new instance of the client and authenticated, we'll initialize a new feed:

const knockFeed = knockClient.feeds.initialize({
  channelId: process.env.NEXT_PUBLIC_KNOCK_FEED_CHANNEL_ID as string,
  pageSize: 20,
  archived: "include",
});

This ties the feed to the channel ID we got in the first step. The second argument, which is optional, are feed client options. We're including two things:

pageSize: How many items it will grab at one time (set to 20)
archived: Set to 'include' so we get the most recent 20 items of our feed and include archived items as well

In the next step, we'll talk about how we can actually fetch items from that feed and tie those into the user interface.

Fetching feed items

To begin the process of fetching, let's delete the feedItems variable for now. We'll start by declaring some new constant variables using the useState hook:

const [feed, setFeed] = useState<FeedStoreState>({});

We're telling TypeScript that this is a FeedStoreState type, which we're importing from the @knocklabs/client package. We'll initialize it to an empty object.

Below that, we've got this useState hook to set some local state for this component. But we also want to make some network calls using the knockFeed to load the initial state of our feed and listen for updates. We'll use another React hook to do that:

useEffect(() => {
  knockFeed.listenForUpdates();
  const fetchFeed = async () => {
    await knockFeed.fetch();
    const feedState = knockFeed.getState();
    setFeed(feedState);
  };
  fetchFeed();
}, []);

Let's take a recap of what we're doing here:

We used useState to create some local state variables for the ActivityFeed component.
Inside the useEffect hook, we're asking the knockFeed client to listen for real-time updates.
We create a function to fetch the feed initially.
We fetch the feed, get the state that we get back, and set it to our local component state.

There's one additional thing we need to do: add event listeners to the knockFeed so that when we get those real-time updates from listenForUpdates() or make changes to the status of messages, we can reconcile those updates with our local state:

knockFeed.on("items.received.*", () => {
  setFeed(knockFeed.getState());
});
knockFeed.on("items.*", () => {
  setFeed(knockFeed.getState());
});

The Knock feed does a good job of keeping track of its own internal state. When there are changes to that internal state, we're just going to reconcile those with the state in React by calling setFeed and overriding whatever feed was in that local variable.

Now we've got a handle on getting those items from the API. In the next step, we'll make those items available to the interface so we can render some different components.

Rendering feed items

Before we proceed, let's make sure we have event handlers for both 'items.received.realtime' and 'items.*'. This captures a wider array of changes that can happen to the Knock feeds that deal with both message statuses and receiving new messages.

Even as we start updating the message engagement statuses on these items, we'll see that reflected when this event trigger fires, helping us reconcile our state as we make different changes to the feed.

If we reference back to our user interface, we can see that we've got a couple of different options:

Inbox: Things that aren't archived
Archive: Archived items
All: All items

We'll want to separate these things out and create different arrays for these different types of items. We'll use the useMemo hook to compute some of these values for us every time the feed array changes:

const [feedItems, archivedItems] = useMemo(() => {
  const feedItems = feed.items?.filter((item: FeedItem) => !item.archivedAt);
  const archivedItems = feed.items?.filter((item: FeedItem) => item.archivedAt);
  return [feedItems, archivedItems];
}, [feed]);

We create two arrays:

feedItems: Items that haven't been archived yet
archivedItems: Items that have been archived

We return these arrays from useMemo, which will re-compute them whenever feed changes.

Now, let's implement the list of regular feed items (what we would find in the user's inbox). If we scroll down to our tabbed content, we can see that we're going to implement that here:

{
  feedItems?.length > 0 ? (
    feedItems.map((item: FeedItem) => (
      <FeedItemCard key={item.id} item={item} knockFeed={knockFeed} />
    ))
  ) : (
    <div className="p-4 text-gray-500">{/* ... */}</div>
  );
}

We do a conditional check to make sure feedItems has a length greater than 0. If it does, we map through feedItems and return a FeedItemCard for each one, passing in the item and knockFeed as props.

Head back into you interface and double-check that everything's working as expected now. You should see FeedItems displaying in your inbox tab.

Let's do something similar with our archived items tab:

{
  archivedItems?.length > 0 ? (
    archivedItems.map((item: FeedItem) => (
      <FeedItemCard key={item.id} item={item} knockFeed={knockFeed} />
    ))
  ) : (
    <div className="p-4 text-gray-500">{/* ... */}</div>
  );
}

If you go back to the interface, you should see any archived items there. If you archive an item, it should update and move to the "Archived" tab.

It's worth noting that message engagement statuses in Knock are mutually inclusive, meaning they can be in multiple different states at the same time. For example, an item can be both unread and archived. This gives you a lot of flexibility as the developer in how you want to model these engagement statuses in your own application.

The FeedItemCard component

The FeedItemCard component is doing a lot of the heavy lifting in this example app. Let's explore that component next.

We can see the props it takes: item (the feed item) and knockFeed. Inside the component, we do a number of things:

Extract the different blocks attached to the feed item (like the body, which is the message template we created as part of our workflow).
Loop through the item's actors (the people generating the notification by triggering the workflow in Knock) and create the heading.
Render the date using the toLocaleDateString function and the item.insertedAt property.
Handle message engagement statuses.

For the message engagement statuses, we conditionally render different buttons based on whether the item has been read or not:

{
  !item.readAt ? (
    <button onClick={/* ... */}>Mark as Read</button>
  ) : (
    <button onClick={/* ... */}>Mark as Unread</button>
  );
}

We pass the knockFeed client into the component so we can attach each of those onClick handlers to a particular method on knockFeed, like markAsArchived, markAsUnarchived, markAsRead, markAsUnread, etc.

When we call these methods, the Knock feed updates for us locally inside our ActivityFeed component because of the event listener we set up in our useEffect hook. We told knockFeed to listen to any of those lower-level item changes and then reset our feed state.

Additional functionality

There are a couple of other pieces of functionality we want to build into this, like the "Mark all as Read" and "Archive All" buttons in our inbox experience.

To do that, we'll create two functions in our ActivityFeed component:

const markAllAsRead = () => {
  knockFeed.markAllAsRead();
  setFeed(knockFeed.getState());
};
const markAllAsArchived = () => {
  knockFeed.markAllAsArchived();
  setFeed(knockFeed.getState());
};

These functions:

Use special bulk methods on the knockFeed to make status updates to all FeedItems in the current scope
Manually set our feed state using knockFeed.getState()

Then, we can add onClick handlers to our buttons that call these functions:

<button onClick={markAllAsRead}>Mark all as Read</button><button onClick={markAllAsArchived}>Archive All</button>

If you go back to the interface, these buttons should work as expected, allowing you to quickly clear out our notification feed.

Polish and finishing touches

There are a couple of things that Notion does that add an extra layer of polish to the in-app feed experience.

The "New" unread icon

If we look at our FeedItemCard component, we can see that we're conditionally rendering a "New" icon based on whether the item has been read or not:

{
  !item.read_at && <div className="new-icon" />;
}

This is just a div with some additional styling applied to it. In the example app, we apply these styles with the styles attribute, but this is what a CSS class may look like:

.new-icon {
  height: 8px;
  width: 8px;
  background: rgb(35, 131, 226);
  position: absolute; /* ... */
}

These styles come one-to-one from the Notion UI, with a few tweaks to the left and top properties because the avatar size was a little different using shadcn/ui.

This is just one of those really nice features that calls attention to an unread item in a feed.

Opacity treatment for read items

There's another treatment that Notion applies to feed items that is really classy. If we look at our FeedItemCard component, we can see that we're applying a 70% opacity to the element whenever it's marked as read:

<div className={`${item.read_at ? "opacity-70" : ""}`}>{/* ... */}</div>

When we look at the interface, we can see how this de-emphasizes the things we've already interacted with and makes the unread items stand out much more. We've got this double encoding of the unread status:

The "New" item icon
100% opacity (vs. 70% for read items)

When you compare these things against each other, they both stand out really well. These are really tasteful affordances that Notion builds into their in-app feed experience.

Wrapping up

Awesome! Thanks so much for reading. In this post, we covered how to build a Notion-style in-app feed experience using Knock's Vanilla JavaScript client.

We looked at:

Creating an in-app feed channel and workflow
Fetching items from a user's feed
Managing engagement statuses on feed messages

The feed client gives developers pretty much unlimited flexibility in the types of experiences they can create, so we're excited to see what you'll build.

You can get started with Knock for free by signing up here. Knock on.

Building a GitHub activity feed with Node.js and Socket.io

Jeff Everhart — Fri, 26 Apr 2024 10:11:22 +0000

In a previous article, we discussed the benefits of creating an activity feed for your product. In this post, we’ll cover how to build an activity feed directly into your product using Node.js and Socket.io.

Let’s say we’re building a B2B SaaS app for developers, and it needs to show an activity feed of what is happening in their organization’s GitHub repo. Any commits pushed to the repository should be displayed in the app in real-time. That’s what we'll build in this post. You can find the completed project available on GitHub.

We’ll use a library called Socket.io to implement WebSockets that send events in real-time from our backend Node.js server to our frontend JavaScript client whenever the server gets a message from GitHub that a repo has been updated. We’ll create webhooks to get that information from GitHub and set up our Node.js server to listen for these webhook events.

Creating your server

First, let’s create the Node.js server that listens for GitHub webhook events and updates connected clients in real-time using WebSockets via socket.io. It will also serve a static HTML file for the client-side interface.

To set up this project, create a new directory and initialize a Node.js project:

mkdir github-webhook-feed
cd github-webhook-feed
npm init -y

Install the following packages using npm:

npm install express body-parser socket.io

Create a file called index.js and include the following code for this server:

const express = require("express");
const bodyParser = require("body-parser");
const http = require("http");
const socketIo = require("socket.io");

const app = express();
app.use(bodyParser.json()); // For parsing application/json
const server = http.createServer(app);
const io = socketIo(server);

// Endpoint for GitHub Webhooks
app.post("/webhook", (req, res) => {
  const event = req.body;
  // Check for a push event
  if (event && event.pusher) {
    io.emit("new_commit", event);
  }
  res.status(200).end();
});

// Serve the client HTML file
app.get("/", (req, res) => {
  res.sendFile(__dirname + "/index.html");
});

io.on("connection", (socket) => {
  console.log("A user connected");
});

server.listen(3000, () => {
  console.log("Server listening on port 3000");
});

Let's break down this code step-by-step. First, we have the module imports and initializations.

const express = require("express");
const bodyParser = require("body-parser");
const http = require("http");
const socketIo = require("socket.io");

const app = express();
app.use(bodyParser.json()); // For parsing application/json
const server = http.createServer(app);
const io = socketIo(server);

First, we import express. The Express framework allows us to create routes that will respond to webhook POST requests and serve an HTML file when a GET request is made to the root of the site.

Next, we import body-parser, which is middleware for parsing incoming request bodies before your route handlers run, available under the req.body property.

Then, we have the two imports we need to set up our WebSockets. The http module creates a basic HTTP server, and socket.io, a library for building real-time applications, enables real-time, bidirectional, and event-based communication between web clients and servers.

Using Express with Socket.IO

Once we’ve imported all our modules, we create an instance of Express and assign it to a variable called app, and then call the .use() method with body-parser as an argument, which tells Express to use the middleware to parse the JSON body of incoming requests.

Then, we create an HTTP server and pass the Express app as an argument and initialize a new instance of socket.io by passing that HTTP server object into socketIo. This allows socket.io to work in conjunction with the Express app to handle both regular routes and WebSockets.

Creating server endpoints

Now that we’ve configured a server that can use both Express and Socket.io, let’s add the endpoints we’ll need to accept webhook payloads and serve our user interface.

Receiving webhook POST requests

First, we’ll create our /webhook endpoint using the app.post method:

app.post("/webhook", (req, res) => {
  const event = req.body;
  // Check for a push event
  if (event && event.pusher) {
    io.emit("new_commit", event);
  }
  res.status(200).end();
});

This listens for POST requests to the /webhook path, and when a POST request is received it runs the callback function we provide. Inside the callback function, we check the request's body using the req.body parameter. In this example, req.body will contain event data from GitHub. If the event data includes a pusher object, which indicates a push event, we’ll emit a new_commit event to all connected WebSocket clients using socket.io and pass in the GitHub event data.

Serving static HTML with GET handlers

We’ll also need a front end to connect to our WebSockets, and we do that by serving the client HTML file.

app.get("/", (req, res) => {
  res.sendFile(__dirname + "/index.html");
});

This is a route handler for GET requests to the root URL (/). It serves the index.html file located in the same directory using the res.sendFile method in Express.

Handling WebSocket connections

Next, we’ll add a function to create our socket.io connection handler.

io.on("connection", (socket) => {
  console.log("A user connected");
});

This listens for connection events on the socket.io instance. Every time a new client connects, the callback function is executed, and the message "A user connected" is logged to the console.

Finally, we start the server and listen on port 3000:

server.listen(3000, () => {
  console.log("Server listening on port 3000");
});

Let’s set up our client code next.

Creating your client

Now, let’s move on to the frontend. Create an index.html file in the same directory as your index.js file and add this code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>GitHub Commit Feed</title>
    <script src="/socket.io/socket.io.js"></script>
    <style>
      body {
        font-family: Arial, sans-serif;
        background-color: #f4f4f4;
        padding: 20px;
      }
      .notification {
        background-color: #fff;
        border: 1px solid #ddd;
        padding: 10px 15px;
        margin-bottom: 10px;
        border-radius: 4px;
        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
      }
      .notification-header {
        font-weight: bold;
      }
    </style>
  </head>
  <body>
    <h1>GitHub Commit Feed</h1>

    <script>
      document.addEventListener("DOMContentLoaded", function () {
        const socket = io();

        socket.on("new_commit", function (data) {
          const notificationDiv = document.createElement("div");
          notificationDiv.className = "notification";

          const header = document.createElement("div");
          header.className = "notification-header";
          header.textContent = `New commit in ${data.repository.name}`;

          const content = document.createElement("div");
          content.textContent = `Commit by ${data.pusher.name}: "${data.head_commit.message}"`;

          notificationDiv.appendChild(header);
          notificationDiv.appendChild(content);
          document.body.appendChild(notificationDiv);
        });
      });
    </script>
  </body>
</html>

There are a few critical parts of this HTML file to highlight.

The first is the script tag in the head of our HTML document that loads the Socket.IO client library. This script tag includes the Socket.IO client library that will communicate with our socket.io server from the code above.

We then have a few CSS styles for the document body, and notification, and notification-header classes.

Then, in our document’s body section, we have some JavaScript that we’re using to update our feed. The JS is wrapped inside an event listener on the DOMContentLoaded event, which runs after the DOM is fully loaded. This allows us to make sure the Socket.io client script is loaded before we use it in our code.

We create a new variable called socket and initialize it to a new io() client object. This establishes a WebSocket connection to the server.

From there we create a new event listener on socket that listens for the new_commit event we send from the server when a GitHub webhook is received. When a new commit event is received, the callback function is executed to handle the data.

Inside the callback, we use some vanilla JavaScript to create the HTML structure for our notifications:

- A new `div` element with the class `notification` is created to represent a notification.
- Two more `div` elements are created within this notification `div` to display the repository name (with class `notification-header`) and the commit details.
- These elements are appended to the `notificationDiv`, and then `notificationDiv` is appended to the `body` of the document, making the commit data visible on the page.

The JS code in the <script> tag dynamically updates the web page's content in real-time as new commit data is received from the server via the established WebSocket connection. Each new commit results in a new notification being added to the page with the details of the commit.

Setting up your webhook

To start our server locally, you can run the following command:

node index.js

At the moment, our webhook endpoint is at http://localhost:3000/webhook. But we can’t give this URL to GitHub and expect anything to happen—GitHub can’t access our local server.

The solution is to use a service like ngrok to expose our server to the internet. Download and install ngrok, then, in a different terminal tab, run:

ngrok http 3000

This will expose the server on that port to the internet and give you a public URL you can use that will look something like this:

This URL is what you are going to give to GitHub. Follow the

Go to your GitHub repository.
Navigate to Settings > Webhooks > Add webhook.
In the Payload URL, enter the ngrok URL followed by /webhook.
Choose application/json for content type.
Select Just the push event.
Add the webhook.

Whenever a push is made to the repository, GitHub will send a POST request to your server.

Let’s push some changes to a GitHub repository and see what happens.

Building more sophisticated feeds

So, we have a basic feed, but what’s missing here? If you read the first part of this series on the benefits of creating an activity feed for your product, you know that a lot goes into making a good activity feed.

For a production-level feed, we’d likely need to consider the following things:

This feed should be a separate component with different variants, like a full-page inbox or a popover inside a header. We might also want to style it differently for commits, PRs, merges, etc.
We’d probably want to store the GitHub activity events in a database and pull from that to populate the frontend activity feed. Then, we could include logic to always show the last N events. Right now, refreshing the client loses the feed because we have no persistence for our activity feed.
We'd want some way to manage message status, such as marking a notification as seen or dismissing notifications, as well as some mechanism for the user to personalize their feed experience.
We'd have to manage the infrastructure for this extra server, and in this example we really only have one client user. It would require a lot more server-side logic to handle these updates across thousands of repositories and hundreds of organizations.

Creating a basic activity feed is easy, but creating a usable activity feed that will scale with your product is harder. This is where services such as Knock can help. Knock allows developers to include in-app notifications with pre-built components with no extra infrastructure and no custom code.

If you want to learn more about Knock, our documentation will show you how to build something better than above with less code. You can also join our Slack community to see how others use Knock, or contact us to chat about using Knock in your application.

The benefits of adding an activity feed to your B2B product

Jeff Everhart — Wed, 24 Apr 2024 11:44:55 +0000

Activity feeds give users a real-time stream of updates about new content, actions, and changes in an application that are relevant to them.

They are a great way to increase user engagement by helping them be more successful in your application. In the B2B SaaS space, where workflows are complex, and collaboration is often the primary goal, activity feeds can help provide a cohesive user experience. They serve as a centralized hub of notifications and updates that inform users of critical changes, keeping everyone in sync. Providing a snapshot of recent activities allows team members to quickly catch up on what they've missed, thus reducing the time spent searching for information and increasing productivity.

However, integrating an activity feed into your product has its challenges. It requires a thoughtful approach to design and functionality to ensure that the feed enhances, rather than disrupts, the user experience. An effective activity feed must be finely tuned to deliver personalized and relevant information without overwhelming users. The goal is to create a seamless flow of information that supports the user's day-to-day tasks and boosts their overall success with your application.

In this two-part series, we want to introduce you to the ideas underpinning activity feeds and why you should consider them for your application before showing you how to build an activity feed for your product.

Some B2B SaaS activity feeds for inspiration

Let’s look at a few activity feed examples.

First, we have this from HubSpot. Here, the activity feed shows how customers interact with an email campaign the HubSpot user created.

(Source: HubSpot)

The feed is organized chronologically with entries from "Yesterday" and "This month" as the primary time categories. Each entry in the feed includes:

The name of a person and their job title (such as "Manager, Transportation" or "Shipping Coordinator").
The name of the organization they are associated with.
A brief description of the activity, for example, "was sent email Checking In / Following Up" or "was sent email Reintroducing ALG Worldwide Logistics."
A timestamp of when the activity occurred.

There are also ways for the user to interact with the notification, such as flagging the activity for further action. The design is clean, which is essential for an activity feed as it must clearly present a lot of new, moving information.

This activity feed from Atlassian is a little different. This is the Confluence activity feed on Android.

(Source: Atlassian)

This is an example of an internal activity feed for a team-based product. Here, the activity feed is used for team collaboration and document sharing, with functionalities for commenting and reacting to shared content. You can also follow your co-workers in the Confluence feed, blurring the lines between a social media feed and a SaaS app.

Here’s a more regular activity feed from Drift, used to monitor engagement and follow up with leads or customers:

(Source: Drift)

This activity feed shows website visitors and any interactions with them through Drift. Each entry has information about the site visitor, and the conversation thus far, and can interact further with the visitor, either through the Drift app or through email. You can also find more information about the user through LinkedIn.

Again, the interface is clean and modern and designed to monitor visitor activity and real-time interactions.

The benefits of activity feeds

The core benefit of activity feeds that cuts across all use cases is awareness.

You use an activity feed in your application to inform users of what is happening. Let’s take the HubSpot example above. The activity feed informs users of what is happening with email campaigns–what emails have been sent, to whom, and whether the recipient has interacted with the email. This gives HubSpot users an immediate understanding of how the email campaign performs.

From this benefit to users comes benefits to the product:

User engagement. Activity feeds can enhance user engagement by providing constant, relevant content. They encourage users to interact more frequently with the application, as they can quickly see new updates and respond in real-time. This feature makes the app more dynamic and interactive, leading to longer session times and more frequent visits.
User retention. Activity feeds play a role in retaining users by keeping them informed and engaged. They create a habit loop for users, who return to the app to check for updates and notifications. This regular interaction fosters a deeper connection with the app. The ability to then personalize feeds, showing content based on user behavior and preferences, makes the app more relevant to the user, thereby increasing the likelihood of them staying engaged over time.
User insight. Activity feeds provide valuable data on user behavior, preferences, and engagement patterns. By analyzing interactions with the feed, such as clicks, likes, shares, and the time spent on different types of content, developers and marketers can gain insights into what users find most appealing and engaging. This information can be used to tailor the app's content strategy, improve features, and even direct product development efforts to better meet user needs.

There are also secondary benefits to users from activity feeds beyond simple awareness. In the HubSpot example above, users will be excited to see their campaigns working in real time. This little dopamine hit will make them more engaged with the activities and further engaged with the app. The same goes for Atlassian–Annika will probably be thrilled to get a heart emoji from her boss on her leadership principles doc.

User engagement and retention also come from another avenue–a lack of task-switching. If the user has to check other applications or windows for updates continually, they will lose focus and will likely get lost elsewhere. The Drift feed shows this. Users can check LinkedIn from within the app without heading off to a new tab, open LinkedIn, type in the person’s name, and then find the necessary information. Instead, the activity feed condenses that workflow into a single click.

The key components of an activity feed

What design and product features do each of the example feeds above exhibit?

Relevance

Whatever is presented in the activity feed should be relevant to the user. The idea is to bring them further into the app, not remove them from their work. Relevance comes initially from the information you provide in the activity feed. In the case of the HubSpot example, email usage is relevant to a marketer following a campaign. Three other components can increase relevance:

Personalization. Personalization algorithms can tailor the feed to the user’s behavior, preferences, and past interactions. By analyzing user data and activity, the feed can dynamically present the most pertinent information to each user. For instance, a marketer using HubSpot would see the most recent and relevant campaign data based on the past activities and campaigns they are managing.
User customization. Allowing users to set preferences for what they wish to see in their activity feed empowers them to customize the content to their needs. Features like filtering by topic, project, or team and muting less relevant threads or notifications can help users maintain focus on what's most important to them. In a practical sense, users could customize their feed in HubSpot to monitor specific campaign metrics that they find most indicative of performance.
Contextual information. Including contextual information such as related projects, previous activities, or upcoming deadlines can make each item in the feed more informative. Embedding links to related reports, conversations, or tasks in the feed items can provide a more holistic view and understanding of the activity. For example, a feed item in HubSpot about a recent email campaign could include open rates, how those rates compare to past campaigns, and how they correlate with subsequent conversions or sales.

By combining these components, an activity feed can become a powerful tool for keeping users informed and engaged, ensuring they have a clear, concise, and relevant stream of information at their fingertips.

Timeliness

Activity feeds need to display content that is relevant and timely. Users expect to see the latest updates and actions in their feed. The challenge lies in balancing the need for real-time updates without overwhelming the user. The success of an activity feed in maintaining user engagement often depends on its ability to provide up-to-date information.

Timeliness comes down to two factors. The first is technical. One of the primary technical considerations in building an activity feed is the choice between push and pull mechanisms for updating the feed.

In push systems, updates are sent in real-time from the server to the client, often using technologies like WebSockets. This approach is ideal for applications with crucial immediate content updates, ensuring the feed is constantly refreshed with the latest information.
Pull systems require the client to request updates from the server periodically. Typically implemented through traditional HTTP requests, this approach is more suited to applications where real-time updates are less critical.

The second is user-controlled preferences. An activity feed should allow users to customize how and when they receive updates, giving them control over the timeliness of their feed. Users could receive some updates in real-time, while others could be summarized in a daily digest. For example, a project management tool might offer real-time updates for task completions but provide daily summaries for general project progress.

Interactivity

Features like commenting, liking, and sharing are integral, enabling users to interact with the content and notifications. Within an activity feed based around team activity, this interactivity fosters a sense of teamwork among users, making the feed more than a passive viewing experience.

All three examples above use interactivity, whether just flagging the activity for further review in HubSpot or the full commenting, liking, and sharing of Atlassian, interactivity is a critical component that enhances user engagement and collaboration. This engagement improves the user experience by making it more social and connected and provides valuable data to the platform regarding which features are most used and appreciated.

Challenges and pitfalls of activity feeds

Developing and maintaining activity feeds come with unique challenges and pitfalls that can impact user experience and technical performance.

The first is scaling. Imagine the Drift activity feed if you had 1,000 visitors to your site. Or the Atlassian activity feed with 100 team members. Both would be constantly updating, and it would be impossible to find relevant information. The feed would become overwhelming for the user.

The simplest solution here would be strong user preferences. Allowing users to control what they see and when would remove much of this burden. This requires more backend complexity but a much better user experience.

The second is design. Activity feeds must be designed to allow users to understand information at a glance. This includes a clean layout, intuitive icons, and a clear information hierarchy. Poor design can lead to confusion and a steep learning curve, which may drive users away.

A well-designed feed also needs to account for the cognitive load on the user. Too much visual complexity or dense text can be counterproductive. Simplifying the presentation of information with visual cues such as color coding, avatars, and icons can enhance comprehension.

The third is managing the signal-to-noise ratio. An activity feed must strike the right balance between being informative and not overwhelming. It should filter out the 'noise' or less essential updates and highlight the 'signal' or the most relevant and critical information.

Without careful management, users can quickly become frustrated with unimportant notifications, leading to notification fatigue and potential disengagement from the feed or the product itself.

Building an activity feed

Activity feeds help both the user and the product. For the user, they allow them to work better and more efficiently, giving them the real-time information they need to perform their job. For products, they increase engagement and retention, keeping users coming back for more.

If you are adding an activity feed to your product, try Knock for free by signing up for a free account and get started by checking out our in-app feed docs.

Build a Slack app with SlackKit

Jeff Everhart — Tue, 23 Apr 2024 16:06:04 +0000

If you’re looking for ways to provide value to your app’s users, a Slack integration is worth building . But adding Slack support to an existing app has historically been a large engineering task: you need to map your app’s data model onto Slack’s users and channels, provide a way to authenticate and store credentials, manage notification templates in domain-specific formats like mrkdwn and Block Kit, and then create UI to handle the self-serve aspects of this process.

SlackKit is a library of drop-in components powered by the KnockSlackProvider, and it uses components like the SlackAuthButton and SlackChannelsCombobox. Engineering teams can add support for Slack channel notifications in Knock in hours, not days or weeks.

In this post, we'll take a high-level look at SlackKit in action and walk through an example Next.js application that implements it.

Getting started

For this project, there are quite a few configuration variables you need before you can get started. Some of these are typical environment variables you would supply to your application, like API keys, tokens, or client ids.

The other set of values would typically be determined by your product's business logic, but you can hardcode these values for the time being.

You can access the repository for this project directly or clone it to your local machine using the following command:

git clone https://github.com/knocklabs/slack-kit-example.git

Video walkthrough

If you prefer to learn with video, watch it here.

Setting up a Slack app

You can either follow the setup steps outlined here, or use the official instruction in the SlackKit docs.

Create a new app

First, visit https://api.slack.com/apps and sign into your account. Then, click Create an App and select the From scratch option. Next, select which workspace to develop it in. You'll still be able to use it in other workspaces, so this selection isn't critical.

Add bot features

Under Add features and functionality select Bots features. Then, under OAuth and Permissions, give it the channels:read scope. It doesn’t need any scopes here since we’ll be sending the scopes we need from the component, but we need to do this so we can expose the redirect url form.

Add redirect URL

Under OAuth and Permissions, find the redirect URL section and add this Knock URL to that field: https://api.knock.app/providers/slack/authenticate. Knock's API endpoint will handle the OAuth callback for you and store a Slack access token. Finally, Under Manage distribution, allow it to be publicly distributed.

Setting up Knock

For this tutorial, you'll need a Knock account. If you don't already have one, you can sign up on this page. You can also find these steps outlined in the official SlackKit docs.

Create a Slack channel

Add a Slack channel in Knock with the Client Id and Client Secret from the Basic Info section of your Slack. Take note of this channel id for use in the next step.

Create a new workflow

Create a new workflow with a Slack channel step pointing to this Slack channel. Take note of this workflow key for use in the following steps, and the example project uses a default workflow key of new-issue. In the message template use the following liquid tag to send messages: A new issue was submitted: {{message}}

Environment variables

All of these values are sourced from environment variables at runtime. The example app will check for these values as the first step. Make a copy of .env.sample using the following command: cp .env.sample .env.local

`NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID`

This value comes from Knock after you create a Slack channel in the dashboard.

`NEXT_PUBLIC_SLACK_CLIENT_ID`

This value comes from Slack when you create a new Slack app. You can find it in your app's "Basic Info" section.

`KNOCK_SIGNING_KEY`

This value comes from Knock and is used to sign a JWT on behalf of a user to store channel data for Slack tokens and channel ids. You can generate a signing key under "Developers" > "API keys." This is a secret value and should not be exposed publicly.

`KNOCK_API_KEY`

This value comes from Knock and is used to authenticate server-side API requests. You can find it listed as the secret key under "Developers" > "API keys." This is a secret value and should not be exposed publicly.

`NEXT_PUBLIC_KNOCK_CLIENT_ID`

This value comes from Knock and is used to authenticate public API requests from the browser. You can find it listed as the public key under "Developers" > "API keys."

`NEXT_PUBLIC_KNOCK_API_URL`

This value comes from Knock and is used to construct the URL for API endpoints. You can keep the default value for this.

`NEXT_PUBLIC_REDIRECT_URL`

This value comes from your application. It is where Knock will redirect your user after the OAuth flow with Slack. The default of http://localhost:3000 is valid when running this project locally.

Knock resource variables

To make the connection between Slack channels and Knock objects, you'll also need to provide details for several types of resources in Knock. To do this, you can replace the values in the getAppDetails function inside of the /app/lib/app-details.ts file. These values would typically be determined by your application's business logic, but we can hardcode them for this example:

export function getAppDetails() {
  return {
    tenant: "knock-projects",
    collection: "repositories",
    objectId: "repo-2",
    userId: "123",
    workflowKey: "new-issue",
  };
}

You should already have a value for workflowKey from a previous step, and you can choose a user identifier to use from the dashboard.

Create a tenant

In SlackKit, tenants are used to store the access token for an organization's Slack workspace. You can create a new tenant from the dashboard and include its ID as the value for the tenant property in the getAppDetails function. You can also use this cURL command to create a tenant by replacing the values for tenant-id, KNOCK_API_KEY, and tenant-name:

curl --location --request PUT 'https://api.knock.app/v1/tenants/<tenant-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <KNOCK_API_KEY>' \
--data '{
  "name": "<tenant-name>",
}'

You do NOT have to create your tenant before using SlackKit. If you pass a tenant ID into the KnockSlackProvider that doesn't exist, SlackKit will create it for you on completion of the OAuth process. However, tenants are an important concept in Knock so we'd recommend reading about these key concepts in the SlackKit overview.

Create an object

In SlackKit, objects are used to store channels and act as the recipient of your workflows. You can't create a new object from the dashboard, so you can use this cURL command to create an object by replacing the values for object-collection, object-id, KNOCK_API_KEY, and object-name:

curl --location --request PUT 'https://api.knock.app/v1/objects/<object-collection>/<object-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <KNOCK_API_KEY>' \
--data '{
    "name": "<object-name>"
}'

Once you've done that, update the values in the getAppDetails function to point to your new object.

You do NOT have to create your object before using SlackKit. If you pass an object ID into the SlackChannelsCombobox that doesn't exist, SlackKit will create it for you on the completion when the user registers a channel. However, objects are an important concept in Knock so we'd recommend reading about these key concepts in the SlackKit overview.

Running the app locally

Now that you have all of the configuration out of the way, you can install your dependencies using one of the following commands:

npm install
#or
yarn install

After your dependencies have installed, you can run the app in dev mode:

npm run dev
#or
yarn dev

If you open the app in a browser at http://localhost:3000 you should see a screen that looks like this:

This step gives you an opportunity to confirm that you have all of the necessary environment variables needed to use the application.

If you click Next you'll navigate to a screen where you can confirm the Knock resources you'll use to connect your Slack app:

If all of the values in this step look good, you can click Next to authenticate with your Slack app and store the access_token in Knock.

Sharing Knock and Slack state

Before we dig into the actual SlackKit UI components and their functionality, let's look at how we share certain values across those components in our application.

In the @knocklabs/react package, Knock already exposes a KnockProvider component that is meant to provide top-level authentication and authorization to components farther down in the component tree.

With the SlackKit release, the @knocklabs/react package now also contains a Slack-specific provider, called KnockSlackProvider. Since these both rely on React context, they are implemented as client-side components in /app/components/providers.tsx in the following manner:

"use client";

import { KnockProvider, KnockSlackProvider } from "@knocklabs/react";

export default function Providers({
  userToken,
  knockUserId,
  tenant,
  children,
}: {
  userToken: string;
  knockUserId: string;
  tenant: string;
  children: JSX.Element;
}) {
  return (
    <>
      <KnockProvider
        apiKey={process.env.NEXT_PUBLIC_KNOCK_CLIENT_ID!}
        userId={knockUserId}
        host={process.env.NEXT_PUBLIC_KNOCK_API_URL}
        userToken={userToken}
      >
        {/*
        The KnockProvider handles authentication with Knock, while the KnockSlackProvider
        provides shared context to all Slack-related components.
        Both are required for Slack-related apps.
        */}
        <KnockSlackProvider
          knockSlackChannelId={process.env.NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID!}
          tenant={tenant}
        >
          {children}
        </KnockSlackProvider>
      </KnockProvider>
    </>
  );
}

To create some of the necessary authentication data, like userToken and userId, we implement the Providers component inside of the root layout.tsx file. In this code, which runs on the server, we also add some additional grants to the userToken JWT to allow the user to interact with the Slack resources stored in Knock. You can read more about these resource access grants in the docs.

Note 🚨: this is necessary because the user in this context is an end user in
your application who does not have access to Knock as a member of the
account.
Therefore, these grants provide them elevated privileges to operate on
specific resources using the API.

import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";
import "@knocklabs/react/dist/index.css";

import Providers from "./components/providers";
import "./global.css";
import { getAppDetails } from "./lib/app-details";

const { userId, tenant, collection, objectId } = getAppDetails();

const signingKey = process.env.KNOCK_SIGNING_KEY!;

async function MyApp({ children }: { children: React.ReactElement }) {
  //Generate a production build in CI/CD even if we're missing the env vars
  const userToken = signingKey
    ? await Knock.signUserToken(userId, {
        grants: [
          Knock.buildUserTokenGrant({ type: "tenant", id: tenant }, [
            Grants.SlackChannelsRead,
          ]),
          Knock.buildUserTokenGrant(
            { type: "object", id: objectId, collection: collection },
            [Grants.ChannelDataRead, Grants.ChannelDataWrite]
          ),
        ],
      })
    : "secretOrPrivateKey";

  return (
    <>
      <html>
        <body className="px-12 py-6">
          <h1 className="text-2xl font-bold mb-6">SlackKit Demo App</h1>
          <Providers userToken={userToken} knockUserId={userId} tenant={tenant}>
            {children}
          </Providers>
        </body>
      </html>
    </>
  );
}

export default MyApp;

Authenticating with Slack

On this screen, you can initiate the OAuth flow with Slack. This page uses two SlackKit components to help facilitate this interaction: SlackAuthButton and SlackAuthContainer.

Both of these components are client-side components. The SlackAuthButton component takes your redirectUrl and slackClientId as props:

<SlackAuthContainer
  actionButton={
    <SlackAuthButton
      slackClientId={process.env.NEXT_PUBLIC_SLACK_CLIENT_ID!}
      redirectUrl={process.env.NEXT_PUBLIC_REDIRECT_URL}
      onAuthenticationComplete={onAuthComplete}
    />
  }
/>

When this button is clicked, it will initiate an OAuth flow in a pop-up window where the user can authenticate with Slack and choose a workspace to install the app. Once the flow is complete, the pop-up window should close and the state of the component should update to show it is Connected to Slack. Behind the scenes, Knock handles the OAuth callback from Slack and stores an access_token on the tenant you provided to the KnockSlackProvider as channel data.

Note 🚨: if the pop-up window does not close, double check that the
redirectUrl matches your current environment.

From here, you can click Next to choose one or more Slack channels to associate with your object recipient.

Choosing Slack channels

On this route, you can associate your Knock object recipient with one or more Slack channels using the SlackChannelCombobox component. It accepts a slackChannelsRecipientObject as a prop that specifies a collection and objectId for the recipient object:

"use client";

import { SlackChannelCombobox } from "@knocklabs/react";

export default function SlackChannelWrapper({
  collection,
  objectId,
  className,
}: {
  collection: string,
  objectId: string,
  className: string,
}) {
  const slackChannelsRecipientObject = {
    objectId: objectId,
    collection: collection,
  };
  return (
    <div className={className}>
      <SlackChannelCombobox
        slackChannelsRecipientObject={slackChannelsRecipientObject}
      />
    </div>
  );
}

As you select channels using the combobox input, the component will update the channel data for that object to store the Slack channel ids.

Note 🚨: if you want to use a private Slack channel, you need to make sure that
the Slack Bot has been invited to that channel.

At this point, Knock has all of the information it needs to send Slack messages to your selected channels. Click Next to examine the channel data for your object and tenant.

Examine channel data

In this step, you're not required to take any action, but this page uses the Node SDK to pull channel data for your object recipient and tenant. This will give you an idea of how Knock is storing the data and how these two abstractions interact.

This data is pulled dynamically, so if you make different channel selections or disconnect and reconnect your Slack auth, the value for access_token and connections.channelIds will change as well.

If you click Next you can test your workflow end-to-end.

Trigger your workflow

In this step, you can see a code sample using the Node SDK of how you'd trigger your workflow. This is actually the code that runs in a server action when you submit the form on this page. Go ahead and submit a form to send a Slack message into your designated channels:

Wrapping up

If you need help implementing any of the code in this example app, consider joining our Slack community. We've got over 500 other developers learning how to improve their notification experiences with Knock.

Thanks for reading and Knock on 🤘

How push notifications work on Apple and Android

Jeff Everhart — Mon, 22 Apr 2024 18:14:50 +0000

Push notifications are an essential component of many mobile apps, helping developers engage users, improve retention, personalize experiences, and drive action. However, it's crucial for developers to use push notifications responsibly and respectfully to avoid overwhelming or alienating users.

But how do those notifications work? How does an application get direct access to your mobile OS and put itself at the forefront of your attention? In this post, we’ll walk you through the key concepts behind push notifications to better understand how this process works.

The basic framework of push notifications

Push notifications consist of interactions between the mobile device, your app, server, and the operating system push notification service (OSPNS).

When the app is launched, it requests the user's permission to receive push notifications.

(Source: Apple Developer)

With consent, the app communicates with the push notification service provided by the operating system, which is Apple Push Notification Service (APNS) for iOS devices or Firebase Cloud Messaging (FCM) for Android devices. The consent interaction generates a device token specific to the app on that device. The app sends this device token to the application server, registering the device for future notifications.

The application server stores and manages the device tokens, associating them with user profiles or app installs. When an event in the app needs to trigger a notification, the server creates the message, and then sends this message and the device tokens to the push notification service.

The push notification service processes the requests from the application server, verifying the messages. Using the device tokens, the push notification service identifies the associated devices and routes the notifications to them. The push notification service manages network conditions and device availability, as devices may be offline or in a do-not-disturb mode when the notification is sent. The service might queue the notifications or attempt redelivery later in such cases.

Once the notification reaches the user's device, the OS displays the notification according to the user's settings and the app's parameters.

This all seems straightforward. But the interaction that needs to happen between your app and backend, a user’s mobile device, and Apple/Firebase requires a lot of moving parts that you don’t have to consider if you are building email or in-app notifications. Let’s investigate some of these critical components of push notifications to understand how they work.

Device tokens: the core of push notifications

The journey begins when the user first launches the app. The app requests permission to send push notifications. This step is crucial, as the app cannot send notifications without the user's consent.

iOS mandates the explicit permission prompt above. Up until Android 13, apps didn’t have to require permission from a user to send push notifications explicitly. Instead, they could be managed via the Android settings page.

(Source: Android Developers)

From Android 13 onwards, the OS requires developers to use an opt-in model, like Apple. However, developers have more flexibility to design their permission modals in Android.

Once permission is granted, the device establishes communication with either APNS or FCM. This generates a unique identifier known as the device token.

The device token is the core part of push notifications. It is a globally unique identifier for the user’s device and that specific app installation on that device. If the user has your application installed on another device, they’ll be granted a separate token. If they uninstall and reinstall your app on that device, they’ll get another device token.

On Apple devices, you generate a device token using the registerForRemoteNotifications() method. On Android, developers declare their intent to send notifications in their manifest, and then the SDK asks FCM to generate the token.

The app then transmits this device token to its server, registering the device for future notifications. This registration signals to the server that the device can receive notifications.

When your server sends a push notification, it must always include this device token in the request.

APNS and FCM: the routing system for push notifications

The application (or your servers) doesn’t send push notifications itself. Instead, each operating system has a push notification service, which routes your request to your user's device.

For Apple, this is the Apple Push Notification Service (APNS). For Android, it is Firebase Cloud Messaging (FCM). The two are mostly similar, with a key difference being that APNS only works with Apple devices, whereas FCM works with Google and Apple devices.

Here's an overview of how this routing typically works:

Triggering the notification. An event on the application server triggers a notification. This event could be anything from a new message in a chat app to a price drop alert in a shopping app. The server prepares the notification, which includes setting its content (like the message body and title) and any additional data or commands.
Sending the notification to the push notification service. The application server sends the notification to APNS or FCM. The server includes the unique device tokens of the target devices in the request.
Processing by the push notification service. Upon receiving the notification request, the PNS verifies it. This includes checking the sender's credentials and the validity of the device tokens. The PNS may queue the notification for delivery. Depending on the service and the message's priority, it might be delivered immediately or delayed.
Delivering to the target device. Using the device token, the PNS locates the correct device. If the device is offline or unavailable, the PNS may retry delivery later based on the service’s retry policy. Once the device is reachable, the PNS delivers the notification. The operating system receives the notification on the device and passes it to the appropriate app. The notification is then displayed to the user.

APNS allows for varying notification priorities, providing immediate delivery or delivery options at the next opportunity. FCM, on the other hand, offers features like topic subscription, where devices can subscribe to specific topics for notifications, and message collapses to prevent similar notification overload.

Your app and server: push notification creation and management

With routing and delivering the push notification handled by the push notification services, your application and servers are responsible for creating the notification and managing device tokens. First, the server must craft the notification payload. The payload needs to be structured in a JSON format that complies with the specifications of the target push notification service.

For APNS, a payload looks like this:

{
  "aps": {
    "alert": {
      "title": "New Message",
      "body": "You have a new message from John."
    },
    "badge": 1,
    "sound": "default"
  },
  "customData": {
    "conversationId": "12345abcde",
    "messageType": "text"
  }
}

aps is the Apple-defined key for the payload. The alert object contains the notification's title and body. The badge tells the OS the number to display on the app icon and sound which sound to play when the notification is received. customData is a custom key-value pair (optional) for additional data the app might use.

An FCM payload has a similar, with the naming different:

{
  "to": "device_token_here",
  "notification": {
    "title": "New Message",
    "body": "You have a new message from John."
  },
  "data": {
    "conversationId": "12345abcde",
    "messageType": "text"
  },
  "priority": "high"
}

to is the target device token (this is in the HTTP headers for APNS). notification contains the notification's title and body, data is the custom key-value pairs for additional data, and priority sets the priority of the message.

Each push notification service has a limit on the size of the notification payload (4KB for APNS and FCM). Your server should ensure that the payload size does not exceed these limits.

Your server also has to manage a stateful connection to the push notification service to send each notification request. This request includes the payload and a list of device tokens to which the notification should be delivered. The request is made using server credentials like APNS certificates or FCM API keys for authentication. After sending the notification, your app server should handle the response from the push notification service, such as processing success or error messages and implementing retry logic.

Your server also has to manage and store device tokens. Usually, these are stored in your user database alongside other user information. These tokens must be stored securely to prevent unauthorized access, as they represent a direct line of access to the user's device.

Device tokens can change over time, such as when users reinstall the app or update their device's operating system. The mobile app must be designed to detect these changes and resend the updated token to the server. The server, in turn, must update its database with the new token.

Regularly validating and cleaning up the tokens in the database is essential. This can be done by processing feedback from the push notification service, which may inform the server about invalid or expired tokens that need to be removed or updated.

Knock provides mobiles
SDKs for iOS, Andriod, Flutter, and React Native that can help you manage the user token lifecycle.

Lean On Services for Push Notifications

Apple and Google have built extensive push notification services to help developers use their devices and integrate push notifications into their apps. These services do a lot of the heavy lifting associated with push notifications. As long as you use their SDKs and have a way to store tokens, using push notifications with these services securely is seamless.

At Knock, we remove this burden even further. You don’t have to manage the stateful connection with each push notification service. You also don’t need to work with two different JSON payload structures–you can send the same templated message to multiple providers.

Check out how to integrate Apple devices with Knock, as well as how to integrate FCM with Knock. If you need help, reach out to us in Slack or set up a time to talk with our team today.

Taking a deep dive into Slack's Block Kit

Jeff Everhart — Thu, 01 Feb 2024 15:47:45 +0000

If you’re building Slack notifications, you can keep it simple: a bit of text, maybe an emoji and some bolding to draw attention to what’s essential.

But you can also go much further with Slack notifications. Slack allows you to use various text options, images, design, and interactivity in your messaging. To put these together, you can use Slack’s Block Kit.

Block Kit is Slack's UI framework for composing the app's messages, modals, and pages. Using it, you can create rich notifications for your users.

Video walkthrough

Block Kit is just JSON

This is the most straightforward idea to grasp when working with Slack’s Block Kit. You are just putting JSON objects together, no matter what type of interface you are building. JSON is a string format that closely resembles JavaScript object format, and is made up of key-value pairs:

{
"key": "value",
"name" : "Jeff Everhart"
}

But these key-value pairs don’t have to be just strings. They can be strings, numbers, arrays, booleans, or even other objects. This means you can create complex hierarchies, like we’ll see in the following Slack interfaces.

Let’s start with a simple example:

{
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "plain_text",
                "text": "This is a plain text section block."
            }
        }
    ]
}

In this example, you have the root object, which is contained by the outer curly braces { … }. Inside this object, there's a key named blocks. The value associated with this key is an array, indicated by the square brackets [ ... ].

Our array here contains just one object, but, as we’ll see, we can put many objects inside this array to build our message UI. Inside this object, there are two key-value pairs:

type: This key has a value of "section." This indicates the type or role of this object within the broader structure.
text: The value associated with this key is another object. This nested object contains two key-value pairs:
- type: This has a value of "plain_text". Again, this is the role of the object
- text: This has the value of "This is a plain text.”, the actual content that will be displayed to the user.

To add another section, we can add more JSON objects to the blocks array. That’s what we’ll do next to build out our message.

Creating and sending a notification with Block Kit

Now, let’s put together something more useful using Block Kit. We’ll build a notification for an application performance monitoring tool, telling the user in Slack what is happening in their application. Typically, these monitoring tools will send notifications when certain conditions are met, like error rates above a certain threshold, or when actions are taken, like a new deployment.

Here’s what this message will look like in Slack:

Slack has an excellent tool to help build Block Kit, unsurprisingly called Block Kit Builder. This interface allows you to visually build out the JSON of your Slack message and get previews in real-time as you make changes.

Using the ‘add block’ actions on the left-hand side of the UI, you can add blocks to your payload with just a few clicks. The code pane will also highlight syntax errors as you go. Since JSON has a very specific structure, this can be pretty helpful if you’re just learning this syntax or need to debug something.

Here’s what the payload for this notification looks like:

{
    "blocks": [
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": "APM ALERT: Elevated Error Rates Detected!"
            }
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "2023-12-25\nService: *User Authentication API*\nEnvironment: *Production*"
            }
        },
        {
            "type": "section",
            "fields": [
                {
                    "type": "mrkdwn",
                    "text": "*Metrics*\n:red_circle: Error Rate: *15%* (Threshold: 5%)\n:red_circle: Response Time: *900ms* (Average: 200ms)\n:red_circle: Throughput: *1200 rpm* (Requests Per Minute)"
                }
            ]
        },
        {
            "type": "image",
            "block_id": "image4",
            "image_url": "https://i.imgur.com/Bj577mJ.png",
            "alt_text": "Error rates."
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Dashboard Link:* <https://example.com|APM Dashboard>"
            }
        },
        {
            "type": "divider"
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "Assign incident to:"
            },
            "accessory": {
                "type": "users_select",
                "placeholder": {
                    "type": "plain_text",
                    "text": "Select a team member",
                    "emoji": true
                },
                "action_id": "users_select-action"
            }
        },
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": "Recommended Actions:",
                "emoji": true
            }
        },
        {
            "type": "actions",
            "elements": [
                {
                    "type": "checkboxes",
                    "options": [
                        {
                            "text": {
                                "type": "mrkdwn",
                                "text": "*Verify backend database health and connection.*"
                            },
                            "value": "value-0"
                        },
                        {
                            "text": {
                                "type": "mrkdwn",
                                "text": "*Check Redis server and related metrics.*"
                            },
                            "value": "value-1"
                        },
                        {
                            "text": {
                                "type": "mrkdwn",
                                "text": "*Assess recent deployments for potential issues.*"
                            },
                            "value": "value-2"
                        }
                    ],
                    "action_id": "actionId-1"
                }
            ]
        }
    ]
}

Let’s break this down into its constituent parts to see what you can add to your messages using Block Kit.

Adding text

There are two ways to add text with Block Kit. First, we can use plain_text.

{
    "type": "header",
    "text": {
        "type": "plain_text",
        "text": "APM ALERT: Elevated Error Rates Detected!",
        "emoji": true
    }
}

This is easy for building out simple notifications and one-line messages. By setting emoji to true, you can optionally add emojis to this text. This is also a Header block, which makes the font larger and bolds the text.

But a better way to include text in a message is to use Slack’s mrkdwn to format your messages.

{
    "type": "section",
    "text": {
        "type": "mrkdwn",
        "text": "2023-12-25\nService: *User Authentication API*\nEnvironment: *Production*"
    }
},
{
    "type": "section",
    "fields": [
        {
            "type": "mrkdwn",
            "text": "*Metrics*\n:red_circle: Error Rate: *15%* (Threshold: 5%)\n:red_circle: Response Time: *900ms* (Average: 200ms)\n:red_circle: Throughput: *1200 rpm* (Requests Per Minute)"
        }
    ]
}

Here, we can use formatting such as bolding to highlight specific text. We can also use emojis to draw the user's attention to particular items in the notification.

The snippet above also shows how you can add some structure to your payloads using the Section block. By adding fields, we can group text or images into compact side-by-side columns if we include more than one text object:

Adding Images & Videos

Next, we have an image of the incident from the dashboard. You can add images to your Slack message by defining the block as an image type and then passing a publicly available image URL using the image_url key.

{
    "type": "image",
    "block_id": "image4",
    "image_url": "https://i.imgur.com/Bj577mJ.png",
    "alt_text": "Error rates."
}

The Image block also requires a value be passed for alt_text, and you can optionally provide a title. Depending on the use case for your Slack integration, the Image block can also use internal Slack files using the slack_file option.

The Video block is similar to images, with a different block type and a few additional pieces of information.

{
  "blocks": [

    {
      "type": "video",
      "title": {
        "type": "plain_text",
        "text": "How to use Slack.",
        "emoji": true
      },
      "title_url": "https://www.youtube.com/watch?v=RRxQQxiM7AA",
      "description": {
        "type": "plain_text",
        "text": "Slack is a nifty way to communicate with your team.",
        "emoji": true
      },
      "video_url": "https://www.youtube.com/embed/RRxQQxiM7AA?feature=oembed&autoplay=1",
      "alt_text": "How to use Slack?",
      "thumbnail_url": "https://i.ytimg.com/vi/RRxQQxiM7AA/hqdefault.jpg",
      "author_name": "Arcado Buendia",
      "provider_name": "YouTube",
      "provider_icon_url": "https://a.slack-edge.com/80588/img/unfurl_icons/youtube.png"
    }
  ]
}

According to the Slack docs, the Video block requires the following fields: type, alt_text, title, thumbnail_url, and video_url. Since the Video block is meant to embed and unfurl video links in any Slack context, the links.embed:write scope is required for your integration.

The example above would render like this inside of Slack.

Adding interactivity to notifications

Static notifications are good, but one of the biggest benefits of Slack over email as a notification channel is the level of interactivity you can add. Adding interactivity to your Slack notifications allows integrations to enhance user workflows and perform actions in other systems directly from their existing workspace.

Links can be interactive

In this example, we'll introduce a small element of interactivity first using a basic link. We can link the user to the APM dashboard so they can find out more information about the incident.

{
    "type": "section",
    "text": {
        "type": "mrkdwn",
        "text": "*Dashboard Link:* <https://example.com|APM Dashboard>"
    }
},

An important thing to note is that Slack mrkdwn links are subtly different from regular markdown links, using angle brackets, < … > instead of square brackets [ … ]. Even though links are the lowest level of interactivity we can provide for users in this context, a direct link to a resource in another system can help streamline workflows for the user.

Taking the application monitoring example one step further, this link could take the user directly to the offending server or even include a query string to filter to a more particular view:

{
    "type": "section",
    "text": {
        "type": "mrkdwn",
        "text": "*Dashboard Link:* <https://example.com/dashboard?server=ec2-small&errorType=warn,error|APM Dashboard>"
    }
},

Using action blocks

However, sometimes we’ll want to let users perform actions directly from a notification, so let’s move on to a more complex form of interactivity. In the following example, we have two ways for a user to interact with the notifications here:

A multi-select to assign the incident to a user
A list of checkboxes for an incident response checklist

Here are the blocks for these.

{
    "type": "section",
    "text": {
        "type": "mrkdwn",
        "text": "Assign incident to:"
    },
    "accessory": {
        "type": "users_select",
        "placeholder": {
            "type": "plain_text",
            "text": "Select a team member",
            "emoji": true
        },
        "action_id": "users_select-action"
    }
},
{
    "type": "header",
    "text": {
        "type": "plain_text",
        "text": "Recommended Actions:",
        "emoji": true
    }
},
{
    "type": "actions",
    "elements": [
        {
            "type": "checkboxes",
            "options": [
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*Verify backend database health and connection.*"
                    },
                    "value": "value-0"
                },
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*Check Redis server and related metrics.*"
                    },
                    "value": "value-1"
                },
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*Assess recent deployments for potential issues.*"
                    },
                    "value": "value-2"
                }
            ],
            "action_id": "actionId-1"
        }
    ]
}

The crucial parts of these blocks aren’t how you put them together but what you can do with them. In Slack Block Kit, these are ‘Action’ blocks, meaning you can do something with the output when a user selects them. Here, we’re just using multi-select and checkboxes, but you can have radio buttons, inputs, date and time pickers, and buttons.

You need a backend for your Slack app to use the output of these interactions. Then, you need to add a Request URL to your Slack dashboard so it knows where to send the “action.”

If you have a fully developed app, this will be a POST endpoint where you’ll manage the interactivity. For our case, we’ll spin up a ngrok URL for a local development application and add that to Slack.

In this example, we have a single Next.js API route handler that will accept the interaction payload generated by Slack. We will send our actions to the “/slack/interactive-endpoint” created by a /app/slack/interactive-endpoint/route.js file. Here’s all the code the create the endpoint and handle the interactive requests in the block JSON above:

export async function POST(request) {
  const formData = await request.formData();
  const payload = JSON.parse(formData.get("payload"));
  const channel = payload.channel.id;
  const actions = payload.actions[0];
  let res = null;
  if (actions.type === "users_select") {
    const selectedUserId = actions["selected_user"];
    res = await postMessage(
      channel,
      "You have been assigned an incident.",
      selectedUserId,
    );
  } else if (actions.type === "checkboxes") {
    payload.message.blocks.forEach((block) => {
      if (block.block_id === actions.block_id) {
        block.elements[0].options.forEach((option) => {
          const isSelectedOption =
            actions.selected_options.filter(
              (selectedOption) => selectedOption.value === option.value,
            ).length > 0
              ? true
              : false;

          if (isSelectedOption) {
            option.text.text = option.text.text.includes("~")
              ? option.text.text
              : `~${option.text.text}~`;
          } else {
            option.text.text = option.text.text.replaceAll("~", "");
          }
        });
      }
    });
    res = await updateMessage(
      channel,
      payload.message.ts,
      payload.message.blocks,
    );
  }

  return Response.json({ res });
}

async function postMessage(channelId, text, selectedUserId) {
  const url = `https://slack.com/api/chat.postMessage`;
  const slackResponse = await fetch(url, {
    method: "POST",
    body: JSON.stringify({
      channel: channelId,
      text: `<@${selectedUserId}>, ${text}`,
    }),
    headers: {
      Authorization: `Bearer ${process.env.SLACK_TOKEN}`,
      "Content-Type": "application/json; charset-utf8",
    },
  });

  const res = await slackResponse.json();
  return res;
}

async function updateMessage(channelId, timestamp, blocks) {
  const url = `https://slack.com/api/chat.update`;
  const slackResponse = await fetch(url, {
    method: "POST",
    body: JSON.stringify({
      channel: channelId,
      ts: timestamp,
      blocks: blocks,
    }),
    headers: {
      Authorization: `Bearer ${process.env.SLACK_TOKEN}`,
      "Content-Type": "application/json; charset-utf8",
    },
  });

  const res = await slackResponse.json();
  return res;
}

There’s quite a bit going on in this file, so let’s take a second to walk through what’s happening. In the first few lines, we’ll extract the payload from the POST request Slack sends, along with the channel and actions values. Here we’ll create some branches in our code to handle the different types of actions we’ve specified on the action_id key of our Slack blocks.

export async function POST(request) {
  const formData = await request.formData();
  const payload = JSON.parse(formData.get("payload"));
  const channel = payload.channel.id;
  const actions = payload.actions[0];
  let res = null;
  if (actions.type === "users_select") {
    //handle user select
  } else if (actions.type === "checkboxes") {
    //handle checkboxes
  }

  return Response.json({ res });
}

If the Slack user selects a value from the users select dropdown, we’ll execute the code in the users_select branch. In a more robust system, you might make a database call to assign someone to a particular incident, but in this example we’ll just send a message back to Slack tagging that invididual.

To do that, we’ll create another function called postMessage that will take a channelId, some message text and the selectedUserId as parameters. In this function, the SLACK_TOKEN value is a Bot token that we’ve assigned to this app.

async function postMessage(channelId, text, selectedUserId) {
  const url = `https://slack.com/api/chat.postMessage`;
  const slackResponse = await fetch(url, {
    method: "POST",
    body: JSON.stringify({
      channel: channelId,
      text: `<@${selectedUserId}>, ${text}`,
    }),
    headers: {
      Authorization: `Bearer ${process.env.SLACK_TOKEN}`,
      "Content-Type": "application/json; charset-utf8",
    },
  });

  const res = await slackResponse.json();
  return res;
}

Much of the data we’ll need to handle interactive selections is passed as a part of the payload from Slack, either as a part of the base payload or inside of the payload’s actions key. Once we’ve extracted the data into variables, we can call the postMessage function to make a POST request to Slack’s API.

const payload = JSON.parse(formData.get("payload"));
const channel = payload.channel.id;
const actions = payload.actions[0];
let res = null;
if (actions.type === "users_select") {
  const selectedUserId = actions["selected_user"];
  res = await postMessage(
    channel,
    "You have been assigned an incident.",
    selectedUserId,
  );
}

When this message, is sent it renders in Slack like this:

Now, this team member knows they have to deal with the incident. As they complete the recommended action, they can check off the items on the checklist.

Though the checks will show what has been completed, as each of those text descriptions is mrkdwn, we can also use formatting to highlight what has happened further by updating the message.

In our backend, we want to look through our payload to see what has been checked and strikethrough the text if something has been completed. If the interaction is generated by the checkboxes, we’ll loop through the blocks in the message and compare the checkbox values with the values that have been selected. If they have been selected, we can apply some additional formatting to the option text property.

if (actions.type === "checkboxes") {
  //loop through the blocks in the message payload
  payload.message.blocks.forEach((block) => {
    //if the current block triggered the interaction
    if (block.block_id === actions.block_id) {
      //loop through the options on that block
      block.elements[0].options.forEach((option) => {
        //compare the current option value to the list of
        //selected option values and generate a boolean
        const isSelectedOption =
          actions.selected_options.filter(
            (selectedOption) => selectedOption.value === option.value,
          ).length > 0
            ? true
            : false;

        if (isSelectedOption) {
          //if the current option is a selected option
          //add the strikethrough formatting if not already present
          option.text.text = option.text.text.includes("~")
            ? option.text.text
            : `~${option.text.text}~`;
        } else {
          //if not selected, remove any strikethrough formatting
          option.text.text = option.text.text.replaceAll("~", "");
        }
      });
    }
  });
  res = await updateMessage(
    channel,
    payload.message.ts,
    payload.message.blocks,
  );
}

Then, we need to update the message using the Slack API. We need the channel ID and the initial message timestamp (message.ts) to identify the message we are updating. We then pass that to our updateMessage function, which uses the chat.update API.

async function updateMessage(channelId, timestamp, blocks) {
  const url = `https://slack.com/api/chat.update`;
  const slackResponse = await fetch(url, {
    method: "POST",
    body: JSON.stringify({
      channel: channelId,
      ts: timestamp,
      blocks: blocks,
    }),
    headers: {
      Authorization: `Bearer ${process.env.SLACK_TOKEN}`,
      "Content-Type": "application/json; charset-utf8",
    },
  });

  const res = await slackResponse.json();
  return res;
}

When we select a checkbox, the text gets a strikethrough for all in the channel to see.

A good use for this style of updating is cleaning up after your notifications. If someone selects a choice from two buttons, you can remove the buttons and show the selection. You can see more design best practices for using Slack Block Kit in the Slack docs.

Depending on your product, a Slack integration can be a valuable addition to your feature set. At Knock, we're focused on helping developers leverage Slack as a notification channel, so here are a few additional posts we've written on using Slack:

Using Knock to Manage Your Slack Notification Design

Knock allows engineering and product teams to build their notification system, without dealing with the infrastructure required. You can manage notifications across multiple channels, such as email, in-app, Push, and Slack.

If you build out your Slack messages using Block Kit, you can quickly transfer your JSON to the Knock JSON block editor. A bonus is that you can use liquid within your blocks to inject variables and add control flows. You can follow the instructions to set up a Knock and Slack integration. With Knock, you can build out your OAuth flow, set up messaging templates, and use all the interactivity of Slack that we showed above.

If you want to try it out, sign up for a free account or chat with our team. 👋

How to authenticate users with Slack using OAuth

Jeff Everhart — Tue, 30 Jan 2024 14:22:37 +0000

Slack won't let your application anywhere near its users and platform without authentication through the Slack OAuth flow.

This gives Slack a secure way to control access to its API, ensuring that only authorized applications can interact with user data and functionality. It also allows users to grant specific permissions to your application based on the required scopes, thereby protecting their privacy and data security.

Luckily, implementing the OAuth flow in your application is straightforward, so developers can integrate their applications with Slack's features and functionalities, enabling them to enhance their app's capabilities, such as posting messages, scheduling reminders, or reading from channels where the app is present.

In this post, we're going to build a simple app that does just that - uses the OAuth flow to grant our application access to user data, all in less than 100 lines of code, including error handling.

Video walkthrough

If you prefer to learn with video, watch it here.

Why third-party apps use OAuth

Using OAuth with Slack offers several significant benefits for your application:

Secure authentication. OAuth is a secure standard for authorization that allows applications to authenticate users without handling their passwords. This minimizes the security risks associated with storing and transmitting sensitive credentials.
Scoped access. OAuth allows applications to request specific levels of access, commonly known as scopes, to a user's Slack resources, such as channels, messages, or user data. This means the application doesn’t gain more access than necessary, following the principle of least privilege.
User experience. The OAuth flow provides a more streamlined user experience by allowing users to authenticate with an existing Slack account.
Token-based access. After the OAuth process is complete, the application receives an access token to interact with the Slack API on behalf of the user. This token can be stored and used for future authenticated requests without further user interaction as long as the token remains valid.
Revoke access. Users can revoke the application's access through their Slack settings, giving them control over which third-party apps can access their Slack account.

Building the Slack OAuth flow into a Node.js application

Let's build a small Node.js application allowing you to authenticate using the Slack OAuth flow. This app only needs two components:

A route to call the Slack OAuth flow URL
A route to handle the redirect with the Slack access token

We'll also need a few dependencies to help us build this:

npm install dotenv express axios express-session

We need these for:

dotenv: loads environment variables from a .env file into process.env to make it easy to manage configuration variables like API keys.
express: a minimalist web server for Node.js.
axios: a common library for making HTTP requests.
express-session: session middleware for Express used to store session data on the server and allow persistence across requests.

Here's the complete code, which we'll add to a file called app.js:

require("dotenv").config();
const express = require("express");
const axios = require("axios");
const session = require("express-session");

const app = express();
const port = 3000;

// Configure session middleware
app.use(
  session({
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: true,
    cookie: { secure: "auto" },
  }),
);

// Redirect user to Slack's OAuth authorization page
app.get("/auth/slack", (req, res) => {
  const scopes = "channels:read";
  res.redirect(
    `https://slack.com/oauth/v2/authorize?client_id=${
      process.env.SLACK_CLIENT_ID
    }&user_scope=${encodeURIComponent(
      scopes,
    )}&redirect_uri=${encodeURIComponent(process.env.SLACK_REDIRECT_URI)}`,
  );
});

// Callback URI endpoint
app.get("/auth/slack/callback", async (req, res) => {
  const { code } = req.query;
  try {
    const tokenResponse = await axios.post(
      "https://slack.com/api/oauth.v2.access",
      null,
      {
        params: {
          code,
          client_id: process.env.SLACK_CLIENT_ID,
          client_secret: process.env.SLACK_CLIENT_SECRET,
          redirect_uri: process.env.SLACK_REDIRECT_URI,
        },
      },
    );

    if (tokenResponse.data.ok) {
      // Save the tokens in session or a secure place
      const accessToken = tokenResponse.data.authed_user.access_token;
      req.session.slack_access_token = accessToken;
      req.session.slack_user_id = tokenResponse.data.authed_user.id;

      // Fetch user's channels
      const channelsResponse = await axios.get(
        "https://slack.com/api/conversations.list",
        {
          headers: { Authorization: `Bearer ${accessToken}` },
        },
      );

      if (channelsResponse.data.ok) {
        const channels = channelsResponse.data.channels
          .map((channel) => channel.name)
          .join(", ");
        res.send(
          `Authorization successful! Here are your channels: ${channels}`,
        );
      } else {
        res
          .status(500)
          .send("Error fetching channels: " + channelsResponse.data.error);
      }
    } else {
      res
        .status(500)
        .send("Error authorizing with Slack: " + tokenResponse.data.error);
    }
  } catch (error) {
    console.error(error);
    res
      .status(500)
      .send(
        "Server error when exchanging code for token or fetching channels.",
      );
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});

Let's go through this to see how we're implementing OAuth in this app.

At the top, we have this line:

require("dotenv").config();

This line loads environment variables from a .env file into process.env. We haven't got our environment variables yet. We'll do that in a moment.

Then we need to set up Express:

const express = require("express");
const session = require("express-session");

const app = express();
const port = 3000;

Here, we require express and create a constant variable called app that represents the Express application. We also set the port variable to 3000, which is the port our server will listen on.

Then we're going to set up our session using express-session:

app.use(
  session({
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: true,
    cookie: { secure: "auto" },
  }),
);

Sessions are used to store information about the user across multiple requests. The secret is used to sign the session ID cookie, resave and saveUninitialized are flags for session saving behavior, and cookie: { secure: "auto" } ensures that cookies are secure in production (used over HTTPS).

With our server set up, we can create two endpoints to communicate with Slack. First, we'll create an endpoint for redirecting to the Slack OAuth flow:

app.get("/auth/slack", (req, res) => {
  const scopes = "channels:read";
  res.redirect(
    `https://slack.com/oauth/v2/authorize?client_id=${
      process.env.SLACK_CLIENT_ID
    }&user_scope=${encodeURIComponent(
      scopes,
    )}&redirect_uri=${encodeURIComponent(process.env.SLACK_REDIRECT_URI)}`,
  );
});

In this route, when a GET request is made to the /auth/slack path, the server responds by redirecting the client to Slack's OAuth authorization page.

The Slack URL is constructed with the query parameters from your application:

[https://slack.com/oauth/v2/authorize](https://slack.com/oauth/v2/authorize) is the base URL for Slack's OAuth 2.0 authorization endpoint.
client_id=${process.env.SLACK_CLIENT_ID} is the query parameter that includes the client ID for your application, which you obtain from Slack when you register your application. It identifies which application is making the request.
&user_scope=${encodeURIComponent(scopes)} is the query parameter that includes the OAuth scopes. The scopes variable contains the permissions the application requests from the user's Slack account. In this case, it asks permission to read the user's channels. URL encoding ensures that the scope string is safely formatted for inclusion in a URL.
&redirect_uri=${encodeURIComponent(process.env.SLACK_REDIRECT_URI)} is the query parameter for the URL-encoded redirect URI, telling Slack where to redirect the user after they have either approved or denied the authorization request. The redirect URI must match one of the URIs configured in your Slack app settings.

When the user navigates to your server's /auth/slack endpoint, they are immediately redirected to the Slack authorization page with the proper query parameters set, starting the OAuth flow.

Our next route is our Slack OAuth callback route. This is the endpoint Slack will call when they have authenticated the user:

// Callback URI endpoint
app.get("/auth/slack/callback", async (req, res) => {
  const { code } = req.query;
  try {
    const tokenResponse = await axios.post(
      "https://slack.com/api/oauth.v2.access",
      null,
      {
        params: {
          code,
          client_id: process.env.SLACK_CLIENT_ID,
          client_secret: process.env.SLACK_CLIENT_SECRET,
          redirect_uri: process.env.SLACK_REDIRECT_URI,
        },
      },
    );

    if (tokenResponse.data.ok) {
      // Save the tokens in session or a secure place
      const accessToken = tokenResponse.data.authed_user.access_token;
      req.session.slack_access_token = accessToken;
      req.session.slack_user_id = tokenResponse.data.authed_user.id;

      // Fetch user's channels
      const channelsResponse = await axios.get(
        "https://slack.com/api/conversations.list",
        {
          headers: { Authorization: `Bearer ${accessToken}` },
        },
      );

      if (channelsResponse.data.ok) {
        const channels = channelsResponse.data.channels
          .map((channel) => channel.name)
          .join(", ");
        res.send(
          `Authorization successful! Here are your channels: ${channels}`,
        );
      } else {
        res
          .status(500)
          .send("Error fetching channels: " + channelsResponse.data.error);
      }
    } else {
      res
        .status(500)
        .send("Error authorizing with Slack: " + tokenResponse.data.error);
    }
  } catch (error) {
    console.error(error);
    res
      .status(500)
      .send(
        "Server error when exchanging code for token or fetching channels.",
      );
  }
});

Let's break this down. The whole thing is a GET route handler for the /auth/slack/callback path. This is the URL where Slack redirects users after they have authorized the application.

When Slack redirects back to this URL, it will include a temporary authorization code as a query parameter that can be exchanged for an access token, which we access using const { code } = req.query.

We then POST that code using Axios with our CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI to the Slack API's oauth.v2.access endpoint.

If the request is successful, meaning tokenResponse.data.ok returns true, then we can use an access token to access Slack data as long as it is within the scopes. We save the access token in the session and then use it with the conversations.list API method. This sends back a list of channel names to the browser. The channel names are extracted from the API response and sent to the browser.

This seems like a lot of back-and-forth, and it is, but it can be summarized like this:

Steps 1 & 2 happen in the /auth/slack route, and steps 3 through 6 occur in the auth/slack/callback route.

Finally, we can start the server:

app.listen(port, () => {
  console.log(`Server running on <http://localhost>:${port}`);
});

If we were to run this now with node app.js it would error because we're missing all the environment variables we need. We need to create the .env file that dotenv will read the environment variables from:

# .env
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-client-secret
SLACK_REDIRECT_URI=your-slack-redirect-uri
SESSION_SECRET=some-random-string

But, of course, we don't have those variables. Let's move to Slack to create our application and get a client ID and client secret.

Setting up OAuth in Slack

It's quick and easy to get this information from Slack. Head to the Slack API Apps page and hit Create New App:

Choose “From Scratch,” then name your app and pick a workspace to develop it in:

From there, the first thing we want to do is set our permissions:

Scroll down until you see the 'Scopes' heading.
This is where we will set the scopes that we used in the code above. Here, we're just using channels:read as a user token scope, but you need to select the correct permissions for your application:

Next, we need to set the redirect URL. Because we are developing this locally for now, the full redirect URL from our code above would be http://localhost:3000/auth/slack/callback.

However, if we tried to add that to Slack, we'd get an error message because the HTTP protocol isn't secure. We could deploy our application to an online server, but instead, we can use ngrok. ngrok is an ingress controller that will give us an HTTPS URL for our localhost.

Development & testing only

ngrok opens a tunnel between the web and your local machine. It should only be used for the development and testing of this feature. In some cases, these local tunnels can be blocked by your network.

You can download and install ngrok using the instructions from the link above and then run it using:

ngrok http http://localhost:3000

If ngrok is installed correctly, this command will print some data to your console that includes a 'Forwarding' URL. You can append the /auth/slack/callback path to this URL and then add it to Slack:

Finally, let's grab our client ID and secret from the 'Basic Information' screen in Slack:

We can now add all those details to our .env file: the SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, and SLACK_REDIRECT_URI. Now, we can run the app with:

node app.js

We can access the application with our ngrok URL appended with /auth/slack. In some cases, firewalls or network settings may block ngrok's access to your local machine. If all is working correctly, you'll be redirected to Slack and see this page:

Click 'Allow,' Slack will then pass you back to the redirect URL. The code above will run to obtain the channel list, and you'll see this:

Congratulations, you've OAuthed into Slack. You can now build out that application to use the Slack functionality and data as needed.

OAuth simplifies authorization

More and more services are defaulting to OAuth as their authentication mechanism. It is secure and allows developers and users to control both access and data using clear scopes. It is straightforward for developers to implement and users to use, as they don't have to use new passwords.

You can integrate your OAuth flow with Knock so that the access, scopes, and data received can be used in your notifications. This means that all you need for extensive Slack notifications is the few lines of code above, and then Knock can take care of the rest.

If you want to add Slack notifications to your application, you can sign up for Knock or reach out to us on Slack to chat.

How to send in-app notifications with Next.js

Jeff Everhart — Mon, 29 Jan 2024 21:34:47 +0000

Next.js continues to be one of the most widely-used frameworks to build full-stack web applications. In version 13, Next.js introduced the App Router, a new routing paradigm built on top of React Server Components that works alongside the existing Pages Router. These changes offer developers a lot of benefits around data fetching and reduced bundle size, but also present a fundamental change to how you work in Next.js.

In this guide you'll learn how to:

create a notification workflow with an in-app feed step in Knock
identify users and trigger workflows with the Knock Node.js SDK and Server Actions
integrate the KnockFeedProvider with React Server Components
secure your application for production

Typically, real-time notification feeds are time-intensive features to create. First, you need to manage the infrastructure for WebSockets and Publish/Subscribe messaging patterns. Second, you need to deal with user preferences, user presence detection, storage and logging. And finally, you need to build out the frontend UI and underlying APIs to display the notifications. Luckily, Knock comes with all of that out of the box.

The in-app feed channel in Knock manages all of the backend infrastructure for you. The @knocklabs/react-notification-feed library is highly customizable, with advanced features like experimental cross-browser feed synchronization. If you need a higher level of control, the @knocklabs/client library is a low-level JavaScript SDK that you can use to build your own custom client-side experience.

Video walkthrough

Resources

If you want to try out Knock to power your notifications, you can sign up for free here.

The developer's guide to Slack's Markdown formatting

Colin White — Tue, 31 Oct 2023 18:06:17 +0000

Slack mrkdwn is Slack’s version of the Markdown language tailored for their platform. It allows developers to craft visually appealing and structured messages as well as emphasize critical information and add flair to their Slack messages.

In this guide, we’ll explore the nuances of mrkdwn, from its basic formatting capabilities to advanced features, coupled with practical examples to get you started and build the right Slack notifications for your application.

mrkdwn isn’t Markdown

At first glance, Slack’s mrkdwn and the popular Markdown syntax appear remarkably similar.

Both Slack’s mrkdwn and John Gruber’s Markdown syntax offer a way to richly format text using simple, plaintext notations. However, the design and capabilities of each of the languages is different due to their different purposes.

Markdown was designed as a lightweight markup language to convert plaintext into structurally valid HTML. It allows writers to easily ‘markup’ their text to convert it cleanly into HTML. Most developers will be used to Markdown in Github. You can use Markdown in both the Readme of a repo and individual commit messages. Markdown is also a core component of the Notion platform.

Slack’s mrkdwn is a custom formatting syntax tailored specifically for the Slack platform. Its sole goal is to make it easier to write rich, visually appealing text within Slack and take advantage of the core features of the platform such as @-mentions and channels.

The different purpose leads to core differences in the syntax. Most obviously, Markdown supports multiple header levels using #. For instance, ### Header 3 would represent a <h3> tag in HTML. mrkdwn doesn’t support multiple header levels in the same way. When would you use a header in a Slack message? It’s more streamlined for shorter messages.

The same goes for tables or syntax highlighting. These are core for a full document, but less important in Slack messages. Conversely, mrkdwn has special link formats, like <@U12345678> for user mentions or <!channel> to notify all members of a channel. Markdown doesn’t have a native equivalent for these functionalities given how platform-specific they are.

There are also some design choices within mrkdwn that are different from Markdown, such as the use of underscores for italics rather than a single asterisk, or angle brackets for links instead of square brackets.

Basic formatting: the foundations of mrkdwn

The core elements of mrkdwn help you convey your messages with clarity, emphasize key points, and make your text easy to scan and understand.

Three elements are commonly used with regular text:

Wrapping your text with asterisks (*) characters bolds the text to emphasize a word or phrase.
Wrapping your text with underscores (_) characters italicizes the text to emphasize subtly or indicate titles of works.
Wrapping your text with tildes (~) characters strikes through the text to indicate corrections or highlight something that’s no longer relevant.

Then we have two ways to add code to Slack messages. This could be particularly useful if you are building alerts for an application monitoring platform and need to show code that has failed.

Inline code is good for highlighting code, commands, or special terminology. For this, you wrap your text with backticks (`).

Multiline code blocks are ideal for sharing longer code snippets or preformatted text. To do this, you wrap your text with three backticks (`). To add a new line, you have to use \n.

Throughout, we are using the Block Kit to show how you build mrkdwn to use with the Slack API. Block Kit enables developers to build interactive and visually appealing messages in Slack. By incorporating mrkdwn within these blocks, you can achieve a fine balance between structure and textual presentation, ensuring your messages are not only interactive but also clear and captivating.

If you are writing these into your code for a notification app, here’s how they would look:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "This is *bold* \n This is _italic_ \n This is ~strikethrough~ \n This is `code` \n ```This is a code block\nAnd it's multi-line```"
      }
    }
  ]
}

This message will read in Slack as:

The primary goal of this formatting is to enhance comprehension and draw attention to essential information. Overuse might make messages harder to read. So, while it’s tempting to jazz up every message with formatting, always prioritize clarity.

You can find all the special formatting for mrkdwn in the Slack mrkdwn formatting docs.

Links and mentions: engaging directly with users and content

A foundational element of Slack is that you can use notifications to directly engage individuals and teams through mentions and direct those users to specific channels, applications, or sites through links.

We can split these into two types: internal Slack links and mentions and external links to sites and emails.

Internally, mrkdwn uses the @ symbol to mention a specific user (such as @colin) or user group, such as @here, @everyone, or @channel. As with when you are working directly in Slack, etiquette is important here. Don’t @everyone unless you really need everyone.

Internal to Slack you can also highlight and direct users to other channels, using the hash symbol (#).

To link away from Slack, you use hyperlinks. The format for these in mrkdwn is <URL|Displayed Text>. So <https://knock.app|Knock> will render as a clickable link titled “Knock” leading to https://knock.app.

You can use this syntax to link to an email address as well, you just prepend the email address with the mailto protocol. So <mailto:hello@knock.app|hello@knock.app> will render as a clickable “hello@knock.app” link that opens a user’s default email client with hello@knock.app as the recipient.

Here are code examples of these:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "This is a link to the <https://knock.app|Knock website> \n This is a mention of user @andrew \n This is an @channel mention \n This is a link to the #random channel \n This is an email link <mailto:hello@knock.app|hello@knock.app>"
      }
    }
  ]
}

This will show in Slack as:

When leveraging special links and mentions, always remember to consider the context and the intended audience. While mentions are a powerful way to get someone’s attention, they can be disruptive if overused.

Likewise, linking to channels or external sites should be done judiciously to ensure the message remains clear and focused.

Lists and blockquotes: structuring your message

Structuring messages lets you convey multiple points or highlight a specific piece of information. In mrkdwn, you can use lists and blockquotes to make your message more digestible.

There is no particular syntax for lists within mrkdwn, at least when sending messages via the API. Instead, you can use whichever symbol you want to specify an unordered list

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "- Item 1 \n - Item 2 \n - Item 3 \n - Item 4"
      }
    }
  ]
}

This renders to:

Ordered lists are just numbers or letters as the symbol. For instance:

{
"blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "1. Item 1 \n 2. Item 2 \n 3. Item 3 \n 4. Item 4"
      }
    }
  ]
}

This becomes:

To add blockquotes to highlight or emphasize a particular section, like a quotation or important note, you start a line with > followed by a space.

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "> This is a blockquote. It can span multiple lines and is often used to highlight specific pieces of information or quotations."
      }
    }
  ]
}

This renders as:

While lists and blockquotes are excellent tools for enhancing readability, they should be used thoughtfully. Too many lists can confuse readers, and excessive blockquoting might dilute the emphasis you’re trying to create.

Special formatting: elevating your Slack messages

There are a few other options with mrkdwn that you might need to use.

First, displaying dates in a consistent, readable manner with date formatting. Here, you use the timestamp in UNIX format with the syntax <!date^timestamp^{date_format}|{fallback_text}>, like this:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Today is: \n\n <!date^1697250654^{date_short}|Oct 13, 2023> \n <!date^1697250654^{date_short_pretty}|Oct 13, 2023> \n <!date^1697250654^{date_long}|Oct 13, 2023> \n <!date^1697250654^{date_long_pretty}|Oct 13, 2023> \n <!date^1697250654^{date_num}|Oct 13, 2023> \n <!date^1697250654^{date}|Oct 13, 2023>"
      }
    }
  ]
}

This renders as:

Tip: In JavaScript or TypeScript, use const unixTimestamp = Math.floor(Date.now() / 1000) to get the current date in UNIX format.

You can also combine some of the mrkdwn above. For example, to bold a link, you can use:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Here is a *bolded* link to <https://knock.app|*Knock*>"
      }
    }
  ]
}

Which will render a bolded link:

And, last but definitely not least, you have emojis:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":earth_americas: :rocket: :star: :alien: :moon: :sun_with_face: :zap: :fire: :cloud: :umbrella: :rainbow: :cat: :dog: :mouse: :elephant: :tiger: :rooster: :snake:"
      }
    }
  ]
}

This gives us:

Remember, you can never have enough emojis.

Putting it all together: A mrkdwn alert

Let’s put all this together into an alert that an application monitoring platform might send through Slack. Some elements we might use are:

Notifying a specific individual or team. The application might get this information from a database of SREs or on-call individuals. Here we will use @-mentions.
A concise description of the alert. Here we will use basic formatting to highlight the issue.
Links to dashboards and pertinent information. So the team can go deeper into the issue
A list of steps to be taken. These can be predefined and added to the Block Kit
Date and time information. Then anyone seeing the alert will know when the alert happened.
Emojis. This can add visual appeal to the alert and draw attention to it.

Altogether, the mrkdwn for this alert would be:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "@colin \n @sres \n\n *<!date^1697250654^{date_num}|Oct 13, 2023>* \n\n *[APM ALERT]: Elevated Error Rates Detected!* :red_circle: \n - Service: `User Authentication API` \n - Environment: `Production` \n\n :chart_with_upwards_trend: Metrics \n\n *Error Rate*: _15%_ (Threshold: _5%_) \n *Response Time*: _900ms_ (Average: _200ms_) \n *Throughput*: _1200 rpm_ (Requests Per Minute) \n :world_map: Geographical Impact: _US East, Europe Central_ \n  \n :sos: Related Incidents: \n <https://example.com|Database Latency Spike> \n <https://example.com|Redis Connection Failures> \n  \n :link: *Dashboard Link*: <https://example.com|APM Dashboard> \n  \n :speech_balloon: Recommended Actions: \n 1. Verify backend database health and connection. \n 2. Check Redis server and related metrics. \n 3. Assess recent deployments for potential issues."
      }
    }
  ]
}

This code looks complicated, but most of this information will be added dynamically from the APM. This creates a well-formatted, clear message for the team:

Use mrkdwn for clear communication

Slack’s mrkdwn is a powerful tool. Using mrkdwn enhances the readability and emphasis of critical pieces of information. The above example alert shows this, highlighting the crucial data for a team and making sure they can act on that information quickly.

Integrating mrkdwn into your Slack notifications not only beautifies the message but, more importantly, makes it exponentially more user-friendly. When time is of the essence, and clarity is paramount, leveraging the full potential of mrkdwn ensures that your alerts are not just noticed but acted upon effectively.

At Knock, we’ve taken mrkdwn further by integrating it into our templating engine and enhancing it with liquid tags for templating and an easy-to-use JSON editor. This allows you to design your Slack notifications exactly how you want them.

Check out some Slack notification examples for inspiration and sign up here to get started for free.

The top real-time notification services for building in-app notifications

Colin White — Tue, 24 Oct 2023 20:11:29 +0000

Real-time, in-app notifications in a product allow you to instantly engage users with relevant content, enhancing user experience and user retention. These notifications foster immediate action and feedback, ensuring users stay informed and connected to the application's latest updates and activities.

But building in-app notifications from scratch is challenging. First, you have to manage the infrastructure for WebSockets and Publish/Subscribe messaging patterns to power the real-time behavior. Second, your product needs logic to deal with user preferences, user presence detection, storage, and logging. Finally, you need to build out the frontend UI features and underlying APIs to display the notifications.

Using a SaaS service to offload some or all of this complexity allows you to concentrate on your own product while still giving the benefit of in-app notifications to your customers.

Here, we will evaluate 4 providers to power the real-time infrastructure for your in-app notifications.

The key features of real-time services for in-app notifications

What should you be looking for in a real-time service for in-app notifications?

Pricing: The cost-effectiveness of in-app notifications can significantly influence an app's overall budget and profitability. Transparent, scalable pricing ensures you can anticipate costs, allocate resources, and adjust any strategy based on budget.
Scalability: In-app notifications should adapt as user bases grow or shrink. A scalable notification system can handle spikes in traffic and vast volumes of concurrent users, ensuring every individual receives timely and consistent alerts without overburdening infrastructure.
Reliability: A reliable in-app notification system guarantees that users receive messages without delays. This reliability is vital for maintaining trust, especially in applications where timely alerts can impact user decisions or safety.
Framework: The chosen framework should support your desired communication mechanism, be it pub/sub for broadcasting messages to various subscribers, WebSockets for real-time bidirectional communication, or polling where the client periodically requests updates.
Features: Essential features to consider include presence (indicating who is online), low latency (ensuring rapid message delivery), the ability to query the state (understanding the current status of a user or system), and encryption (securing the content of the messages for privacy and protection).
Developer experience: An intuitive and well-documented platform streamlines the integration and maintenance process for developers. A positive developer experience translates to quicker implementation, fewer bugs, and more time spent refining and enhancing the core features of the application.

Let's look at a few services and how they align with these key features.

Pusher

Pusher Channels is a real-time notifications service that empowers developers to swiftly integrate real-time functionality, like live notifications and chat, into web and mobile apps using WebSockets. Pusher is known for reliability and scalability and is used by Buffer, GitHub, and Datadog.

Features

Managed WebSocket connections with fallback
Support for Publish/Subscribe framework
Presence detection
The ability to query the API to find out channel and state information
Interactivity through webhooks
End-to-end encryption

Pros

Scalability. Pusher easily handles surges in traffic, ensuring consistent real-time communication for applications ranging from startups to large enterprises.
Versatility. With SDKs for various languages and platforms, Pusher seamlessly integrates with numerous tech stacks, simplifying real-time feature implementation.
Reliable WebSocket fallback. Pusher's automatic fallback mechanisms guarantee continuous connectivity, even when WebSockets are unsupported or unstable.

Cons

Location. You are locked into a specific data center location when you sign up for Pusher and “it's not possible to change it afterwards.” This means that notification latency will slow further from the data center location.
Pricing complexity. With eight tiers and pricing changing with messages, connections, and support, it is not clear how you'll have to pay. You also have to pay separately for Pusher Beams, their Push notification service.

Pricing

Pusher has eight pricing tiers ranging from free on the “Sandbox” tier, where you get 200k messages per day and 100 concurrent connections, standard support and no monitoring, to $1,199/month on the “Growth Plus” tier for 90 million messages per day and 30,000 concurrent connections with premium support and monitoring. After that, you can contact the team for enterprise-level pricing.

PubNub

PubNub is a real-time communication platform based on HTTP long-polling instead of WebSockets. It provides scalable infrastructure to send and receive messages at low latency, and supports presence, compression, and storage. Customers include Niantic, Kustomer, and Autodesk.

Features

Uses the Publish/Subscribe framework to send high volumes of messages
Low latency messaging
GZip message compression
Message persistence for history through their storage API
Presence detection

Pros

Broad integration options. PubNub offers SDKs for numerous platforms and languages, making integration effortless across various development environments.
Robust feature set. Beyond just messaging, PubNub provides presence detection, storage, and playback, catering to diverse real-time app requirements.
High scalability. Built for large-scale applications, PubNub can handle millions of concurrent connections without compromising performance.

Cons

Pricing concerns. As message volumes or connections increase, costs can escalate due to usage-based pricing, making budgeting unpredictable for high-traffic applications.
Lack of WebSockets: PubNub uses the Publish/Subscribe model across HTTP rather than WebSockets. WebSockets have better scalability, better error handling, and lower latencies.

Pricing

PubNub has a free tier giving users up to 200 MAUs or 1M total transactions per month. They are clear that this is for testing purposes only and should not be used for production. For production-level applications, they have a $49/month tier that allows up to 1000 MAUs and 3000 transactions per MAU. Usage-based billing is used beyond those limits.

Ably

Ably is a robust real-time data delivery platform based on WebSockets with features like message ordering, presence, and connection recovery. Customers include Toyota, HubSpot, and Verizon.

Features

Low latencies of ~65ms for notification delivery
Queryable state API to find popular channels and user presence
Reduced bandwidth with delta compression
Also supports MQTT and server-side events as well as WebSockets

Pros

Connection State Recovery: Ensures interrupted users can resume their session without missing data.
Data Consistency: Guaranteed message ordering and delivery ensure that all users receive updates in the correct sequence.
Edge network. Ably uses 15 data centers around the globe and persists data across each to lower latencies.

Cons

Pricing Model: With a pay-as-you-go model, costs can escalate quickly with little control if you add more users and channels.

Pricing

Ably pricing has a free tier offering 6M monthly messages across 200 concurrent channels and 200 concurrent connections. They then move to a pay-as-you-go model which charges $2.50 per million messages, $15.00 per thousand concurrent channels, and $15.00 per thousand concurrent connections.

Socket.io

Socket.io is an open-source JavaScript library that facilitates real-time web communication. It simplifies bidirectional data transfer between web clients and servers. By abstracting WebSockets with fallbacks, it ensures consistent performance across devices and browsers, making real-time chats, notifications, and dynamic content more accessible for developers.

Features

Automatic reconnection
Middleware to filter and act on incoming packets
Built-in support for binary data.
Multiplexing through multiple namespaces

Pros

Ease of use: Socket.io offers a simple API, enabling developers to quickly integrate real-time functionalities without deep expertise in WebSockets.
Cross-platform: It provides client-side libraries for multiple platforms, ensuring broad compatibility across devices and browsers.
Fallback mechanisms: If WebSockets aren't available, Socket.io automatically falls back to other methods, ensuring consistent connectivity.

Cons

Scalability concerns: For very large-scale applications, Socket.io might face challenges, requiring additional configurations or optimizations.
Self-hosting: As Socket.io is only a library, you have to set up the infrastructure yourself.

Pricing

N/A. Socket.io is an open-source library that allows you to build real-time communication more easily.

Choosing the right solution

The above options are great choices for providing the backend infrastructure for real-time notifications. But if you want to use these real-time services as the foundation for in-app notifications, then you’ll have to think about what needs to be built around them. These options don’t feature:

UI components. While these services provide the backend infrastructure for notifications, they don't typically offer ready-to-use frontend components, meaning you'd need to design and implement the visual aspects of your notifications separately.
Templated messaging. You may need to build or integrate a system that allows for templated messages, letting you send consistent yet customizable notifications based on predefined templates.
Read receipts. Knowing if and when a user has seen a message can be vital for engagement and user experience. These platforms might not offer out-of-the-box solutions for read receipts, necessitating additional development.
Interactivity. These services deliver messages, but enabling interactive elements (e.g., buttons or links within notifications) would require additional development and design efforts.
User preferences. Tailoring notifications to user preferences, such as frequency, type, or topic, is crucial for a positive user experience. Incorporating such customization would need a separate mechanism or system.

Each of these will have to be built out for a complete in-app notification system.

Introducing notification infrastructure

Knock is a developer tool for building cross-channel notification systems. You can use it to add in-app notifications to your app with pre-built components to get you started quickly, but the power comes from integrating in-app and out-of-app channels such as email, push, SMS, and Slack. You can build workflows for these notifications so the right messages are sent via the right channels to the right users at the right time. We built Knock to be the best option for teams needing to implement any type of notification in their application.

Knock also takes care of all of your retry and delivery logic, as well as batching (collapsing multiple notifications about a single topic into one), managing per-user notification preferences, and providing unparalleled visibility into the notifications your product is sending.

Knock is an all-in-one notification platform that allows developers to build stateful, in-app notification experiences like floating feeds, inboxes, toasts and banners. Customers include Vercel, Amplitude, and Darwin Homes.

Features

Pre-built components to power in-app notifications that can be customized to match your brand
No infrastructure setup, no APIs to build
Workflow builder to determine how to alert users
Visual template builder to create and update notification templates
Preferences API to let users take control of their notifications
Strong support with responses in hours

If you'd like to try it out, you can sign up for a free account and get started by checking out our in-app feed docs. 👋