Quick start
In this guide you'll integrate Knock with your backend web application and send your first notification using Knock.
0. Create a Knock account
First, create a Knock account if you don't already have one and log into the Knock dashboard.
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. Set up environment variables
You can find your public and secret API keys under the Developers section of the Knock dashboard. Since we're working on the backend here, you'll want to use the secret key.
As a best practice, your API key should be set as an environment variable and should not be checked into source control.
3. Create a workflow in Kock
Next we'll create our first workflow in Knock via the dashboard.
A workflow encapsulates a notification in Knock. Each workflow takes a trigger call via the Knock API, runs the data you provide through a set of logic you configure, 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 a workflow. Click the "+ Workflow" button in the top right corner of the Knock dashboard. Name it whatever you like.
- Add a channel step. To send a notification, a workflow needs at least one channel step. A Knock channel represents a notification delivery medium (such as email or mobile push). 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. Choose the channel you'd like to use in your workflow and follow the dashboard steps to configure the channel.
- Design a 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 trigger call to populate any of the custom properties required in our workflow.
- Commit the workflow to development. Knock follows a versioning model similar to Git. This means that before you can trigger 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 Knock API. You can also learn more about workflows and channels in Knock via our guide on designing workflows.
4. Trigger your workflow
Now, you'll trigger your workflow to notify a set of users. When triggering workflows, you need to provide the following required pieces of data in your call to the Knock API:
recipients– The list of users to notify.data– The variable data that will populate your notification templates. Here you'll use the sample data payload we grabbed in step 3.
In the example below, we trigger a new comment notification workflow for two project members.
Learn more about notify calls in our API reference.
A note about managing users
Knock needs to know information about your users to send notifications, such as an email address for message delivery. Knock also persists this information for quick reference when triggering workflows.
We call this process of creating and updating user information in Knock "identification".
In the workflow trigger example just above, you are identifying your new users with Knock as part of the trigger API call itself, using the data provided in the recipients field. In future trigger calls, you could pass in just a list of your user ids, since Knock has stored this information with your account.
Alternatively, you can use the identify call to create or update users in Knock as a separate step in your integration.
Best practice is to identify your users with Knock whenever 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 Knock uses your user data to power your notifications, how to manage user data in Knock, and 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.
5. 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.
See our guide on going to production to review a complete set of steps you'll need to take to push your workflows to production.
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.