KnockDocs

Quick start

In this guide you'll integrate Knock with your application and send your first notification using Knock.

1. Add the Knock SDK to your backend

We have SDKs available in most major languages. Don't see your language listed here? Let us know!

2. Setup environment variables

You can find your API key under the 'Developers' section of the Knock dashboard. As a best practice, your API key should be set as an environment variable and should not be checked into source control.

3. Tell Knock about your users

Knock needs to know about your users to send them notifications. At a minimum we need the user's name, email address, and a unique id with which to identify them.

You'll keep user information up to date in Knock using the identify call. Best practice is to make an identify call to Knock when a new user is created and when any Knock-relevant user property changes. This way your user data is always up to date in Knock and we have what we need to send them notifications.

You can learn more about how and why Knock uses user data to power your notifications system (as well as how to migrate your current users into Knock) in our guide on managing user data.

πŸ” Security first πŸ”

We don't take storing your user data lightly. For more on our security practices, take a look at our security page.

4. Create your workflow in Knock

Next we'll log into the Knock dashboard to create our first workflow in Knock.

A workflow takes a notify call, runs it through a set of logic configured by you in the Knock dashboard, and outputs the actual messages that will be sent to your end users. All channel routing and message design takes place within the workflow. Here's how to create your first workflow:

  • Create workflow. Log into the Knock dashboard and click "+ Workflow" in the top right corner. Name it whatever you like.
  • Add channel step. To send a notification, a workflow needs a channel step. To add this step, we’ll click β€œedit steps” to enter the workflow canvas. Here we can see a number of steps available for us to add to our workflow including functions (such as batch and delay) and channels (such as email and in-app.) Choose the channel you'd like to use in your workflow and follow the dashboard steps to configure the channel.
  • Design notification. When your channel is configured, head back to the workflow's channel step and click "create" to create its notification template. The template starts with default copy, so we'll just use that for now.
  • Grab notify payload. Before we leave the workflow canvas and head back to your backend, let’s click on the trigger step to grab a payload data sample to use when we call Knock. This sample payload is auto-generated by the workflow creation process within the Knock dashboard. It gives us the JSON blob we'll need to pass through as data in our notify call to populate any of the custom properties required in our workflow.
  • Commit workflow to development. Knock follows a versioning model similar to Git. This means that before you can call your new workflow via the API, you'll need to commit it to your current environment and activate the workflow. Click the back arrow in the top-left corner of the workflow canvas to get back to the workflow overview page, where you can commit your changes and activate the workflow.

Now we're ready to trigger our workflow via the API.

5. Trigger your workflow

When you want to notify a set of users simply call the notify function to trigger the workflow you want to send.

When calling the notify function, you'll pass in the recipients you want to receive messages sent by the workflow, as well as the data (which we received during step 4) required to populate those messages.

Learn more about notify calls in our API reference.

6. Publish to production

Knock uses logically separated environments to control the roll-out of your notifications. When you're happy with the way your workflows work and look, you just need to push them to production to start sending notifications to your real users.

Go deeper

This was a simple overview to send your first notification with Knock. Read on to see how Knock can drive your notification needs, no matter their complexity.