KnockDocs

How Knock works

Knock is a managed notifications-as-a-service platform to power your product notifications.

Knock consists of two parts: an API you send and receive data from, and a dashboard that you use to design your product notifications and the logical rules through which they'll flow.

In this section we'll provide a general overview of how Knock works and dive into the key concepts you'll use as you get started with Knock.

If you'd rather just start building you can check out our Quick Start guide.

Overview

Knock takes inputs from your product in the form of API calls: notify, identify, preferences.create. Once in Knock, these inputs are run through Workflows, which orchestrate and manage the delivery of Messages across in-app and out-of-app Channels.

Here's a visual of how these concepts work together:

How Knock works diagram

And here's a brief description of how each concept functions within Knock.

  • Users. A User represents an individual that will receive messages. You'll use the User object to store important attributes about your recipients (e.g. name, email) to be used in personalizing and delivering the messages you send with Knock.
  • Preferences. A Preference indicates a user's willingness to receive a particular kind of notification. Preferences belong to a User in Knock.
  • Channels. A Channel is a destination for your messages. It can be an out-of-app channel such as a SendGrid email integration, or an in-app channel such as the Knock notification feed. Channels are configured in the Knock dashboard as part of the setup process.
  • Workflows. A Workflow orchestrates the delivery of messages to your end users. When you configure a workflow you'll determine which channels its messages should route to, what those messages should look like on each channel, as well as any functionsโ€”batch, throttle, digestโ€”you want applied to the messages prior to delivery. A workflow is triggered by a notify call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)
  • Messages. A message is a per-user, per-channel message sent to your users. Messages are generated by Workflows. Examples of messages include emails, Slack messages, and messages within in-app feeds.

We'll be going into each of these concepts in more detail throughout this guide. You can also learn more about each one in our API reference.

The Knock workflow engine

The Knock workflow engine is a trigger driven system that allows you to control precisely when a message should be sent and who it should be sent to. It handles:

  • Complex message orchestration across channels
  • Batch, aggregation, and digesting of messages to prevent spamming
  • Synchronizing the read statuses of your messages across channels
  • Applying user preferences to avoid sending messages to users who have opted out
  • Reliable delivery of your messages to your delivery providers
  • Recipient fan-out across large groups of users
  • Capturing and storing data about engagement with the messages you send

Configuring Knock

Knock is easy to set up. It shouldn't take your engineering team more than a few hours to integrate Knock into your product, and we're happy to help with the integration however we can.

Here's how it works:

  1. Connect your channels. Connect any channels (e.g. email) through which you plan to send messages and enter the config details of your existing delivery providers (e.g. SendGrid.)
  2. Start sending user data into Knock. You'll use identify calls to send user data into Knock. We use this data to know how to reach a user on a given channel.
  3. Build your first workflow in Knock. You'll design the orchestration flow as well as the per-channel notification designs themselves. When finished, we'll give you the payload format to send from your backend.
  4. Trigger your Knock workflow from your backend. You'll call our the notify endpoint with the payload provided in step 3.