Objects

An Object represents a resource in your system that you want to map into Knock.

In this guide we'll walk through how to use objects for a few different use cases in Knock.

We'll start with an overview of objects and how to use them, then we'll walk through two common use cases for objects: Slack channel notifications and handling mutable data on long-running notifications (such as digests).

Note: Objects are an advanced feature within Knock. You can send multi-channel notifications across all channel types (except Slack) without touching the Objects API. If you're just getting started, we'd recommend coming back to objects when you've already started to leverage a few channels using Knock.

An overview of objects

Objects are a powerful and flexible way to ensure Knock always has the most up-to-date information required to send your notifications. They also enable you to send notifications to non-user recipients.

You can use objects to:

• send out-of-app notifications to non-user recipients (such as a Slack channel)
• send in-app notifications to non-user resources in your product (the activity feed you see on a Notion page is a good example)
• reference mutable data in your notification templates (such as when a user edits a comment before a notification is sent)

Note: As of today, our objects API support for in-app notifications and mutable data referencing is in beta. If you're interested in using this functionality, please reach out and let us know via the feedback button at the top of this page.

Sending object data to Knock

All objects belong to a collection, which groups objects of the same type together. An object should be unique within a collection, identified by the id given. We use the {collection, id} pair to know when to create or update an object.

Objects follow the same rules as all other items in Knock in that they are unique and logically separated per Knock environment.

The way you manage object data in Knock is largely the same as how you manage your user data. As with users, we support three approaches for managing Knock objects: individual, bulk, and inline.

1. Set individual objects

You can use the set object API to send us data for a single object.

API reference →

2. Bulk set objects

You can use the bulk set objects API to send us data for many objects at once. This endpoint allows you to identify up to 100 users at a time.

API reference →

3. Set objects inline

Lastly, you can also integrate object management into your workflow trigger calls. If you include additional object metadata (other than id and collection) in a workflow trigger call, Knock will perform an asynchronous action to upsert these objects as part of processing the workflow.

API reference →

Guidelines for use

Collection naming

You should use plural collection names wherever possible. The collection name should describe the group of one or many objects within the collection. Good examples of collection names are projects, teams, accounts.

The object identifier

The object id should be unique within the collection. It should also be a stable identifier, likely the primary key of the object in your system so it can be easily referenced later. Please note: object ids cannot be changed once set.

Properties

Objects can contain any number of key-value property pairs that you can then reference in templates and trigger conditions. Properties will always be shallowly merged between set calls, meaning that existing properties will be overwritten.

Examples

Slack channel notifications

A common notification use case we see in SaaS applications is the ability for users to connect a object in the product they're using to a channel in their own Slack workspace. That way when something happens in that object (e.g. a comment is left) they receive a notification about it in their connected Slack channel.

Let's take a fictional example here where we have an audio collaboration service that allows its customers to connect a Project object to a Slack channel. Once the Project and Slack channel are connected, all Comments left within the Project will result in notifications sent to the customer's Slack channel.

Here's how we'd use Knock objects to solve this.

1. Register our Project object to Knock

Typically whenever the project is created or updated we'll want to send it through to Knock.

2. Store the Slack connection information for the Project

Once our customer chooses to connect their Slack channel to the Project, we have a callback that then adds the Slack information as Channel Data.

3. Add Slack as a step to our workflow

Inside of the Knock dashboard, we're going to add a new Slack step to our new-comment workflow that will send a notification displaying the comment that was left in our product.

4. Send the Project as a recipient in your workflow trigger

Now when we trigger our new-comment workflow, we also want to add our Project object as a recipient so that the newly added Slack step will be triggered.

Knock then executes the workflow for this Project object as it would for any user recipients sent in the workflow trigger, skipping over any steps that aren't relevant. (In this case, the Project object only has one piece of channel data mapped to it—the Slack channel—so it won't trigger notifications for any other channel steps in our new-comment workflow.) When the Slack step is reached, the connection information we stored earlier will be used as a means to know which channel to send a message to and how to authenticate to that channel.