# Knock Documentation

# Getting started
A technical and non-technical introduction to the basics of Knock, and a step-by-step guide to get you going in minutes.

## What is Knock?
Learn more about what Knock does and how it helps power your product notifications.
---
title: What is Knock?
description: Learn more about what Knock does and how it helps power your product notifications.
tags: ["getting started", "explainer", "explained"]
section: Getting started
---

Knock is notifications infrastructure that helps you implement notifications your users will love, without the effort of building and maintaining your own in-house notifications system.

In this overview, we’ll cover some of the foundational concepts of Knock. Knock is designed with both developers and product teams in mind: it’s easy for developers to implement quickly, and simple for less-technical users to maintain with our intuitive dashboard.

<div className="relative h-0" style={{ paddingBottom: "56.25%" }}>
  <iframe
    src="https://www.loom.com/embed/2865bc7d3bd04fcea9a527030c0f72b1"
    frameBorder="0"
    allowFullScreen
    className="absolute top-0 left-0 w-full h-full"
  ></iframe>
</div>
## Workflows

Workflows are a foundational concept in Knock. They allow you to easily model complex messaging flows across channels using a variety of logical function steps while respecting a user’s individual preferences. All Knock notifications are sent by triggering a workflow.

<Image
  src="/images/what-is-knock/workflow-diagram-3.png"
  alt="An image of a workflow diagram"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

Your application can trigger workflows using our REST API, any one of our [available SDKs](/sdks/overview), or by integrating a CDP like Segment as an event source. You can use the dropdown menu on the code sample below to look at a sample in your language of choice:

<MultiLangCodeBlock snippet="workflows.trigger" title="Trigger a workflow" />

Knock processes each workflow run using a combination of the following concepts:

## Recipients

Recipients are in most cases users in your application. As you trigger workflows for recipients, Knock creates a cache of the data needed to notify them on different platforms, like an email address, phone number, avatar URL, or push token. Knock also stores custom properties you pass from your application to customize their notifications, like a plan type, user role, or timezone.

```javascript title="An object used to create a User"
{
	// Id is a required prop
	id: "1",
	// Knock also supports default props for common channels
	name: "John Hammond",
	email: "hammondj@ingen.net",
	phone_number: "555-555-5555",
	avatar: "https://ingen.net/headshots/hammondj.jpg",
	timezone: "America/Costa_Rica"
	// You can add as many custom props as needed. These will be
	// merged onto the top-level User object
	properties: {
		"title": "CEO",
		"planType": "allAccess",
		"userType": "admin"
	}
}
```

## Channels

Channels in Knock represent a specific provider you have configured to send notifications. You can include channel steps in your workflows to send notifications with the providers you already use in production.
Knock supports the following channel types and providers:

<AccordionGroup>
  <Accordion title="Email">
    Knock supports sending email with [AWS SES](/integrations/email/aws-ses),
    [Mailersend](/integrations/email/mailersend),
    [Mailgun](/integrations/email/mailgun),
    [Mailjet](/integrations/email/mailjet),
    [Mailtrap](/integrations/email/mailtrap),
    [Mandrill](/integrations/email/mandrill),
    [Postmark](/integrations/email/postmark),
    [Resend](/integrations/email/resend),
    [Sendgrid](/integrations/email/sendgrid), [SMTP](/integrations/email/smtp),
    and [Sparkpost](/integrations/email/sparkpost).
  </Accordion>
  <Accordion title="SMS">
    Knock supports sending SMS with [Africa's
    Talking](/integrations/sms/africas-talking), [AWS
    SNS](/integrations/sms/aws-sns), [Mailersend](/integrations/sms/mailersend),
    [MessageBird](/integrations/sms/messagebird),
    [Plivo](/integrations/sms/plivo), [Sinch](/integrations/sms/sinch), [Sinch
    MessageMedia](/integrations/sms/sinch-message-media),
    [Telnyx](/integrations/sms/telnyx), [Twilio](/integrations/sms/twilio), and
    [Vonage](/integrations/sms/vonage).
  </Accordion>
  <Accordion title="Push">
    Knock supports sending push messages with [Apple Push Notification Service
    (iOS)](/integrations/push/apns), [Expo (React
    Native)](/integrations/push/expo), [Firebase Cloud Messaging
    (Android)](/integrations/push/firebase), and
    [OneSignal](/integrations/push/one-signal).
  </Accordion>
  <Accordion title="Chat">
    Knock supports sending chat messages with [Slack](/integrations/chat/slack),
    [Discord](/integrations/chat/discord), [Microsoft
    Teams](/integrations/chat/microsoft-teams),
    [WhatsApp](/integrations/chat/whatsapp).
  </Accordion>
  <Accordion title="In-app">
    Knock provides [a real-time in-app feed API](/integrations/in-app/knock) for
    receiving notifications, along with drop-in components to display them to
    your users.
  </Accordion>
</AccordionGroup>

A notification that is generated as a part of a workflow is called a `Message`, and Knock allows you to define dynamic message templates using a combination of a drag-and-drop editor and the Liquid templating language.

This helps product and marketing teams standardize on one templating system instead of using different templating languages for different providers. It also has the added benefit of lifting these messages out of your codebase so you can iterate quickly on customer communications without a developer.

## Functions

Each workflow can combine multiple function steps to model complex logic that creates better notification experiences.
You can combine the following function steps with any number of channel steps to create personalized notifications for your users:

<AccordionGroup>
  <Accordion title="Batch">
    [A batch step](/designing-workflows/batch-function) condenses multiple
    activities into one notification, e.g. batch all of the comments on this
    document for one hour and then send one email with all of the activities.
  </Accordion>
  <Accordion title="Delay">
    [A delay step](/designing-workflows/delay-function) waits for a specified
    duration before proceeding to the next step in a workflow, e.g. send the new
    user a follow-up email ten days after they sign up.
  </Accordion>
  <Accordion title="Branch">
    [A branch step](/designing-workflows/branch-function) uses multiple
    conditions to execute different branches of logic, e.g. if `user.planType
    === 'pro'` send them email A, else send them email B.
  </Accordion>
  <Accordion title="Throttle">
    [A throttle step](/designing-workflows/throttle-function) controls how many
    times a user is notified for a particular workflow over a specified
    duration, e.g. trigger the `server is down` workflow every minute while the
    server is down, but only send a max of one email every 5 minutes.
  </Accordion>
  <Accordion title="Fetch">
    [A fetch step](/designing-workflows/fetch-function) makes an HTTP request to
    an external service and uses the returned data in subsequent steps, e.g.
    query an MLS API for recent home sales in the user’s zip code and render
    them in an email.
  </Accordion>
  <Accordion title="Trigger workflow">
    [A trigger workflow step](/designing-workflows/trigger-workflow-function)
    allows you to trigger another workflow from within the current workflow,
    e.g. trigger a "welcome_sequence" workflow after recieving an
    "account_setup" notification.
  </Accordion>
</AccordionGroup>

In addition to combining channel steps and function steps to create complex workflows, you can augment these steps with additional logic based on the user recipient, inputs from your application, or the status of previous workflow steps. These are called step conditions.

## Step conditions

Step conditions exist across both channel and function steps, and they allow you to conditionally execute steps based on trigger payload data, user properties, or the status of previous steps

**Examples:**

- Only send an email message if an in-app message has not been seen
- Only send an in-app notification if `recipient.plan === "pro"`
- Only execute a delay step if `delay === true` in the trigger payload

In addition to giving your technical and non-technical users the ability to construct these workflows via a drag-and-drop editor, Knock also enables your users to exercise control over their own notification experience using a flexible preferences model.

## Preferences

In Knock, each workflow run is executed on behalf of a recipient, and each recipient can specify their preferences to receive notifications across a number of different criteria: channel types, individual workflows, and workflow categories.

<Image
  src="/images/what-is-knock/preferences.png"
  alt="An image of a preference set"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

Application developers have control over how these preference sets are presented to the user and which options to surface, but Knock enforces these preferences during every workflow run automatically.

You can learn more about how to set a user's preferences in our [preferences overview](/preferences/overview).

## Next steps

Now that you understand some of the core concepts of Knock, you can either start building with Knock or explore some of the more advanced features Knock offers.

### Build something

If you want to start by adding Knock to your existing system, you can check out our quick start guide to implement your first workflow. This quick start will help you integrate Knock with your backend codebase.

<SdkCardGroup>
  <SdkCard
    title="Quick start guide"
    linkUrl="/getting-started/quick-start"
    languages={["Your codebase"]}
  />
</SdkCardGroup>

If you want to keep learning about Knock using a curated example application, check out our catalog of [examples apps](/getting-started/example-apps). Here are some recommendations:

<SdkCardGroup>
  <SdkCard
    title="In-app feed & toasts"
    linkUrl="https://github.com/knocklabs/in-app-notifications-example-nextjs"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="SlackKit example"
    linkUrl="https://github.com/knocklabs/slack-kit-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="iOS example"
    linkUrl="https://github.com/knocklabs/ios-example-app"
    icon="swift"
    languages={["Swift"]}
    isExternal={true}
  />
</SdkCardGroup>

### Keep learning

While the workflow engine is at the heart of Knock, our goal is to build a complete notification system for our customers. Here is an overview of some of the more-advanced features that we provide:

#### UI components

Knock provides developers with React components like `<NotificationFeed/>` and `<SlackAuthButton/>` to use in their applications. You can read more about building in-app UI with Knock for both web and mobile [here](/in-app-ui/overview).

#### Advanced concepts

There is a lot more to learn about Knock, and our [concepts overview page](/concepts/overview) is a good place to start. Here are use cases our customers commonly solve with Knock:

- Powering [translation and localization](/concepts/translations) and managing timezone-aware delivery
- Creating advanced notification logic using [subscriptions](/concepts/subscriptions) and [schedules](/concepts/schedules)
- Integrating Knock with your application's data model, using [tenants](/concepts/tenants) and [objects](/concepts/objects) to power customized experiences
- Using [the template editor](/designing-workflows/template-editor/overview) to standarize messaging templates across providers

#### Developer tools

Knock is a developer-first platform, with both [environment](/concepts/environments) and [commit models](/concepts/commits). If you want to work with Knock resources in code, you can use our [Management API](/developer-tools/management-api) or [CLI](/developer-tools/knock-cli).

Once you're sending notifications through Knock, we offer observability tools like [workflow run logs](/send-notifications/debugging-workflows) (to examine all steps of workflow execution in your dashboard) and data streaming into a monitoring system like Datadog with [extensions](/integrations/extensions/overview).


## Quick start
Quickly get up and running with Knock.
---
title: Get started with Knock
description: Quickly get up and running with Knock.
tags: ["getting started"]
section: Getting started
---

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

<Steps titleSize="h2">
  <Step title="Create a Knock account">
    First, [create a Knock account](https://dashboard.knock.app/signup) if you don't already have one and log into the [Knock dashboard](https://dashboard.knock.app).
  </Step>
  <Step title="Add the Knock SDK to your backend">
    We have SDKs available in [most major languages](/sdks/overview#server-side-sdks). Don't see your language listed here? [Let us know](mailto:support@knock.app)!

    <MultiLangCodeBlock snippet="sdks.install" title="Install Knock" />

  </Step>
  <Step title="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.

    ```bash
    KNOCK_API_KEY='sk_example_123456789'
    ```

  </Step>
  <Step title="Create a workflow in Knock">
    Next we'll design 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 build your first workflow:
    <AccordionGroup>
      <Accordion title="Create a workflow">
        Click the "+ Workflow" button in the top right corner of the Knock dashboard. Name it whatever you like.
      </Accordion>
      <Accordion title="Add a channel step">
        To send a notification, a workflow needs at least one [channel step](/designing-workflows/channel-step). To add this step, we'll click “edit steps” to enter the workflow canvas editor.

        Here we can see a number of steps available for us to add to our workflow, including functions (such as [batch](/designing-workflows/batch-function) and [delay](/designing-workflows/delay-function)) and channels.

        Choose the delivery channel you'd like to use in your workflow and drag it onto the workflow canvas.
      </Accordion>
      <Accordion title="Design the notification message">
        After adding a channel step, we can configure the notification's content by clicking on "Edit template" in the channel's edit step view to see that step's [message template](/designing-workflows/template-editor/overview). The template starts with default copy, so we'll just use that for now.
      </Accordion>
      <Accordion title="Grab trigger 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 when you create a workflow within the Knock dashboard. It gives us the JSON blob we'll need to pass through as `data` in our trigger call in order to populate any of the custom properties defined in our workflow.
      </Accordion>
      <Accordion title="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 to 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.
      </Accordion>
    </AccordionGroup>
    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](/send-notifications/designing-workflows).

  </Step>
  <Step title="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, using [inline identification](/reference#trigger-workflow-inline-identify).

    <MultiLangCodeBlock
      snippet="workflows.trigger-with-user-identification"
      title="Trigger your workflow"
    />

    Learn more about trigger calls in our [API reference](/reference#trigger-workflow).

  </Step>
  <Step title="Publish to production">
    Knock uses [logically separated environments](/concepts/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 promote them to production to start sending notifications to your real users.

    See our [going to production](/guides/implementation-guide#going-to-production) checklist to review a complete set of steps you'll need to take to push your workflows to production.

  </Step>
  <Step title="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.

    - [Learn about Knock's core data concepts](/concepts/overview)
    - [Learn how to set up a real-time, in-app notification feed in minutes](/notification-feeds/getting-started)

  </Step>
</Steps>


## Example apps
Example applications to help you get started with Knock.
---
title: Knock example apps
description: Example applications to help you get started with Knock.
tags: ["nodejs", "using knock", "getting started", "react"]
section: Getting started
---

Below you'll find a number of Knock example apps to learn from or incorporate into your project.

## In-app notification examples (web)

<SdkCardGroup>
  <SdkCard
    title="In-app feed & toasts"
    linkUrl="https://github.com/knocklabs/in-app-notifications-example-nextjs"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="In-app feed"
    linkUrl="https://github.com/knocklabs/angular-in-app-feed-example"
    icon="angular"
    languages={["Angular"]}
    isExternal={true}
  />
  <SdkCard
    title="Notion-style feed"
    linkUrl="https://github.com/knocklabs/notion-feed-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="In-app feed & toasts"
    linkUrl="https://github.com/knocklabs/nuxt-feed-example"
    icon="vue"
    languages={["Vue.js", "Nuxt"]}
    isExternal={true}
  />
  <SdkCard
    title="Linear-style inbox"
    linkUrl="https://github.com/knocklabs/inbox-example-app"
    icon="react"
    languages={["Next.js", "React"]}
    isExternal={true}
  />
</SdkCardGroup>

## Web app examples

<SdkCardGroup>
  <SdkCard
    title="SlackKit example"
    linkUrl="https://github.com/knocklabs/slack-kit-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="Webhook example"
    linkUrl="https://github.com/knocklabs/customer-facing-webhooks-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="Alerting example"
    linkUrl="https://github.com/knocklabs/alerting-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
  <SdkCard
    title="Marketplace example"
    linkUrl="https://github.com/knocklabs/marketplace-example"
    icon="react"
    languages={["React", "Next.js"]}
    isExternal={true}
  />
</SdkCardGroup>

## Mobile examples

<SdkCardGroup>
  <SdkCard
    title="iOS example"
    linkUrl="https://github.com/knocklabs/ios-example-app"
    icon="swift"
    languages={["Swift"]}
    isExternal={true}
  />
  <SdkCard
    title="Android example"
    linkUrl="https://github.com/knocklabs/knock-android/tree/main/knock-example-app"
    icon="kotlin"
    languages={["Kotlin"]}
    isExternal={true}
  />
</SdkCardGroup>



# Concepts
Learn about the key concepts in Knock.

## Overview
Learn about the key concepts in Knock.
---
title: Core concepts
description: Learn about the key concepts in Knock.
tags: ["how knock works"]
section: Concepts
---

## Workflows

In Knock, all notifications are sent via a workflow. Each workflow acts as a container for the logic and templates that are associated with a type of notification in your system.

[Learn more →](/concepts/workflows)

## Channels

A channel in Knock represents a configured provider, such as Sendgrid for email, to send notifications to your recipients. Most providers within Knock use credentials that you supply to deliver notifications on your behalf. These credentials and other settings are what make a configured channel.

[Learn more →](/concepts/channels)

## Commits

Knock uses a commit model to version changes that you make to all of your Knock resources. When you make a change to a workflow or a layout in the Knock dashboard, you'll need to commit it to your development environment before those changes will appear in workflows triggered via the API.

[Learn more →](/concepts/commits)

## Environments

Knock uses the concept of environments to ensure logical separation of your data and configuration. This means that users and preferences created in one environment are **never** accessible to another. Environments usually map to the environments you have in your software development life cycle (SDLC).

[Learn more →](/concepts/environments)

## Recipients

A Recipient within Knock is any [User](#users) or [Object](#objects) that may wish to receive notifications.

[Learn more →](/concepts/recipients)

## Users

A user in Knock represents an individual who should receive a message. A user's profile information contains important attributes about the user that will be used in messages (name, email). The user object can contain other key-value pairs that can be used to further personalize your messages.

[Learn more →](/concepts/users)

## Preferences

Preferences enable your users to opt-out of the notifications you send using Knock.

[Learn more →](/concepts/preferences)

## Objects

An object represents a resource in your system that you want to map into Knock. 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 in-app notifications to non-user resources in your product (the activity feed you see on a Notion page is a good example)
- send out-of-app notifications to non-user recipients (such as a Slack channels)
- reference mutable data in your notification templates (such as when a user edits a comment before a notification is sent)

[Learn more →](/concepts/objects)

## Subscriptions

A subscription represents a relationship between a non-user entity (an Object) and a Recipient (the subscriber). Subscriptions are used to model pub/sub behavior and lists of recipients that Knock will automatically fan out a workflow trigger to on your behalf.

[Learn more →](/concepts/subscriptions)

## Schedules

A schedule allows you to automatically trigger a workflow at a given time for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

[Read more →](/concepts/schedules)

## Tenants

Tenants represent segments your users belong to. You might call these "accounts," "organizations," "workspaces," or similar. This is a common pattern in many SaaS applications: users have a single login joined to multiple tenants to represent their membership within each. Within Knock you can model your tenant objects as first-class entities and use them to scope features.

[Learn more →](/concepts/tenants)

## Messages

A message in Knock represents a notification delivered to a recipient on a particular channel. Messages contain information about the request that triggered its delivery, a view of the data sent to the recipient, and a timeline of its lifecycle events.

[Learn more →](/concepts/messages)

## Translations

Translations support localization in Knock. They hold the translated content for a given locale, which you can reference in your message templates with the `t` Liquid function filter.

[Learn more →](/concepts/translations)

## Conditions

Knock uses conditions to model checks that determine variations in your workflow runs. They provide a powerful way to create more advanced notification logic flows.

[Learn more →](/concepts/conditions)

## Variables

Variables within Knock let you set shared constants or secrets that you can use in all of the workflows and templates under your account. Variables can be overridden at the environment level to set per environment constants.

[Learn more →](/concepts/variables)

## Audiences

Audiences are user segments that you can notify. You can bring audiences into Knock programmatically with our API or a supported reverse-ETL source.

[Learn more →](/concepts/audiences)


## Workflows
Learn more about what a workflow in Knock is, and how to think about grouping together your cross-channel notifications into different workflows.
---
title: Workflows
description: Learn more about what a workflow in Knock is, and how to think about grouping together your cross-channel notifications into different workflows.
tags: ["categories", "archive", "archived"]
section: Concepts
---

In Knock, all notifications are sent via a workflow. Each workflow acts as a container for the logic and templates that are associated with a kind of notification in your system.

Workflows are represented as a set of steps, which are either function or channel steps. Functions apply logic to your workflow run, like batching to collapse multiple calls into single notifications or delays to pause the execution of a workflow for some duration. Channel steps produce a notification that will be delivered via a [configured channel](/concepts/channels). All steps can also have conditions to determine if and when they should run.

Workflows in Knock:

- Always have a unique `key` associated
- Are always executed for a single recipient at a time
- Contain all of the logic and templates for the notifications you send
- Can have recipient preferences attached
- Can be triggered via the API, an event, or on a schedule for a recipient

## Thinking in workflows

A workflow groups together cross-channel notifications and the business logic that governs those notifications into a single entity. Workflows are always executed on behalf of a single recipient and can have other properties associated with them, like the "actor" who performed the action that triggered the notification.

It's highly recommended to group notifications about the same "topic" or "entity" in your system into individual workflows. While it might be tempting to build a single workflow with conditional logic for all of your notification use cases that can be triggered from anywhere within your application with the same workflow `key`, modularizing your workflows by topic and use case allows you to offer the highest level of configurability to your users via [Preferences](/concepts/preferences). Our customers also find that concise, topic-specific workflows are easier to maintain and iterate on.

As an example, if we're building a document collaboration app where users can comment on specific documents, we might group all of the logic about the cross-channel comment notifications we have into a single `new-comment` workflow.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> remember that in Knock all
      notifications sent are via a workflow. There's no other way to send
      notifications to your recipients, so every notification you want to send
      must be represented in a workflow.
    </>
  }
/>

You can read more about how to build your workflows and the features available within the workflow builder under the [designing workflows section of the documentation](/designing-workflows).

## Workflows and notification templates

Each workflow you build will contain one or more [channel steps](/designing-workflows/channel-step). It's these channel steps that contain the templates that will be rendered to produce a notification sent to the recipient of the workflow run.

The templates associated with a channel step **only** exist in the context of that channel step. That means that templates cannot currently be shared across workflows, or even across other channel steps within the same workflow.

## Managing workflows

Knock workflows can be managed either via the Knock Dashboard or programmatically via the [Management API](/mapi). The [Knock CLI](/cli) offers a convenient way to work with the management API locally to make updates to workflows and their templates.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> remember that workflows and other
      resources in Knock can only ever be edited in the development environment.{" "}
      <a href="/concepts/commits">Learn more about versioning</a> and{" "}
      <a href="/concepts/environments">environments</a>.
    </>
  }
/>

### Workflow categories

Each workflow can have one or more categories associated with it. Categories are useful for grouping related types of workflows together and offer a way to apply a user's preferences across many workflows.

To set a `category` for a given workflow, go to that workflow's page in the dashboard, click the "..." menu, and select "Manage workflow." From there, you'll be able to add categories.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> workflow categories are{" "}
      <strong>case sensitive</strong>.
    </>
  }
/>

### Version control for workflows

All changes to workflows, including changes made to the templates inside of a workflow, are version controlled. Changes must be made in the development environment and are then "committed" and then "promoted" between environments for that version to be live within an environment. This allows you to confidently make changes to workflows, without affecting any running in production.

Read more about [environments](/concepts/environments) and [versioning](/concepts/commits) in Knock.

### Workflow status

Each workflow has an `Active`/`Inactive` status that is displayed in your dashboard's **Workflows** section. The status defaults to `Active` and can be set by clicking on the workflow and using the "Status" selector.

This is your kill switch for a given workflow should you need it; any attempt to trigger an `Inactive` workflow will result in a `workflow_inactive` [error](/reference#error-codes). The status setting operates independently from the commit model so that you can immediately enable or disable a workflow in any environment without needing to go through environment promotion. **It is environment-specific and will only be applied to the current environment.**

### Archiving workflows

Archiving a workflow allows you to permanently remove a workflow from Knock. When you archive a workflow it will be removed from **all environments** and cannot be called via API. Once a workflow is archived, it **cannot be undone**. If you have delayed runs for a workflow that is archived, when the workflow run resumes after the delay it will immediately terminate.

## Running workflows

Workflows defined in Knock are executed via trigger, which starts a workflow run for the recipients specified using the `data` passed to the workflow trigger.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> it's important to know that in
      Knock a workflow run is <strong>always</strong> executed against a single
      recipient. Workflows can always be invoked for multiple recipients, but
      each <em>run</em> will only be for a single recipient.
    </>
  }
/>

### Triggering a workflow

In Knock, workflows can be triggered in three different ways:

- **API call**: workflows can be [triggered directly via an API call](/send-notifications/triggering-workflows) to our workflow trigger endpoint. This is the most common form of integration and means that Knock is integrated into your backend codebase, usually alongside your application logic.
- **Events**: using different [event sources](/integrations/sources/overview/), you can connect Knock to CDPs such as Segment and Rudderstack and map the events those systems produce to workflows that should be triggered.
- **Schedules**: [workflows can be scheduled](/concepts/schedules) to be run for one or more recipients, in a recipient's local timezone on a one-off, or recurring basis.

### Canceling a workflow run

Any triggered workflow that has an active delay or batch step can also be canceled to halt the execution of that workflow run. Workflow cancellations today must happen through the cancellation API and can only occur when a `cancellation_key` has been specified on the workflow trigger.

[Read more about canceling workflows](/send-notifications/canceling-workflows)

### Workflow runs and recipients

When a workflow is triggered via the API we return a `workflow_run_id` via the API response. This ID represents the workflow run for all of the recipients that the workflow was triggered against.

For each recipient included in the workflow trigger or that the workflow should fan out to [via subscriptions](/concepts/subscriptions), a new workflow run is enqueued. We call this the recipient workflow run.

Recipient runs are visible within the Knock dashboard by going to **Developers** > **Logs**. Each run can be inspected to view its current state as well as the steps executed for the workflow. It's also possible from a workflow run log to see the messages (notifications) produced by the run.

### Workflow run scope

When a workflow run is executed, associated state is loaded to be used within the templates and conditions defined in the workflow. This state is known as the workflow run scope. The run scope can be modified during the duration of the workflow run by fetching additional data via the [fetch function](/designing-workflows/fetch-function).

[Read more about the properties available](/designing-workflows/template-editor/variables)

## Automate workflow management with the Knock CLI

In addition to working with workflows in the Knock dashboard, you can programmatically create and update workflows using the [Knock CLI](/developer-tools/knock-cli) or our [Management API](/developer-tools/management-api).

If you manage your own workflow files within your application, you can automate the creation and management of Knock workflows so that they always reflect the state of the workflow files you keep in your application code.

The Knock CLI can also be used to commit changes and promote them to production, which means you can automate Knock workflow management as [part of your CI/CD workflow](/developer-tools/integrating-into-cicd).

### Workflow files structure

When workflows are pulled from Knock, they are stored in directories named by their workflow key. In addition to a `workflow.json` file that describes all of a given workflow's steps, each workflow directory also contains individual folders for each of the [channel steps](/designing-workflows/channel-step) in the workflow that hold additional content and formatting data.

```txt title="Local workflow files structure"
workflows/
└── my-workflow/
    ├── email_1/
    │   ├── visual_blocks/
    │   │   └── 1.content.md
    │   └── visual_blocks.json
    ├── in_app_feed_1/
    │   └── markdown_body.md
    └── workflow.json
```

If you're migrating your local workflow files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using [`knock workflow push --all`](/cli#workflow-push). Each `workflow.json` file should follow the structure defined [here](/mapi#workflows-object).

You can learn more about automating workflow management in the [Knock CLI reference](/cli). Feel free to <a href="mailto:support@knock.app">contact us</a> if you have questions.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is there a limit to the number of workflows I can have in Knock?">
    No, there's no limit to the number of workflows you can have within your
    Knock environment.
  </Accordion>
  <Accordion title="Can I create per-tenant/per-customer workflows?">
    While it's possible to create per-customer workflows using the management
    API, we recommend avoiding doing this in favor of using [per-tenant
    overrides](/concepts/tenants#custom-branding) and
    [preferences](/concepts/preferences) to control individual workflows.
  </Accordion>
  <Accordion title="Is there a way to disable a workflow without archiving it?">
    Yes, you can set a workflow's [status](/concepts/workflows#workflow-status)
    to `Inactive` to disable it.
  </Accordion>
  <Accordion title="What happens to in-progress workflow runs when I set a workflow's status to Inactive?">
    Any in-progress workflow runs will be immediately terminated.
  </Accordion>
</AccordionGroup>


## Channels
Learn about what a channel is in Knock and how you can use channels to power your cross-channel notification delivery.
---
title: Channels
description: Learn about what a channel is in Knock and how you can use channels to power your cross-channel notification delivery.
tags: []
section: Concepts
---

A channel in Knock represents a configured provider to send notifications to your recipients. Most providers within Knock use credentials that you supply to deliver notifications on your behalf. These credentials and other settings are what make a configured channel.

Within Knock, we split channels into different types, where each type has at least one provider associated that can be configured:

- [Email](/integrations/email/overview) (such as Sendgrid, Postmark)
- [In-app](/integrations/in-app/overview) (such as feeds, toasts, banners)
- [Push](/integrations/push/overview) (such as APNs, FCM)
- [SMS](/integrations/sms/overview) (such as Twilio, Telnyx)
- [Chat](/integrations/chat/overview) (such as Slack, Microsoft Teams, and Discord)
- [Webhook](/integrations/webhook/overview) (send webhooks to custom channels or enable your own customers to configure webhooks in your product)

You can read more about the various types of [channel integrations available here](/integrations/overview).

## Managing channels

You can create and manage channels within Knock from the dashboard under the **Integrations** > **Channels** section. A created channel exists across all environments in your Knock account and uses the same ID for each environment.

**Please note**: only admins and owners on an account can manage channels.

## Channel settings

For each channel you create in the Knock dashboard, you will need to configure the channel per environment for it to be valid. Each provider requires different configuration data, and you can see the required settings in the [integrations guide](/integrations/overview).

Given that channel configuration is **per-environment** this makes it possible to have separate settings for your testing/sandbox environments vs your production environments. Channel settings can easily be cloned across environments when needed.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> unlike other types of
      configuration in Knock, channel settings are never versioned, meaning when
      they are saved the configuration is synchronized to the Knock
      configuration store to immediately take effect.
    </>
  }
/>

## Using channels to send notifications

In Knock, all notification messages are sent via a channel step configured within a [workflow](/concepts/workflows). Notifications to be delivered will be forwarded to the channel using the settings that you provide inside our message delivery service, which handles the communication to the underlying provider and the retry logic if a message delivery should fail.

For most providers, you can inspect the delivery logs produced when trying to send a message from under the **Messages** > **Logs** page from within the Knock dashboard.

## Setting additional, per-recipient data for a channel

Some providers may require additional, per-recipient data to send notifications. A good example of this is a push provider like [APNs](/integrations/push/apns), which requires a unique, device-specific token to know how to route a push notification to the recipient.

In Knock, we refer to this concept as "Channel Data" as it represents the data that exists for a recipient on a particular channel.

You can read more about [setting channel data here](/managing-recipients/setting-channel-data). You can also see channel data requirements in the documentation for each provider.

## Frequently asked questions

<AccordionGroup>
  <Accordion
    title="Can I have multiple channels for the same provider?"
    defaultOpen={true}
  >
    There's no restriction on how many different channels you can have,
    including multiple channels for the same provider.
  </Accordion>
</AccordionGroup>


## Commits
Learn about how Knock's commit and promotion model works.
---
title: Commits
description: Learn about how Knock's commit and promotion model works.
tags:
  [
    "branches",
    "env",
    "version control",
    "versions",
    "commit",
    "promote",
    "promotion",
    "revert",
    "rollback",
    "staging",
    "active",
    "inactive",
    "diffs",
    "push",
  ]
section: Concepts
---

To version the changes you make in your [environments](/concepts/environments), Knock uses a commit model. When you make a change to a workflow or a layout in the Knock dashboard, you'll need to commit it to your development environment before those changes will appear in workflows triggered via the API.

After you modify a resource, you'll see a "Save" button that allows you to store those changes. When you're ready to permanently store your updates with version control, they should be committed with the "Commit to development" button that will come into focus after changes have been saved.

**A few things to note:**

- Channel configurations, branding, and variables do not need to be committed, as they live at the account-level. This means that if you make a change to a channel configuration, it will update immediately on notifications sent in that environment.
- Any changes you have saved but not yet committed **will** apply when you're using the test runner. This allows you to test your latest changes before you commit them to your development environment.
- You can work with Knock resources outside of your dashboard if you prefer. We offer both a [Management API](/developer-tools/management-api) and a [command line interface](/developer-tools/knock-cli) for interacting with Knock resources programmatically. The commit model applies to all methods of interacting with Knock resources, whether directly in the dashboard or with the Management API or CLI.

## Visualizing changes between commits

Clicking the "Commit to development" button will show you a view of changes between your current commit and the most recent version of the resource that you're updating. Commit diffs are also available on your full commit log (viewable on the "Commits" page in your dashboard), so you can view the commit history for a resource and know exactly what was changed with each commit.

![Commit diffs in Knocks version control](/images/commit-diff-showcase.gif)

## Promoting commits

Knock is designed to allow large teams to create and manage notifications at scale. That means that
changes must be versioned, tested, and promoted to production environments, so that if there are
any issues they can be rolled back with ease.

Knock uses a model where all changes to the production environment must be **promoted** and cannot be made directly.
Changes must be made in the development environment, then staged and tested before being rolled out (similar to a git-based workflow).

<Callout
  emoji={"🚨"}
  text={
    <>
      <span className="font-bold">Note:</span> There is one exception to the
      commit and promote rule — the active/inactive{" "}
      <a href="/concepts/workflows#workflow-status">status</a> on a workflow
      lives independently from the commit model so that you can immediately
      enable or disable a workflow in any environment without needing to go
      through environment promotion. A workflow's status is environment-specific
      and will only be applied to the current environment.
    </>
  }
/>

To promote a committed change to a higher environment, navigate to the "Commits" page in your Knock dashboard and click on "Unpromoted changes." Here you'll see a list of commits that are ready for promotion. Clicking "View commit" on a given commit will show you a commit diff for that change, and clicking the "Promote to [environment]" button will promote the staged commit to the next-higher environment (whose name is displayed on the button).

**A typical deployment lifecycle in Knock looks like:**

1. Introduce any backend changes to support a new workflow (users and preference properties)
2. Build the workflow in a dev environment in Knock and commit it to that environment
3. Test the workflow
4. When you're ready to go live, promote the workflow to production

## Reverting a commit

If you've made a change in a commit that you want to revert, you can use the "Revert commit" feature to "undo" that change. You can find the revert commit action on the "Commits" page in the dashboard, under the "Unpromoted changes" and "Commit log" tabs.

<Callout emoji={"🚨"}>
  **Note**: you can only revert a commit in the development environment. If you
  need to revert a change to a higher environment, you must first revert it in
  development and then promote the revert commit.
</Callout>

**Reverting a commit will**:

- Create a new commit with a message that indicates the commit reverts a preceding commit
- Wind back the state of the resource to the change that precedes the commit
- Undo any uncommitted changes on the resource

Because the revert will produce a new commit, you can then promote that commit to other environments to make that change live in those environments.


## Environments
Learn about how Knock's isolated environment model works and how it fits into your system development lifecycle.
---
title: Environments
description: Learn about how Knock's isolated environment model works and how it fits into your system development lifecycle.
tags: ["env", "version control", "variables", "promote", "promotion", "staging"]
section: Concepts
---

Knock uses the concept of environments to ensure logical separation of your data between
local, staging, and production environments. This means that recipients and preferences created
in one environment are **never** accessible to another.

The API key you use determines the environment into which you'll be sending data. You can find your environment-specific API keys under the "Developer" section of the Knock dashboard.

## Working with Knock resources across environments

In order to prevent unintended changes to Knock resources (like a [workflow](/concepts/workflows) or [layout](/integrations/email/layouts)) in a production setting, we use a commit model that requires changes to be saved and committed in your Development environment and [promoted](/concepts/commits#promotion-and-rollback) to higher environments.

[Read more about Commits](/concepts/commits)

## Create additional environments

By default your Knock account comes with two environments: Development and Production. If you need an additional environment in Knock to mirror your own development lifecycle (for example, a Staging environment) you can add it on the settings page of the Knock dashboard.

To create a new environment, go to **Settings** > **Environments**. You'll see a button to "Create environment."

When you create an additional environment, it will be inserted between Development and Production. This means all changes will continue to be introduced in your Development environment and will need to be promoted through additional environments until they land in Production. Subsequent new environments will always be added one "level" lower than Production; environments cannot be re-ordered, as this would break the promotion model for previously-promoted changes.

## Environment-based access controls

We recognize the importance of protecting your sensitive data, so we designed Knock from the ground-up with privacy and security in mind.

There are two tools you can use to control access to your data in the Knock dashboard:

- [Roles and permissions.](/manage-your-account/roles-and-permissions) Knock offers granular roles for the different functions your team members may want to carry out in Knock, such as support team members that need to debug issues for customers but shouldn't be making changes to notification logic.
- [Customer data obfuscation.](/manage-your-account/data-obfuscation) You can use our per-environment data obfuscation controls to configure whether you want your team members to be able to view customer data in the Knock dashboard.


## Recipients
A Recipient in Knock represents a person or a non-user entity that receives notifications.
---
title: Recipients
description: A Recipient in Knock represents a person or a non-user entity that receives notifications.
tags:
  [
    "RecipientIdentifier",
    "recipient",
    "user",
    "timezone",
    "time zone",
    "locale",
  ]
section: Concepts
---

A Recipient within Knock is any [User](/concepts/users) or [Object](/concepts/objects) that may wish to receive notifications. Knock persists information about recipients to send those recipients notifications and give a single source of truth for the notifications sent for debugging and logging purposes.

Recipients have:

- **Identifiers.** A string from your system that uniquely represents the recipient.
- **Properties.** Structured and unstructured data for the recipient, including but not limited to the name, email, and phone number.
- **Preferences.** The rules under which the recipient should or should not receive notifications.
- **Channel data.** Channel data send a recipient a notification on a particular channel, such as tokens for sending push notifications to a given channel or access tokens to send notifications to a chat channel like Slack.

## `RecipientIdentifier` definition

A recipient identifier can be one of:

- A string user ID for a previously identified user (`user-1`)
- An object reference dictionary (`{ "collection": "my-collection", "id": "object-1" }`) for a previously identified object
- A dictionary containing a recipient to be [identified inline](/managing-recipients/identifying-recipients#inline-identifying-recipients)

This can be expressed as the following type:

```typescript
type RecipientIdentifier =
  | string
  | { collection: string; id: string }
  | Record<string, any>;
```

## Identifying recipients

For Knock to be able to send notifications to your recipients, you must first identify those recipients to synchronize them with Knock. We call this process "identification", and it can be done ahead of time, or lazily via inline-identification in your workflow triggers. Identifying sets the properties associated with your recipients into Knock, so that you can reference those properties in the notifications you send out.

[Read more about identifying your recipients ->](/managing-recipients/identifying-recipients)

## Custom properties

Recipients in Knock can have any number of custom properties set on them, which you set during the identification process. Some properties, like `email` or `phone_number` are required for notifications to be delivered to the recipient.

## Managing lists of recipients

You can use our [Subscriptions](/concepts/subscriptions) feature to create a Knock-managed list of recipients that should be notified. Subscriptions are useful for modeling pub/sub behavior.

## Recipient timezones

A recipient can have an optional `timezone` property, which should be a [valid tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), like `America/New_York` or `Europe/London`. By default, if no recipient timezone is set `Etc/UTC` will be used however a [default timezone](/manage-your-account/account-timezone) can be specified at the account level under "Settings" which will override this default for all recipients.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is there a limit on the number of recipients I can have in Knock?">
    No, there's no limit on the number of recipients you can have within Knock.
  </Accordion>
  <Accordion title="Why would I need a non-user recipient?">
    We support non-user entities (Objects) receiving notifications in Knock
    because some notifications are delivered to non-user entities. For example,
    a Slack notification that sends to a channel. That notification is not
    delivered to a user but to an entity that connects Slack and your system
    (such as a Project or a Team).
  </Accordion>
  <Accordion title="Is there a limit to the size of the properties I can pass on a recipient to Knock?">
    Currently, there's no limit to the size of the properties you can add to a
    recipient. We reserve the right to impose a limit here in the future,
    however.
  </Accordion>
</AccordionGroup>


## Users
Learn more about Users in Knock and see code examples to get started.
---
title: Users
description: Learn more about Users in Knock and see code examples to get started.
tags: ["recipients", "identify", "actor"]
section: Concepts
---

A [User](/reference#users) represents a person who may need to be notified of some action occurring in your product. A user is a type of recipient within Knock and is the most common type of entity that you may wish to send a notification to.

## Sending user data to Knock

User data must be synchronized to Knock to send the user a notification or to reference that user in a notification. We refer to this process as identifying users.

[Read more about identifying users ->](/managing-recipients/identifying-recipients).

## Guidelines for use

### User identifiers

The identifier for a user is important as it's the unique key that we will use to merge users and determine recipients for a notification. Generally, the best practice here is to use your internal identifier for your users as the `id`.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Please note:</span> The maximum number of
      characters for the identifier is 256, and it cannot contain a "/" or "#".
      You <span className="font-bold">cannot change</span> a user's id once it
      has been set, so we recommend that you use a non-transient `id` like a
      primary key rather than a phone number or email address.
    </>
  }
/>

### Required attributes

The following attributes are required for each user you identify with Knock.

| Property | Description                                                    |
| -------- | -------------------------------------------------------------- |
| id       | An identifier for this user from your system, should be unique |

### Optional attributes

The following attributes are optional, depending on the channel types you decide to use with Knock.

| Property     | Description                                                                                                                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email        | The primary email address for the user (required for email channels)                                                                                                                                                        |
| name         | The full name of the user                                                                                                                                                                                                   |
| avatar       | A URL for the avatar of the user                                                                                                                                                                                            |
| phone_number | The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels)                                                                                                            |
| timezone     | A valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (optional for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients)) |

### Storing user properties

In addition to the system attributes defined on the user schema above, Knock will keep track of any `properties` (key/value pairs) that you send to us. These _traits_ are always merged onto a user and returned to you.

Traits are useful for when you need to perform additional personalization on a user, like denormalizing the current plan they're on so you can use this to determine the portion of a notification they should receive.

You can nest the properties you send as deeply as needed, and Knock will perform a deep merge with these properties on each subsequent upsert. Note that this means that existing properties cannot be explicitly removed, but you can overwrite them with a `null` value.

### The user object

Once sent to Knock, the user object returned to you in the Knock payload looks like this:

```json title="User object"
{
  "id": "user_1234567890",
  "name": "Dummy User",
  "email": "dummy@example.com",
  "updated_at": "2021-03-07T12:00:00.000Z",
  "created_at": null,
  "__typename": "User"
}
```

| Property     | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| id           | The unique user identifier                                         |
| properties\* | Traits sent for the user are merged back onto the main user object |
| created_at   | The created at time (provided by you)                              |
| updated_at   | The last time we updated the user                                  |

\* All properties appear at the top level of the user object.

## Retrieving users

Users can be retrieved from Knock to see the current state of their properties using the `users.get` method.

<MultiLangCodeBlock snippet="users.get" title="Get a user" />

## Deleting users

Users can be deleted from Knock via the `users.delete` method. Deleting a user from Knock will have the following effect:

- The user will no longer be able to be a recipient or an actor in a workflow
- The user will no longer appear in the dashboard under the "Users" list
- Any in-app messages that reference the user will be replaced by a "missing user" marker

<MultiLangCodeBlock snippet="users.delete" title="Delete a user" />

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What do I do if my notification recipients aren't yet users?">
    Commonly you'll want to send notifications to entities in your system that are not currently registered users in your product (think guests or invited users). In these situations, we recommend:

    1. Identifying the user with a unique identifier, such as their email address, or with a prefix (`guest_`) to denote the different type.
    2. Where possible, if the notified user becomes a registered user in your system then using our [merge API](#merging-users) to merge the guest user and the registered user to preserve message sending history.

    It might feel counterintuitive to store registered users and non-registered users under a single collection in your Knock environment, but Knock should always be viewed as a _cache_ of information about users and entities that may need to be notified in your system.

  </Accordion>
  <Accordion title="Are users unique per environment?">
    Yes, they are. Each environment has a separate, isolated set of users. If you need to share users across environments, you must re-identify them in each environment.
  </Accordion>
  <Accordion title="What do I do if I have different types of users?">
    If you want to store and notify different types of users within your Knock environment, we recommend prefixing the id with the type. So if you had two distinct user types, `owners` and `customers` you can pass Knock ids like `customer_123` and `owner_456`.
  </Accordion>
  <Accordion title="How can I send a notification to a non-user entity?">
    If you need to send a notification to an entity in your system you should have a look at modeling those as [Objects](/concepts/objects). Objects can represent **any non-user entity**.
  </Accordion>
  <Accordion title="Why do I see my team members as users in Knock?">
    When you add new team members in the Knock dashboard, we automatically add them as "Users" within your Knock Development environment so you can send them notifications. We do this to help you with testing.
  </Accordion>
  <Accordion title="Can I avoid storing user data in Knock?">
    No, all users who are sent a notification are identified in your Knock environment and are persisted. If you have a use case here that you wish to discuss with us please [get in touch](mailto:support@knock.app).
  </Accordion>
  <Accordion title="How can I update a user's attributes?">
    If you need to edit or update a user's attributes in Knock, you can either use the [identify a user endpoint](https://docs.knock.app/reference#identify-user) or [inline identification](https://docs.knock.app/managing-recipients/identifying-recipients#inline-identifying-recipients) when triggering a workflow.
  </Accordion>
</AccordionGroup>


## Preferences
Learn how the notification preference system works in Knock.
---
title: "Preferences"
description: "Learn how the notification preference system works in Knock."
tags:
  [
    "recipients",
    "conditions",
    "prefs",
    "preferences",
    "users",
    "user preferences",
  ]
section: Concepts
---

[Preferences](/reference#preferences) enable your users to opt-out of the notifications you send using Knock.

## How preferences work

A user has a `PreferenceSet`. A `PreferenceSet` is a JSON object that tells Knock which channels, categories, and/or workflows a user has opted out of receiving.

When Knock runs a workflow for a user, we evaluate their `PreferenceSet`. A message will not send if the user has opted out of receiving it.

With Knock preferences you can power standard preference use cases, such as the topic-channel preferences grid picture below, as well as advanced use cases such as per-workflow preferences, send time preferences, and more.

To learn more about how to build your preference center with Knock, how to set preferences for your users, and advanced concepts like per-tenant preferences, object preferences, and preference conditions, go to our [preferences overview](/preferences/overview).

<Image
  src="/images/what-is-knock/preferences.png"
  alt="An image of a preference set"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

## Learn more

To learn more about how to build your preference center with Knock, how to set preferences for your users, and advanced concepts like per-tenant preferences, object preferences, and preference conditions, go to our [preferences overview](/preferences/overview).


## Objects
Learn the basics of Objects in Knock.
---
title: Objects
description: Learn the basics of Objects in Knock.
tags: ["recipients", "identify"]
section: Concepts
---

An [Object](/reference#objects) 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](#slack-channel-notifications)).
- [Reference mutable data in your notification templates](/designing-workflows/template-editor/referencing-data) (such as when a user edits a comment before a notification is sent).

<Callout
  emoji="🛣"
  text={
    <>
      <span className="font-bold">Knock roadmap alert.</span> We have Objects
      API support for in-app feed notifications on our roadmap.
      <br />
      <br /> If you have a use case for this functionality, please send a note
      to <a href="mailto:support@knock.app">support@knock.app</a> or use the
      feedback button at the top of this page to let us know.
    </>
  }
/>

## 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](/concepts/users#sending-user-data-to-knock). As with users, we support three approaches for managing Knock objects: individual, bulk, and inline.

<AccordionGroup>
  <Accordion title="Set individual objects">
    You can use the set object API to send us data for a single object.

    [API reference →](/reference#set-object)

    <MultiLangCodeBlock snippet="objects.set" title="Set an object in Knock" />

  </Accordion>

  <Accordion title="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 1000 objects at a time.

    [API reference →](/reference#bulk-set-objects)

    <MultiLangCodeBlock
      snippet="objects.bulkSet"
      title="Bulk set objects in Knock"
        />

  </Accordion>

  <Accordion title="Set objects inline">
    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 →](/reference#trigger-workflow-inline-identify)

    <MultiLangCodeBlock
      snippet="workflows.trigger-with-object-identification"
      title="Trigger a workflow with inlined identification data"
        />

  </Accordion>
</AccordionGroup>

## Guidelines for use

### Collection naming

Use plural collection names when 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 deeply merged between upserts, meaning that existing properties (including nested properties) will be updated with the newly provided values. Note that this means that existing properties cannot be explicitly removed, but you can overwrite them with a `null` value.

## Object subscribers

You can use [subscriptions](/concepts/subscriptions) to subscribe [recipients](/concepts/recipients) to objects as subscribers. When an object is passed to a workflow trigger, Knock will automatically fan out and run a workflow for every subscriber on that object.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Nested object hierarchies.</span> One of the
      most powerful things about object subscriptions is that they can contain
      other objects.
      <br />
      <br />
      As an example, a <code>workspace</code> object may have a list of <code>
        projects
      </code> as subscribers, each of which has a list of <code>
        project follower
      </code> subscribers.
      <br />
      <br />
      When you trigger a workflow with that <code>workspace</code> as a
      recipient, Knock will fan out through the hierarchical relationship you've
      created and notify all <code>projects</code> and{" "}
      <code>project followers</code> under that <code>workspace</code>.
    </>
  }
/>

## Referencing object data in templates

You can reference object data in templates using the `object` filter to load object data into a template. You can reference an object by a static identifier, or by a dynamic identifier passed in via data in your workflow trigger.

For example, if we have a `projects` collection that contains an object under the identifier `proj_1`, we can load that object into a template via a static identifier like this:

```liquid title="Referencing an object by a static identifier"
{% assign project = "proj_1" | object: "projects" %}
```

Or, we can load an object by a dynamic identifier. For example, if we have a workflow trigger that contains a `project_id` property, we can load that object into a template like this:

```liquid title="Referencing an object by a dynamic identifier"
{% assign project = data.project_id | object: "projects" %}
```

Once an object is loaded into a template, you can reference any of the properties of that object using the dot notation.

You can read more about referencing data in templates in our [guide on referencing data in templates](/designing-workflows/template-editor/referencing-data).

## 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.

<MultiLangCodeBlock
  snippet="objects.set"
  title="Send project object 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.

<MultiLangCodeBlock
  snippet="objects.setChannelData.slack"
  title="Store Slack connection on object"
/>

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.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-object-as-recipient"
  title="Triggering a workflow with an object as a recipient"
/>

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.


## Subscriptions
Learn how to use subscriptions to notify a list of recipients associated with an object in your data model.
---
title: Subscriptions
description: Learn how to use subscriptions to notify a list of recipients associated with an object in your data model.
tags:
  ["subscriptions", "publish subscribe", "pub/sub", "lists", "alerts", "topics"]
section: Concepts
---

Subscriptions are an extension to [Objects](/concepts/objects) and express the relationship between a [Recipient](/concepts/recipients) (the subscriber) and an Object.

You can use subscriptions for:

- Creating notifications for a large number of recipients (e.g. all users of your product)
- Alerting use cases, where users can opt into and out of an alert
- Publish/subscribe models where you want to fan out to a set of users subscribed to a topic

Any Object within Knock can be subscribed to by one or more recipients, and the entire set of subscribers can be notified by triggering a workflow for the object, without you needing to keep the relationship data within your system of who is subscribed to what.

## How subscriptions work

1. Identify an object in a collection that represents the topic, or entity you wish to subscribe recipients to
2. Subscribe one or more recipients to the object by creating a subscription between the recipient and the object
3. Trigger a workflow for the object

On step #3, Knock will handle the fan out of the workflow trigger **to all recipients that are subscribers**, automatically enqueuing a workflow run for the recipient on your behalf.

## Integrating subscriptions

Note: for all of the examples below you will need to have an [object identified within Knock](/concepts/objects#sending-object-data-to-knock). In our examples below, we create an object under a `project_alerts` collection with an id `project-1`.

[Go to API documentation →](/reference#subscriptions)

### Subscribing recipients to an object

Subscribing a recipient to an object creates an `ObjectSubscription` entity describing the relationship between the `Recipient` and the `Object`.

You can subscribe up to 100 recipients to an object at a time by passing one or more `RecipientIdentifiers`. There is no limit to the number of recipients you can subscribe to an object.

```javascript title="Subscribing multiple recipients to an object"
await knock.objects.addSubscriptions("project_alerts", "project-1", {
  recipients: ["esattler", "dnedry"],
  properties: {
    // Optionally set other properties on the subscription for each recipient
  },
});
```

Similar to workflow triggers, you can inline identify recipients while subscribing them to an object.

```javascript title="Identifying users while subscribing them to an object"
await knock.objects.addSubscriptions("project_alerts", "project-1", {
  recipients: [
    {
      id: "esattler",
      name: "Ellie Sattler",
      email: "esattler@ingen.net",
    },
    {
      id: "dnedry",
      name: "Dennis Nedry",
      email: "dnedry@ingen.net",
    },
  ],
  properties: {
    // Optionally set other properties on the subscription for each recipient
  },
});
```

### Unsubscribing recipients from an object

To remove one or more recipients (up to 100) from an object, you can pass a list of recipient identifiers.

```javascript title="Delete subscriptions for provided recipients"
await knock.objects.deleteSubscriptions("project_alerts", "project-1", {
  recipients: ["esattler", "dnedry"],
});
```

### Triggering a workflow for all subscribers of an object

By default when you trigger a workflow for an object that has subscriptions attached Knock will fan out to all subscribers and enqueue a new workflow run for that recipient, with the information passed into the workflow trigger.

```javascript title="Triggering a workflow for all subscribers of an object"
await knock.workflows.trigger("alert-workflow", {
  recipients: [{ collection: "project_alerts", id: "project-1" }],
  data: {
    // Data to be passed to all workflow runs
  },
});
```

### Retrieving subscriptions for an object

You can retrieve a paginated list of subscriptions for an object, which will return the `recipient` subscribed as well.

```javascript title="Retrieving a paginated list of subscriptions for an object"
const { entries, page_info: pageInfo } = await knock.objects.listSubscriptions(
  "project_alerts",
  "project-1",
  { after: null },
);
```

### Retrieving subscriptions for a user

You can retrieve a paginated list of active subscriptions for a user, which will return the `object` that the user is subscribed to as well.

```javascript title="Retrieving a paginated list of subscriptions for a user"
const { entries, page_info: pageInfo } = await knock.users.getSubscriptions(
  "user-1",
  { after: null },
);
```

## Accessing subscription properties in a workflow run

When triggering a workflow for a recipient from a subscription, the `properties` defined on the subscription are made available for use within the workflow run scope. You can access the properties under the `recipient.subscription` namespace.

As an example, if you have a property `role` under your subscription properties, you can access it as `recipient.subscription.role` in the workflow run scope.

Note: If you're looking to reference the parent object that the recipient is subscribed to, you can side-load the parent object [using the `object` filter in liquid](/designing-workflows/template-editor/referencing-data).

## Modeling nested subscription hierarchies

It's possible to model nested subscription hierarchies by associating child objects as subscribers of a parent object. This allows you to create structures like "organizations" having many "teams" which have many "team members" (users).

```javascript title="Adding child objects as subscribers of a parent object"
await knock.objects.addSubscriptions("organizations", "org-1", {
  recipients: [
    { collection: "teams", id: "team-1", name: "Org 1, Team 1" },
    { collection: "teams", id: "team-2", name: "Org 1, Team 2" },
  ],
});
```

Once you've established a nested hierarchy like the above, it's also possible to notify **all child subscribers** from a parent object. In the example above, that means we could notify all team members of an organization by setting the recipient of the trigger to be the organization.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note:</strong> currently we only support subscriptions at a
      maximum depth of 2, meaning you can model a hierarchy such as{" "}
      <code>{"parent -> child -> user"}</code> but no deeper. If you need to
      support a deeper nesting, please{" "}
      <a href="mailto:support@knock.app">get in touch</a>.
    </>
  }
/>

## Deduplication by default

Knock always deduplicates recipients when executing a notification fan out, including for workflow triggers with subscriptions. Knock will ensure your notification workflow is executed only once for each unique recipient in the following cases:

- When the recipient appears both in the initial trigger and as a subscriber to one of your objects.
- When the recipient appears multiple times within a nested subscription hierarchy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What's the maximum number of subscribers I can have against an object?">
    There's no upper bound in the number of subscribers you can have against a
    recipient, although you can only **manage** 100 recipients on an object at a
    time using our API.
  </Accordion>
  <Accordion title="Can I have nested relationships for my objects?">
    Yes! An object with subscribers _can also_ be subscribed to a parent object,
    allowing you to create nested hierarchies of objects (like a Team has many
    Projects, and each Project has many Members).
  </Accordion>
  <Accordion title="Can I manage subscribers to an object in the dashboard?">
    Right now, you can only **view** the subscribers of an object in the
    dashboard. You can do so under **Objects** > **Subscriptions**.
  </Accordion>
  <Accordion title="Can I set custom properties on a Subscription?">
    Yes, you can pass a set of `properties`, which is a set of unstructured
    key-value pairs that you set any arbitrary data about.
  </Accordion>
  <Accordion title="Can I filter the set of Subscriptions to be notified?">
    Right now the answer is no, but we're interested in hearing about your use
    case here as we're considering adding this functionality in the future.
  </Accordion>
  <Accordion title="Can I still debug workflow runs for the subscribers of an object?">
    Yes, you can. Once you trigger a workflow for an object that has subscribers
    attached, you will see a workflow run for each of the subscribers under the
    "Workflow runs" page.
  </Accordion>
  <Accordion title="Can I notify both the object AND the subscribers of the object?">
    Yes, by default when you trigger a workflow for an object that has
    subscriptions attached Knock will generate a workflow run for the object
    itself AND all of the attached subscribers.
  </Accordion>
  <Accordion title="Can I notify a recipient each time they appear within an object subscription tree?">
    No, currently Knock [deduplicates all recipients](#deduplication-by-default)
    when fanning out to object subscribers. If this is blocking one of your use
    cases or your adoption of Knock, please contact our [support
    team](mailto:support@knock.app).
  </Accordion>
  <Accordion title="Is the object that recipients are subscribed to exposed in the workflow run scope?">
    No, currently we do not expose the object the subscription belongs to under
    the workflow run scope.
  </Accordion>
  <Accordion title="Will the actor included in the workflow trigger receive a notification if they are a subscriber?">
    No, currently the `actor` is **always** excluded from being a recipient in a
    workflow trigger if they are a subscriber to an Object recipient.
  </Accordion>
  <Accordion title="Can I create a schedule for subscribers of an object?">
    No, currently we do not support [creating schedules](/concepts/schedules)
    for subscribers of an object. Each individual subscriber will need to be
    added as a recipient when creating the workflow schedule.
  </Accordion>
  <Accordion title="Can I cancel a workflow run for a specific recipient if they were notified via an object subscription?">
    Yes, you can. [Workflow
    cancellation](/send-notifications/canceling-workflows) requests can be
    scoped to one or more specific recipients. You can target any recipient who
    was notified via an object subscription, even if that recipient was not
    explicitly included in the workflow trigger request.
  </Accordion>
</AccordionGroup>


## Schedules
Learn how to use Schedules to run workflows at set times for your recipients in a recurring or one-off manner.
---
title: Schedules
description: Learn how to use Schedules to run workflows at set times for your recipients in a recurring or one-off manner.
tags:
  [
    "crons",
    "schedules",
    "digest",
    "recurring",
    "weekly",
    "daily",
    "monthly",
    "schedule",
  ]
section: Concepts
---

A schedule allows you to automatically trigger a workflow at a given time for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

Some examples of where you might reach for a schedule:

- A digest notification where your users can select the frequency in which they wish to receive the digest (every day, every week, every month).
- A reminder notification for a specific event or deadline, sent only once at a given date and time.

## How schedules work

1. [Create a workflow](/designing-workflows) that you wish to run in the future.
2. Using the API, [set a repeating schedule](#scheduling-workflows-with-recurring-schedules-for-recipients) or a [non-recurring schedule](#scheduling-workflows-with-one-off-non-recurring-schedules-for-recipients) for one or more recipients for the workflow.

Knock will preemptively schedule workflow runs for the recipient(s) that you've provided, and execute those runs at the scheduled time. At the end of the workflow run (and in case of using a recurring schedule), a future scheduled workflow will be enqueued based on the recipient's next schedule.

## Scheduling workflows with recurring schedules for recipients

To schedule a workflow for a recipient using recurring schedules, you must first have a valid, committed workflow in your environment. We can then set a schedule with `repeats` for one or more recipients (up to 100 at a time).

```typescript
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const schedules = await knock.workflows.createSchedules("park-alert", {
  recipients: ["jhammond", "esattler", "dnedry"],
  repeats: [
    // Repeat daily at 9.30am only on weekdays
    {
      frequency: "daily",
      days: "weekdays",
      hours: 9,
      minutes: 30,
    },
  ],
  ending_at: "2024-01-02T10:00:00Z", // Schedule will stop after this date
  data: { type: "dinosaurs-loose" },
  tenant: "jpark",
});
```

## Scheduling workflows with one-off, non-recurring schedules for recipients

To schedule a workflow for a recipient using a non-recurring schedule, you must also have a valid and committed workflow in your environment. We can then set a schedule with the `scheduled_at` property, specifying the moment when this workflow should be executed.

```typescript
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const schedules = await knock.workflows.createSchedules("park-alert", {
  recipients: ["jhammond", "esattler", "dnedry"],
  scheduled_at: "2023-12-22T17:45:00Z",
  ending_at: "2023-12-31T23:59:59Z", // Schedule will not execute after this time
  data: { type: "dinosaurs-loose" },
  tenant: "jpark",
});
```

### Schedule properties

| Variable       | Type                  | Description                                                                                                                                                                 |
| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipients`   | RecipientIdentifier[] | One or more recipient identifiers, or complete recipients to be upserted.                                                                                                   |
| `workflow`     | string                | The workflow to trigger.                                                                                                                                                    |
| `repeats`      | ScheduleRepeat[]      | A list of one or more repeats (see below). Required if you're creating a recurring schedule.                                                                                |
| `data`         | map                   | Custom data to pass to every workflow trigger.                                                                                                                              |
| `tenant`       | string                | A tenant to pass to the workflow trigger.                                                                                                                                   |
| `actor`        | RecipientIdentifier   | An identifier of an actor, or a complete actor to be upserted.                                                                                                              |
| `scheduled_at` | utc_datetime          | A UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule.          |
| `ending_at`    | utc_datetime          | A UTC datetime in ISO-8601 format that indicates when the schedule should end. Once the current schedule time passes `ending_at`, no further occurrences will be scheduled. |

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Note:</span> when using an Object as a
      recipient for a scheduled workflow, only the object itself will receive
      the notification. Subscribers to that object will not be included. If you
      want to schedule workflows for subscribers of an object, you must add each
      subscriber individually as a recipient when creating the workflow
      schedule.
    </>
  }
/>

### ScheduleRepeat properties

| Variable       | Type                                 | Description                                                                                                                        |
| -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `frequency`    | RepeatFrequency                      | The frequency in which this repeat schedule should run, one of monthly, weekly, daily, or hourly.                                  |
| `interval`     | number (optional)                    | The interval in which the rule repeats. Defaults to 1. Setting to 2 with a `weekly` frequency would mean running every other week. |
| `day_of_month` | number (optional)                    | The exact day of the month that this repeat should run.                                                                            |
| `days`         | DaysOfWeek[], "weekdays", "weekends" | The days of the week that this repeat rule should run. Can provide "weekdays" or "weekends" as a shorthand.                        |
| `hours`        | number (optional)                    | The hour this schedule should run (in the recipient's timezone). Defaults to 00.                                                   |
| `minutes`      | number (optional)                    | The minute this repeat should run (in the recipient's timezone). Defaults to 00.                                                   |

## Modeling repeat behavior

Every recurring schedule accepts one or more repeat rules, which allow you to express complex rules like:

- Every Monday at 9am.
- Every weekday at 10.30am.
- Every other Monday, Tuesday, and Friday at 6pm.
- Every year at midnight.

A schedule repeat has the following type structure:

```typescript
enum DaysOfWeek {
  Mon = "mon",
  Tue = "tue",
  Wed = "wed",
  Thu = "thu",
  Fri = "fri",
  Sat = "sat",
  Sun = "sun",
}

enum RepeatFrequency {
  Monthly = "monthly",
  Weekly = "weekly",
  Daily = "daily",
  Hourly = "hourly",
}

type ScheduleRepeatProperties = {
  frequency: RepeatFrequency;
  interval?: number;
  day_of_month?: number;
  days?: DaysOfWeek[] | "weekdays" | "weekends";
  hours?: number;
  minutes?: number;
};
```

### Example repeat rules

To illustrate how to model a repeat rule, here are some common examples:

**Every Monday at 9am**

```
{
  "frequency": "weekly",
  "days": ["mon"],
  "hours": 9
}
```

**Every weekday at 10.30am**

```
{
  "frequency": "weekly",
  "days": "weekdays",
  "hours": 10,
  "minutes": 30
}
```

**Every other Monday, Tuesday, and Friday at 6pm**

```
{
  "frequency": "weekly",
  "interval": 2,
  "days": ["mon", "tues", "fri"],
  "hours": 18,
  "minutes": 00
}
```

## Updating schedules

Up to 100 recipient schedules can be updated in a single call. Keep in mind that the properties passed in will be applied to all schedules.

```typescript title="Updating schedules"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const schedules = await knock.workflows.updateSchedules({
  schedule_ids: workflowScheduleIds,
  ending_at: "2024-06-01T00:00:00Z", // Update when the schedule should end
  data: { foo: "bar" },
});
```

## Removing schedules

Up to 100 schedules can be deleted at a time, causing any already enqueued schedules to be cancelled for a recipient.

```typescript title="Removing schedules"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const schedules = await knock.workflows.deleteSchedules({
  schedule_ids: workflowScheduleIds,
});
```

## Listing scheduled workflows

Schedules can be listed per recipient (for a user or an object), or for an individual workflow:

```typescript title="Listing schedules for a user"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const { entries: schedules } = await knock.users.getSchedules("sam");
```

<br />

```typescript title="Listing schedules for a specific workflow"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const { entries: schedules } = await knock.workflows.listSchedules(
  "workflow-key",
);
```

Schedules include a `next_occurrence_at` property which computes the **next time that a schedule will be executed**.
Schedules also include a `last_occurrence_at` property which indicates when was the last time the schedule was executed.

## Workflow data in a scheduled workflow run

Workflows in Knock are triggered either via an API call or via a Source event, both of which will pass the `data` associated. In the case of a scheduled workflow, the workflow will be triggered with an empty data payload by default.

There are 2 ways in which to get data into each of your scheduled workflow runs:

1. **Define static data passed to every triggered workflow on a schedule.** We can include an optional `data` payload when we create our schedule. Any workflow runs triggered by that schedule will include the data payload within their workflow run scope.
2. **Fetch data from an HTTP endpoint to use in your workflow.** You can use an [fetch function step](/designing-workflows/fetch-function) to fetch data for a triggered scheduled workflow to "enrich" the data available with information from a remote server (via HTTP).

## Executing schedules in a recipient's timezone

Knock supports a `timezone` property on the recipient that automatically makes a scheduled workflow run timezone aware, meaning you can express recurring schedules like "every monday at 9am in the recipient's timezone." Recipient timezones must be a [valid tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), like `America/New_York`.

[Read more about recipient timezone support](/concepts/recipients#recipient-timezones).

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note</span>: executing schedules in recipient
      timezones is currently only supported by{" "}
      <a href="/designing-workflows/step-conditions">recurring schedules</a>.
    </>
  }
/>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How can I start my repeating schedule at a particular time?">
    You can use the `scheduled_at` attribute to start your schedule at a
    particular time in the future.
  </Accordion>
  <Accordion title="How can my scheduled workflows use dynamic template data?">
    You can use an HTTP fetch step to fetch data in your workflow as the first
    step to execute to fetch dynamic template data used in your workflow.
  </Accordion>
  <Accordion title="How can I set static data per workflow schedule?">
    When scheduling a workflow for one or more recipients, you can optionally
    provide a static set of `data` which will be passed to the invoked workflow.
  </Accordion>
  <Accordion title="Can I cancel a scheduled workflow?">
    At any point before the scheduled workflow is invoked you can unschedule the
    workflow for one or more recipients. If a workflow has already run, then
    [normal workflow cancellation
    rules](/send-notifications/canceling-workflows) take effect.
  </Accordion>
  <Accordion title="Can I still debug a scheduled workflow?">
    You'll see workflow runs that initiated from a scheduled workflow in the
    list of workflow runs. From there you can select the debugger and debug a
    given workflow.
  </Accordion>
  <Accordion title="Can I model exclusion rules in my repeat logic?">
    Currently no, but we'll be looking to add this feature in the near future.
  </Accordion>
  <Accordion title="How does the ending_at parameter work with schedules?">
    The `ending_at` parameter allows you to set an expiration time for both
    recurring and one-off schedules. For recurring schedules, no new occurrences
    will be scheduled after the `ending_at` time is reached. For one-off
    schedules, the schedule will not execute if the `scheduled_at` time is after
    the `ending_at` time. The `ending_at` time must be specified in UTC ISO-8601
    format, for example: "2024-01-02T10:00:00Z".
  </Accordion>
  <Accordion title="Can I change a recurring schedule to be non-recurring?">
    Yes, you can update the schedule to change from recurring to non-recurring
    (or vice versa). This can be done by removing the `repeats` property and
    setting `scheduled_at` to the desired one-time execution time.
  </Accordion>
  <Accordion title="If I update a workflow, how will it affect the workflow version used for previously-scheduled workflow runs?">
    Scheduled workflow runs will always reference the workflow version that is
    current when the scheduled run is executed. Any scheduled workflow runs that
    are not already in flight when you commit your changes will use the updated
    workflow version.
  </Accordion>
</AccordionGroup>


## Tenants
Learn how to use tenants to map your multi-tenant structure to Knock and power per-user, per-tenant notification experiences.
---
title: Tenants
description: Learn how to use tenants to map your multi-tenant structure to Knock and power per-user, per-tenant notification experiences.
tags:
  ["tenant", "tenancy", "saas", "how knock works", "custom brand", "branding"]
section: Concepts
---

Tenants represent segments your users belong to. You might call these "accounts," "organizations," "workspaces," or similar. This is a common pattern in many SaaS applications: users have a single login joined to multiple tenants to represent their membership within each.

You use tenants in Knock to:

- Support a user having a separate notification feed per tenant
- Apply per-tenant branding in emails
- Define per-tenant preference defaults that apply to all users within that tenant
- Apply per-user, per-tenant preferences
- 🔜 Power per-tenant template overrides

## A conceptual model of tenants

A tenant in Knock:

- Is uniquely identified by an `id`, [per-environment](/concepts/variables). In most cases,
  this `id` is the same `uuid` used to identify the tenant in your system
- Can have any number of custom properties
- Can store branding overrides and preference defaults
- Can be managed via the API

<Callout
  emoji="💡"
  text={
    <>
      Behind the scenes, a tenant in Knock is really just another{" "}
      <a href="/concepts/objects">Object</a> in a special-system defined
      collection, <code>$tenants</code>. That means that anything you can do on
      an object you can do on a tenant.
    </>
  }
/>

By default, Knock will create a stub tenant object for all unique tenants that you trigger a workflow run for. You can also use the [tenant APIs](/reference#tenants) to create and manage tenant objects from your system to Knock.

## Associating workflow runs with a tenant

It's important to note that tenants **do not** have a relationship to the
[users](/concepts/users) and [objects](/concepts/objects) you've identified in Knock.
That means Knock does not know _which tenant_ to associate with the set of users
you're triggering a notification for. Instead, you must explicitly tell Knock as
part of a workflow trigger to associate the workflow runs with a tenant.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-tenant"
  title="Trigger a workflow with a tenant"
/>

Tenants have a loose coupling to your users so Knock does not need to know
anything about the roles and permissions model associated with your product. This
means you have less data to synchronize to Knock and reduces the risk of drift
between what's current in your system and what's reflected in Knock. If you need
to model groups or lists of users, you can use our
[subscriptions model](/concepts/subscriptions) to do that.

Once a workflow run has been triggered with a `tenant`, the Knock workflow engine will do the following:

- Find the tenant or create an empty `tenant` object if one does not exist
- Expose that tenant object to the workflow run scope as a `tenant` variable
- Associates all messages produced in the workflow run with the tenant
- Applies any branding overrides to templates rendered
- Applies any preference defaults to the recipient's preference set
- Fetches any recipient-specific tenant preference sets

## Using tenant data in a workflow run

The full tenant object will be exposed, including any custom properties, in the workflow run scope under the `tenant` [namespace](/designing-workflows/template-editor/variables#tenant).

You can then use the tenant in a workflow to:

- Add per-tenant-specific template changes, like custom messages or details.
- Create per-tenant conditions to only trigger steps for particular tenants.

```markdown title="Using tenant data in a notification template"
# Hello from {{ tenant.name }}

This is a message directly from {{ tenant.name }} going to {{ recipient.email }}.
```

## Syncing tenant data to Knock

To get tenant data into Knock, we expose [various tenant-specific API methods](/reference#tenants). These methods make it possible to create or update a tenant, including any custom properties associated and any tenant settings, which include branding overrides and default preference sets.

<MultiLangCodeBlock snippet="tenants.set" title="Create or update a tenant" />

### Required attributes

| Property | Description                              |
| -------- | ---------------------------------------- |
| `id`     | A string to uniquely identify the tenant |

### Optional attributes

| Property   | Description                                           |
| ---------- | ----------------------------------------------------- |
| `name`     | An optional name to associate with the tenant         |
| `*`        | Any custom properties you wish to store on the tenant |
| `settings` | A `TenantSettings` object to apply (see below)        |

### `TenantSettings`

| Property                          | Description                                                                                                |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `branding.primary_color`          | A hex value for the primary color                                                                          |
| `branding.primary_color_contrast` | A hex value for the contrasting color to use with the primary color user                                   |
| `branding.logo_url`               | A fully qualified URL for an image to use as the logo of this tenant                                       |
| `branding.icon_url`               | A fully qualified URL for an image to use as the icon of this tenant                                       |
| `preference_set`                  | A complete `PreferenceSet` to use as a default for all recipients with workflows triggered for this tenant |

## Messages and tenants

When a workflow is triggered with a `tenant` property, all of the
[Messages](/concepts/messages) produced in the workflow run will be tagged with
the `id` of the tenant.

Tagging messages by the tenant makes it possible to query for tenant-specific
messages in both the API and the dashboard. We also expose this behavior for
in-app feed messages, making it possible to expose per-user, per-tenant feeds
([see below for an expanded guide](#scoping-in-app-feeds) on this usecase).

## Working with tenants in the Knock dashboard

Tenant data is also exposed in the Knock dashboard. From the dashboard it's possible to:

- View information about specific tenants, including custom properties set
- View message logs of messages generated that were associated with the tenant
- View workflow run information for all runs associated with the tenant
- View and set custom branding settings
- View default preferences set for a tenant

You can find tenant information under the "Tenants" section in the left-hand menu of the dashboard.

## Guides for using tenants

### Scoping in-app feeds

Multi-tenancy is important in your notification system when handling in-app feeds. Lets look at an example.
Imagine that we have a SaaS application, Collaborato, where our users belong to one or more different
workspaces. When one of our users is active in a current workspace, we want to make sure they only
see notifications that are relevant for that workspace. That is, a user in the "Acme Fish Co." workspace
should only see notifications that are relevant to "Acme Fish Co."

#### Example

To support this use case within Knock, we can pass a `tenant` identifier into our trigger calls. This `tenant` does not have to be configured in any way beforehand, it can simply be a unique identifier you choose to represent this group.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-tenant"
  title="Trigger a workflow with a tenant"
/>

When retrieving our feed to be displayed, we can then scope the feed to only show items relevant
to the tenant:

```jsx title="Client-side feed scoping"
// If you're using our `client-js` SDK:
import Knock from "@knocklabs/client";
const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);

const feedClient = knockClient.feeds.initialize(
  process.env.KNOCK_FEED_CHANNEL_ID,
  {
    // Scope all requests to the current workspace
    tenant: currentWorkspace.id,
  },
);

// Or if you're using the React SDK:
<KnockFeedProvider
  feedId={process.env.KNOCK_FEED_CHANNEL_ID}
  defaultFeedOptions={{ tenant: currentWorkspace.id }}
>
  ...
</KnockFeedProvider>;
```

By providing the `tenant` property here, we're letting Knock know that the notifications produced
in the `trigger` call belong to a particular tenant and when we're showing the feed to our customers we **only** want to see the feed that's related to that tenant.

Under the hood Knock will ensure that the badge counts you receive for the feed will be relevant
only to the active workspace, and that no real-time notifications will be received for any messages
that aren't relevant to the user.

### Custom branding

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Per-tenant
      branding is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

You can use tenants to define default branding settings when sending email notifications that override your account-level brand settings. When you trigger a workflow with a `tenant`, it will use any settings defined on that tenant in place of the account-level brand settings to style your email layout steps.

#### Example

Let’s say you’re a hospitality company and own two boutique hotels, “The Black Lodge” and “The Great Northern.” Both want custom branding for their reservation update emails.

First, we’ll want to add both of these hotels as `Tenants`. Navigate to the “Tenants” tab on the main sidebar of your dashboard and click “Create tenant." There, you’ll add a name and unique ID by which you'll reference the tenant when triggering notifications. You can also upload a logo, an icon, and select primary colors directly from the interface here.

Now that the tenant is set up, when you trigger a workflow with an email step you can pass the ID for one of these tenants. It will override the account branding settings with the settings you configured for your tenant. If you want to send a reservation reminder to the guests of The Black Lodge, you can pass the ID you set for that hotel, `black-lodge`, into the tenant field of the workflow trigger option to override default account settings with those you've created for this tenant.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-branding-tenant"
  title="Send notification with custom branding"
/>

### Per-tenant user preferences and tenant preference defaults

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Per-tenant
      user preferences and tenant preference defaults are only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

Another advanced tenancy use case is managing different sets of preferences for each user-tenant pair. That is, a user may have different preferences configured for "Acme Fish Co." than they do for "Bell's Bagels," two hypothetical workspaces within our example collaboration app, Collaborato.

We also support the ability to set per-tenant defaults, where an admin in a tenant within your product can set the default preferences for all users within that tenant.

You can learn more about how to set per-tenant preferences and tenant preference defaults in [our preferences guide](/preferences/tenant-preferences).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What's the limit on the number of tenants I can sync into Knock?">
    There are no limits associated with tenants.
  </Accordion>
  <Accordion title="Can I use tenants on a non-enterprise plan?">
    Yes, you can still use our APIs to work with tenant data, and trigger workflow runs for specific tenants. However, per-tenant preferences and custom branding are features gated for enterprise plans only.
  </Accordion>
  <Accordion title="How does Knock map my user access permissions onto a tenant?">
    Knock does not know anything about the mapping between your users and your tenant entities, meaning you do not need to map user permissions.
  </Accordion>
  <Accordion title="Can I use a tenant as a recipient in a workflow trigger?">
    Absolutely, you can use a tenant as a `recipient` or `actor` in a workflow trigger by referencing it as an object with the structure `{ collection: "$tenants", id: "tenant-id" }`.
  </Accordion>
  <Accordion title="Can I subscribe recipients to a tenant?">
    Yes, you can subscribe recipients to a tenant by setting the collection of the object to subscribe to as `$tenants` and using the `id` of the tenant as the object id.
  </Accordion>
  <Accordion title="Can I create per-tenant templates?">
    We're currently working on this feature to create per-tenant template overrides at the workflow step level. If you're interested in being an early adopter of this feature, or this is blocking your adoption of Knock, [please get in touch](mailto:support@knock.app?subject=Per-tenant%20templates).
  </Accordion>
  <Accordion title="Can I create per-tenant workflows?">
    While it's technically possible to create per-tenant workflows in Knock, we recommend not doing this where possible and opting to use our step conditions, preferences, and per-tenant templates to provide the customizations you need. The reason is creating and managing per-tenant workflows increases the surface area of the number of notifications you need to support, and more commonly what we've found from working with customers is there are more similarities between per-customer workflows than differences, which can usually be encapsulated in our workflow model.

    If you find that you have different needs here, we'd love to speak with you. Please [get in touch](mailto:support@knock.app) and we can arrange a consultation with a notification support specialist on the Knock team to walk through your use case.

  </Accordion>
  <Accordion title="Can I nest tenants?">
    No, today it's only possible to have a single-level of hierarchy for your tenants. If you need to apply deeper hierarchy to your tenant objects, please [get in touch](mailto:support@knock.app) and we can discuss your use case further.
  </Accordion>
</AccordionGroup>


## Messages
Learn how Knock models per-recipient notifications with Messages.
---
title: Messages
description: Learn how Knock models per-recipient notifications with Messages.
tags: ["messages", "workflows"]
section: Concepts
---

## An overview

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Some data is subject to retention policy enforcement.
      </span>{" "}
      Message log data in the Dashboard and the public API are subject to
      retention policy enforcement. In-app message data and the Feeds API are
      not. See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

A Message in Knock represents a notification delivered to a [User](/concepts/users) or an [Object](/concepts/objects) on a particular channel. This is the core Knock data entity that your recipients will interact with when receiving notifications.

Knock exposes a set of [Message APIs](/reference#messages) via which you can query for notifications and update messages individually or in batches. The Knock [Feeds API](/reference#feeds) is a specialized view of messages delivered to an in-app feed channel.

The Knock dashboard makes available various message metadata to help you debug your notifications. This includes:

- Information about the request that triggered the delivery of the message.
- A preview of the message content as displayed for the recipient.
- Logs of requests between Knock and your channel provider as Knock works to deliver the message to the recipient.
- A timeline of message lifecycle events.

## Statuses

Messages have two types of statuses. These are:

- **Delivery statuses** — The delivery state of a message as reported by your channel provider. Delivery statuses are mutually exclusive and implicitly managed by Knock as part of notification delivery.
- **Engagement statuses** — The way in which the recipient has interacted with the notification. A message can have multiple engagement statuses, and you can manage them yourself via the Knock API.

Knock captures changes in message status as events that can be sent to [outbound webhooks](/developer-tools/outbound-webhooks/overview).

To learn more, see our [message statuses guide](/send-notifications/message-statuses).

## Link and open tracking

Knock provides opt-in, provider agnostic tracking capabilities for your notifications. With link tracking, Knock will capture link-click actions by your recipients as a message event. With open tracking, Knock will embed tracking pixels in email channel messages to help gauge when recipients are opening and reading your email notifications.

To learn more, see the [Knock tracking guide](/send-notifications/tracking).


## Translations
Learn how to use translations to localize your notifications.
---
title: Translations
description: Learn how to use translations to localize your notifications.
tags:
  [
    "translation",
    "translations",
    "translate",
    "locale",
    "localization",
    "l10n",
    "how knock works",
    "language",
    "i18n",
    "internationalization",
  ]
section: Concepts
---

[Translations](/mapi#translations-overview) localize the notifications you send with Knock.

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Translations
      are only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## Get started

To get started, enable translations for your account. Go to “Settings” under your account name in the left sidebar and click “Enable translations”.

Next you'll need to set a default `locale`. Knock uses the default `locale` when it can't find a translation for a given recipient’s `locale`.

Once you've set your default `locale`, you should see a new “Translations” page under “Developers” in the sidebar. This is where you’ll be working with your translations.

## Basic usage

[Translations](/mapi#translations-overview) are JSON objects that contain the text for your messages in various locales. For example, let’s say you have a customer order notification that you want to localize for French and English users.

```json title="en translation"
{
  "OrderReady": "Your order is ready.",
  "OrderDelayed": "Your order is delayed."
}
```

<br />

```json title="fr translation"
{
  "OrderReady": "Votre commande est prête.",
  "OrderDelayed": "Votre commande est retardée."
}
```

Once you have those translations created for the `en` and `fr` locales, you can reference their translation strings in your message templates using the `t` filter:

```json title="Message template editor"
<p> {{ "OrderReady" | t }} </p>
```

Your users must have a `locale` property set for the helper to find translations in their locale, otherwise Knock will use the default locale. You can set a user's `locale` with the [identify endpoint](/reference#identify-user).

## Translation methods: filter vs. tag

There are two methods available to you to translate your message templates: the `t` filter and the `t` tag.

<AccordionGroup>
  <Accordion title="The t filter">
    The `t` filter is used to reference existing translation files. It works best when you have translations that are already created and you want to reference them in your message templates.

    ```json title="Using t filter in a message template"
    {{ "congratulationsMessage" | t: recipientName: recipient.name }}
    ```

    In the example above, the `t` filter finds the recipient's `locale` and looks for the `congratulationsMessage` key in the translation file for that locale. It then replaces the `recipientName` variable with the recipient's name.

  </Accordion>
  <Accordion title="The t tag">
    The `t` tag is used to write templates in their default language and automatically generate translations for additional locales. It is best when you have less technical users authoring templates, and you want to automatically generate translations for their templates behind the scenes.

    ```json title="Using t tag in a message template"
    {% t %}Congratulations, {{ recipient.name }}!{% endt %}
    ```

    In the example above, we author content in our English default language, wrap that content in our `t` tag, and Knock automatically generates translation files for us behind the scenes.

  </Accordion>
</AccordionGroup>

We cover how to use the `t` filter and `t` tag in more detail below.

<SdkCard
  title="Video walkthrough"
  linkUrl="https://www.youtube.com/watch?v=8VAFqj5qqPI"
  icon="youtube"
  languages={["Explore Knock's translation model", "5 min. watch time"]}
  isExternal={true}
/>

## Using the `t` filter

You can use `t` filter to reference your translations from within a message template. The `t` filter also allows you to use variables, other filters, and special pluralization rules.

### Variables and interpolation

You can use variable interpolation in your translations.

```json title="en translation"
{
  "comment": "New comment from {{ actorName }} on your post {{ postName }}.",
  "like": "{{ actorName }} liked your photo {{ photoTitle}}!"
}
```

You can pass variables to the `t` filter:

```json title="Message template editor"
<p> {{ "like" | t: actorName: actor.name, photoTitle: likedPhoto.title }} </p>
```

### Pluralization

Translations support pluralization rules. When you pass the `count` variable to a translation, it looks for pluralization keys in your translation. Those keys are `zero`, `one`, and `other`. You don’t need to reference these in the template. If you pass the `count` variable, it will evaluate it and choose one for you.

```json title="en translation"
{
  "orders": {
    "shipping": {
      "zero": "You have no orders currently being shipped.",
      "one": "You have one order being shipped.",
      "other": "You have {{ count }} orders being shipped."
    }
  }
}
```

To pluralize content in a message template, pass the `count` variable:

```json title="Message template editor"
<p> {{ "orders.shipping" | t: count: count }} </p>
```

- If the count is 0, it will choose `zero`, unless `zero` does not exist and then it will use `other`.
- 1 corresponds to `one`, and everything else will fall under `others`.

### Other filters in combination

You can still use other filters in combination with `t` but you’ll use them **after** you use the `t` filter.

For example, to titlecase a translation:

```json title="Message template editor"
<p> {{ "congratulationsMessage" | t | titlecase }} </p>
```

### Namespaced translations

When you create a translation, you can supply an optional “namespace.” The namespace helps organize translations of the same locale so you can keep similar concepts together. Below you'll see examples of how to reference namespaced translations from your message templates.

Let's start with a translation with a namespace of `shipping`:

```json title="en:shipping translation"
{
  "backordered": "Your order has been backordered so shipping will be delayed.",
  "shipped": "Your order has been shipped.",
  "canceled": "Your shipment has been canceled."
}
```

To access the contents of the `shipping` translation in your message template you’ll reference the namespace before the key followed by a colon (”:”):

```json title="Message template editor"
<p> {{ "shipping:canceled" | t }} </p>
```

This can be helpful if you use the `canceled` key else where in your translations so that there isn’t a collision. For example, if you had a `payments` translation like this:

```json title="en:payments translation"
{
  "success": "Your payment has been processed.",
  "canceled": "Your payment was canceled."
}
```

You would reference it with the `payments` namespace as well:

```json title="Message template editor"
<p> {{ "payments:canceled" | t }} </p>
```

And if you had a translation that wasn’t namespaced, say the `en` translation, you would simply use the key alone. All together in a template, it would look like this:

```json title="Message template editor"
<p> Hello, </p>
<p> {{ "payments:canceled" | t }} </p>
<p> {{ "shipments:canceled" | t }} </p>
<p> {{ "canceled" | t }} </p>
```

### Nested translations

You can create whatever JSON structure you need to hold your translations.

Given the following translation:

```json title="en translation"
{
  "customers": {
    "orders": {
      "beenReceived": "Have you received your order?",
      "survey": "How was your order?"
    },
    "reminder": {
      "paymentInfo": "Remember to update your payment information!"
    }
  }
}
```

You can access the content with dot-syntax like this:

```json title="Message template editor"
<p> {{ "customers.orders.beenReceived" | t }} </p>
```

The same goes for namespaced translations. If the above translation was in a translation named `services` , you would do the following:

```json title="Message template editor"
<p> {{ "services:customers.orders.beenReceived" | t }} </p>
```

## Using the `t` tag

Knock also provides an editor-friendly `t` tag which you can use to write templates in your default language. Translation files for any supported languages will be automatically generated in the background when you commit a workflow.

<Steps>
  <Step title="Write your message templates">
    Wrap content you want to translate in a <code>t</code> tag. Any content between the opening and closing t tags will be used as the content for your account's default locale.

    ```liquid title="Message template"
    <p> {% t %}Have you received your order?{% endt %} </p>
    ```

  </Step>
  <Step title="Commit your workflow">
    After you commit your workflow, Knock will look for changes to your message templates and update a system translation file. Translation keys will be automatically generated based off of the content of the <code>t</code> tag. 
    
    A Knock bot will commit these changes to your account with a message indicating which workflow generated the new translations.

    ```json title="System translation file"
    {
      "Have you received your order?": "Have you received your order?"
    }
    ```

  </Step>
  <Step title="Translate the default content into additional locales">
    You can then translate the default content into additional locales by manually editing your translation files or programmatically updating them using the Knock API and a translation service.
  </Step>
</Steps>

## Translation version control

Translations follow the same version control flow in Knock as workflows and layouts. You create them in Development and then promote them to subsequent environments. You can archive translations that are no longer needed.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Remember:</span> in order to see translation
      updates in your template previews, you'll need to commit them to your
      development environment first.
    </>
  }
/>

## Locale prioritization

When Knock renders a template for a given user and encounters our `t` helper, it runs through the following locale prioritization:

1. Language + region (e.g. `fr-BE`)
2. Language (e.g. `fr`)
3. Default locale (e.g. `en`)

Regional locales take precedence over language locales. If a translation is not found in the user’s locale, Knock will fall back to the default locale.

## Automate localization with our CLI

In addition to working with translations in the Knock dashboard, you can programmatically create and update translations using the [Knock CLI](/developer-tools/knock-cli) or our [Management API](/developer-tools/management-api).

If you manage your own translation files within your application, you can automate the creation and management of Knock translations so that they always reflect the state of the translation files you keep in your application code.

The Knock CLI supports both JSON and the Portable Object (PO) file formats. When using PO files, the Knock CLI will handle converting between the Knock translation format and the PO format.

The Knock CLI can also be used to commit changes and promote them to production, which means you can automate Knock translation management as [part of your CI/CD workflow](/developer-tools/integrating-into-cicd).

### Translation directory structure

When translations are pulled from Knock, they are stored in directories named by their locale codes. Their filename will be their locale code. Any namespaced translations will prepend the namespace to the filename, with `.` used as a separator.

```txt title="Local translation files structure"
translations/
├── en/
│  ├── en.json
│  └── admin.en.json
└── en-GB/
   ├── en-GB.json
   └── tasks.en-GB.json
```

If you're migrating your local translation files into Knock, you can arrange them using the file structure above and then push them into Knock with a single command using [`knock translation push --all`](/cli#translation-push). Each `<locale>.json` or `<namespace>.<locale>.json` file should follow the structure defined [here](/mapi#translations-object).

You can learn more about automating translation management in the [Knock CLI reference](/cli). Feel free to <a href="mailto:support@knock.app">contact us</a> if you have questions.

## Supported locales

Below is a list of the available locales to choose from for your translations. If you need one added, contact us at support@knock.app.

<AccordionGroup>
  <Accordion title="Supported locales">
    <LocaleTable />
  </Accordion>
</AccordionGroup>


## Conditions
Learn how Knock's conditions model provides dynamic control flow to your workflow runs.
---
title: Conditions
description: Learn how Knock's conditions model provides dynamic control flow to your workflow runs.
tags:
  [
    "triggers",
    "conditions",
    "conditionals",
    "steps",
    "channels",
    "workflows",
    "preferences",
    "conditional send",
    "routing",
  ]
section: Concepts
---

Knock uses conditions to model checks that determine variations in your [workflow](/designing-workflows) runs. They provide a powerful way to create more advanced notification logic flows.

You can use conditions in three areas of the Knock model:

1. [**Step conditions**](/designing-workflows/step-conditions) — Used to determine if a single step in one of your workflows should execute during each workflow run. For example, only send an email if the preceding in-app notification has not yet been read or seen.
2. [**Channel conditions**](/integrations/overview#channel-conditions) — Used to determine if any step using the given channel should execute across all workflow runs. For example, only execute your Postmark email channel steps in your production environment.
3. [**Preference conditions**](/preferences/preference-conditions) — Used to determine the complete set of preferences available to the current workflow run. For example, allow a recipient to mute notifications for specific resources in your product.

Each of these three cases share the same underlying data model and UI editor, which we outline in detail here.

## Condition types

Knock's shared conditions model supports the following types of conditions:

- **Data** — Evaluates against a property in the [workflow trigger](/send-notifications/triggering-workflows) data payload.
- **Recipient** — Evaluates against a property on the workflow run [recipient](/concepts/recipients).
- **Actor** — Evaluates against a property on the workflow run [actor](/send-notifications/triggering-workflows/api#attributing-the-action-to-a-user-or-object).
- **Environment variable** — Evaluates against one of your [environment variables](/concepts/variables).
- **Workflow** — Evaluates against a property of the currently executing workflow.
- **Workflow run state** — Evaluates against a property of the current workflow run.
- **Tenant** — Evaluates against a property on the [tenant](/concepts/tenants) associated with the current workflow run.
- **Message status** — Evaluates against the [delivery status](/send-notifications/message-statuses#delivery-status) or [engagement status](/send-notifications/message-statuses#engagement-status) of a message from a previous step in the current workflow run.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">
        Message status conditions are only available when designing step-level
        conditions.
      </span>{" "}
      They are not available for use with channel-level or preference-level
      conditions. You can learn more about how to work with message status
      conditions in our{" "}
      <a href="/designing-workflows/step-conditions">
        guide on step-level conditions
      </a>
      .
    </>
  }
/>

## Modeling conditions

Knock models each condition as a combination of three properties: a `variable`, an `operator`, and an `argument`. This will feel familiar to boolean logic with infix operators in many modern programming languages.

In our [JSON representation of a workflow](/mapi#workflows-object) this will look something like:

```json title="A workflow run condition"
{
  "variable": "run.total_activities",
  "operator": "greater_than",
  "argument": "5"
}
```

We also provide a [conditions editor](#the-conditions-editor) that provides some helpful UX abstractions on top of this model for building conditions in the Knock dashboard.

### Variables

A condition variable is always a string formatted like `"<prefix>.<path>"`. Knock uses the variable `prefix` to determine the condition type and the variable `path` to determine where to look up the data for evaluation.

See the [conditions scope](#conditions-scope) for a list of available prefixes.

### Arguments

Knock uses the condition argument as the expected value in the condition evaluation. Arguments can be either static values or dynamic properties.

#### Static arguments

Static arguments can be any of the following JSON literals:

- Strings (`"foo"`, `"bar"`, `"baz"`)
- Numbers (`1.0`, `2`, `10000`)
- Booleans (`true`, `false`)
- `null`

Plus arrays of any of the above.

#### Dynamic arguments

Dynamic arguments are nearly identical to variables. Knock will expect a string formatted like `"<prefix>.<path>"` and use the information within to resolve a value from some runtime data property.

See the [conditions scope](#conditions-scope) for a list of available prefixes.

### Operators

You can use any of the following operators in condition comparisons:

| Operator                   | Description                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `equal_to`                 | `==`                                                                                  |
| `not_equal_to`             | `!=`                                                                                  |
| `greater_than`             | `>`                                                                                   |
| `greater_than_or_equal_to` | `>=`                                                                                  |
| `less_than`                | `<`                                                                                   |
| `less_than_or_equal_to`    | `<=`                                                                                  |
| `contains`                 | `argument in variable` (works with strings and lists)                                 |
| `contains_all`             | are all `argument` in `variable` (works with single arguments, or lists of arguments) |
| `not_contains`             | `argument not in variable` (works with strings and lists)                             |
| `empty`                    | `variable in ["", null, []]`                                                          |
| `not_empty`                | `variable not in ["", null, []]`                                                      |

Note: the `empty` and `not_empty` operators do not require a companion argument value in the condition, since Knock is checking for the absence of data from the variable path.

### Conditions scope

Knock makes the following available to be used in a condition variable or dynamic argument:

| Property                              | Description                                                                                                                                                                                                                                                                                   |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.<path>`                         | A data condition, where `<path>` is used to select a property from the workflow trigger data payload.                                                                                                                                                                                         |
| `recipient.<prop>`                    | A recipient condition, where `<prop>` is used to select a property on the current recipient. [See full list of properties available](/designing-workflows/template-editor/variables#recipient-user-or-object).                                                                                |
| `actor.<prop>`                        | An actor condition, where `<prop>` is used to select a property on the current actor. [See full list of properties available](/designing-workflows/template-editor/variables#recipient-user-or-object).                                                                                       |
| `vars.<var>`                          | An environment variable condition, where `<var>` is the name of one of your environment variables.                                                                                                                                                                                            |
| `workflow.{id,name,categories}`       | A workflow condition.                                                                                                                                                                                                                                                                         |
| `run.{total_activities,total_actors}` | A workflow run condition.                                                                                                                                                                                                                                                                     |
| `tenant.<prop>`                       | A tenant condition, where `<prop>` is used to select a property on the current tenant. [See full list of properties available](/designing-workflows/template-editor/variables#tenant).                                                                                                        |
| `refs.<ref>.delivery_status`          | A [message status condition](/designing-workflows/step-conditions#message-status-conditions) that evaluates against a message's [delivery status](/send-notifications/message-statuses#delivery-status), where `<ref>` identifies the preceding workflow step that generated the message.     |
| `refs.<ref>.engagement_status`        | A [message status condition](/designing-workflows/step-conditions#message-status-conditions) that evaluates against a message's [engagement status](/send-notifications/message-statuses#engagement-status), where `<ref>` identifies the preceding workflow step that generated the message. |

In cases where data is not found at the path given by the variable, Knock falls back to an empty string as the default value.

### Combining conditions

<Callout
  emoji="📤"
  text={
    <>
      <span className="font-bold">Preference conditions note.</span> The
      following syntax does not apply to preference conditions. See the{" "}
      <a href="/preferences/preference-conditions#frequently-asked-questions">
        preference conditions FAQs
      </a>{" "}
      for more information on combining multiple conditions on a preference.
    </>
  }
/>

You can combine multiple conditions together via either `AND` or `OR` operators.

- `AND` combined conditions require all conditions to be true for the evaluation to pass.

```json title="JSON representation of AND combined conditions"
"conditions": {
  // the AND operator is represented by the "all" key
  "all": [
    {
      "argument": "true",
      "operator": "equal_to",
      "variable": "recipient.is_active"
    },
    {
      "argument": "true",
      "operator": "equal_to",
      "variable": "actor.is_active"
    }
  ]
}
```

- `OR` combined conditions require at least one condition to be true for the evaluation to pass.

```json title="JSON representation of OR combined conditions"
"conditions": {
  // the OR operator is represented by the "any" key
  "any": [
    {
      "argument": "true",
      "operator": "equal_to",
      "variable": "recipient.is_active"
    },
    {
      "argument": "true",
      "operator": "equal_to",
      "variable": "actor.is_active"
    }
  ]
}
```

- You may also use a combination of `AND` and `OR` operators to create more complex conditions.

```json title="JSON representation of OR plus AND combined conditions"
"conditions": {
  "any": [
    {
      "all": [
        {
          "argument": "true",
          "operator": "equal_to",
          "variable": "recipient.is_active"
        },
        {
          "argument": "true",
          "operator": "equal_to",
          "variable": "actor.is_active"
        }
      ]
    },
    {
      "all": [
        {
          "argument": "true",
          "operator": "equal_to",
          "variable": "data.force_delivery"
        }
      ]
    }
  ]
}
```

## The conditions editor

The Knock Dashboard ships with a conditions editor that provides helpful abstractions on top of this data model. Rather than needing to remember how to format variables or name operators, Knock makes the appropriate options available to you.

When creating or modifying a condition, you'll see:

- A dropdown to select the condition type. Knock will use this option to determine the variable `<prefix>` value.
- An input or dropdown to provide the variable data path.
- A dropdown to select the operator.
- An input or dropdown to provide the argument data path.

<figure>
  <Image
    src="/images/notifications/conditions-editor-example.png"
    width={500}
    height={522}
    className="rounded-md mx-auto border border-gray-200"
    alt="Working with the conditions editor to build a recipient data condition."
  />
  <figcaption>
    Working with the conditions editor to build a recipient data condition.
  </figcaption>
</figure>

You can also use the conditions editor to combine multiple conditions together via either `AND` or `OR` operators.

<figure>
  <Image
    src="/images/notifications/conditions-groups-example.png"
    width={500}
    height={418}
    className="rounded-md mx-auto border border-gray-200"
    alt="Managing condition groups in the conditions editor."
  />
  <figcaption>Managing condition groups in the conditions editor.</figcaption>
</figure>

The condition editor is available for use in the [workflow step editor](/designing-workflows#the-workflow-canvas) and the [channel environment settings editor](/integrations/overview#per-environment-configurations).

## Debugging conditions

Knock executes any step, channel, and preference conditions for each step within a workflow run. As part of execution, Knock captures detailed information about each condition evaluation for use in the [workflow debugger](/send-notifications/debugging-workflows).

### Debugging step and channel conditions

Knock will display step and channel conditions evaluation results together in the step detail panel in the debugger. The overall evaluation result will show whether the step was skipped. For each individual condition within the set, Knock will show either:

1. **The condition evaluation result.** This will include any dynamically resolved variable and argument data captured at workflow run time.
2. **A "not evaluated" state.** This will occur when a preceding condition or group has determined the result, meaning subsequent conditions did not require full evaluation.

<figure>
  <Image
    src="/images/notifications/step-channel-conditions-debugger.png"
    width={2526}
    height={1622}
    className="rounded-md mx-auto border border-gray-200"
    alt="Debugging step and channel conditions."
  />
  <figcaption>Debugging step and channel conditions.</figcaption>
</figure>

### Debugging preference conditions

Knock will display any preference conditions evaluations just below the step and channel conditions results. Knock will group each condition evaluation by location within the resolved preference set. The overall evaluation result will show whether the recipient opted-out for the given workflow, category, or channel type.

<figure>
  <Image
    src="/images/notifications/preference-conditions-debugger.png"
    width={2560}
    height={1578}
    className="rounded-md mx-auto border border-gray-200"
    alt="Debugging preference conditions."
  />
  <figcaption>Debugging preference conditions.</figcaption>
</figure>


## Variables
Learn more about using shared Variables in Knock.
---
title: "Variables"
description: "Learn more about using shared Variables in Knock."
tags: ["vars", "variables", "env vars", "secrets", "constants"]
section: Concepts
---

Variables within Knock let you set shared constants or secrets that you can use in all of the workflows and templates under your account. Variables can be overridden at the environment level to set per environment constants.

## Setting variables

You can create account-wide variables under **Settings** > **Variables**. Each variable has a `key` and a `value`. The key is how you'll reference the variable in your templates, conditions, and preference conditions when building your workflows.

## Setting secret variables

By default, any variables you set are created as public. Public variables are exposed via the [user feed endpoint](/reference#get-feed) and are always visible within the dashboard by all team members. If you're working with variables that should not be exposed you can create them as secret variables by toggling the "Make variable secret" slider when creating a variable.

Secret variables are _never_ revealed in the dashboard (all values are obfuscated) and are _never_ exposed via the API.

## Accessing variables

Variables are available to be accessed under the `vars` namespace within your templates, step conditions, and preference conditions. For instance, if you set a variable with the key `base_url` you can access that variable under `vars.base_url`.

## Overriding variables per-environment

You can optionally set environment-specific values for your variables. To do so, go to the **Settings** > **Variables** section of the dashboard, click the three dots for a specific variable to select "Edit variable," and set the value for the environment you wish to override.

## Setting JSON in variables

Your variables can optionally contain JSON, which will be parsed when a variable is executed. For instance, if you want to set a dynamic batch window for each environment you can set a per-environment variable to contain `{ "unit": "seconds", "value": 30 }`.

Please note: variables will _always_ be parsed as JSON first, before falling back to being processed as a string.


## Audiences (Beta)
Learn how to use Audiences to power your lifecycle marketing use cases.
---
title: Audiences
description: Learn how to use Audiences to power your lifecycle marketing use cases.
tags: []
section: Concepts
---

<Callout
  emoji="🚧"
  text={
    <>
      Audiences is currently in beta. If you'd like early access, or this is
      blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Audiences beta access">
        get in touch
      </a>
      .
    </>
  }
/>

An Audience is a user segment that you can notify. You can bring audiences into Knock programmatically with our API or a supported reverse-ETL source.

Once you start creating audiences in Knock, you can use them to:

- trigger workflows for lifecycle messaging (such as new user signups) and transactional messaging (such as payment method updates)
- orchestrate branch and conditional logic within your workflows using audience membership (e.g. if a user is in a `paid users` audience, opt them out of the workflow)

## Creating an audience

Navigate to the **Audiences** section on the Knock dashboard’s sidebar, then click “Create Audience” in the top right corner.

### Using audiences across environments

When you create an audience, its key instantly exists across all environments. Any users added to an audience are scoped to a specific environment. Audiences do not follow Knock version control and do not need to be committed or promoted to environments.{" "}<a href="/concepts/environments">Learn more about environments.</a>

<Image
  src="/images/concepts/audiences/workflow-editor-audience-selector.png"
  height={926}
  width={470}
  alt="Audience selector in the workflow editor"
  className="rounded-md mx-auto border border-gray-200"
/>

## Using audiences with workflows

### Triggering workflows

Workflows can be configured to trigger for every new member added to an audience.

Create or open the workflow you’d like to trigger for your audience, then open the workflow editor. Click on the “Trigger” step, then click “Edit trigger type” in the top right corner. Click “Audience“ and then select the audience you’d like this workflow to trigger from.

<Image
  src="/images/concepts/audiences/audience-trigger-type-config.png"
  height={1846}
  width={1330}
  alt="Audience trigger type config in the workflow editor"
  className="rounded-md border border-gray-200"
/>

Commit your workflow to development, and when you’re ready promote it to production. At this point, every time a user is added to the selected audience a workflow will be triggered with that user as a recipient.

<Callout
  emoji="💡"
  text={
    <>
      <b>Remember: audiences are environment scoped.</b> This means the workflow
      will run in the environment where the user was added to the audience. If
      you use a production API key to add users to an audience in production,
      your workflow will trigger in the production environment.{" "}
      <a href="/concepts/environments">Learn more about environments.</a>
    </>
  }
/>

### Audience conditions

Audience membership can be checked in [branch](/designing-workflows/branch-function#adding-conditions-to-branches) and [step conditions](/designing-workflows/step-conditions). Create a condition, then select “Audience membership” as the type. When the condition is evaluated during workflow execution it will check if the recipient is a member of the selected audience.

<Image
  src="/images/concepts/audiences/condition-config.png"
  alt="Audience condition type config in the workflow editor"
  width={500}
  height={334}
  className="rounded-md mx-auto border border-gray-200"
/>

## Populating an audience

Before populating your audience ensure that your user data has been [identified in Knock](/managing-recipients/identifying-recipients) and that you’ve configured and promoted any workflows you want to trigger with the Audience.

### Supported reverse ETL vendors

Audiences can easily be synced from Hightouch Models and Census Segments by configuring Knock as a sync destination. Please reach out to support@knock.app for beta access to our rETL integrations with Hightouch and Census.

### Audiences API

The Knock API can be used to sync audiences from any data warehouse or reverse ETL system. Create the audience in the Knock dashboard, then use the add and remove API operations to power your sync.

The API is designed for batch processing and accepts payloads of up to 1,000 members at a time. For more information see the [audiences API docs](/reference#audiences).

## Using audiences with tenants

When adding users to an audience you can optionally include a tenant ID to power per-user, per-tenant workflows. A user can exist in an audience with multiple distinct tenants.

<Image
  src="/images/concepts/audiences/audience-member-with-multiple-tenant-ids.png"
  alt="An audience member with multiple distinct tenant ids"
  width={1710}
  height={550}
  className="rounded-md border border-gray-200"
/>

When a workflow triggers from an audience entry event, the tenant ID provided for the member will be passed along to the workflow trigger. If no tenant ID is provided in the API request, the workflow will run with no tenant data. If the same user is added with multiple distinct tenants, the workflow will trigger each time by default. To configure this behavior use [trigger frequency](/send-notifications/triggering-workflows#controlling-workflow-trigger-frequency) controls.

Tenancy is also taken into account when checking audience membership. For a recipient to be considered a member of an audience during workflow execution, the tenant ID provided with the trigger data must match the user’s audience membership record. If no tenant ID was provided with the trigger, the user must have been added to the audience with no tenant ID.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens if my audience contains a 'missing user' who I subsequently identify to Knock?">
    If you add a user to an Audience who has not yet been identified to Knock, they will be indicated as a "missing user" in the audience. If you subsequently identify a user with the missing `user_id`, they will be a member of the audience and no longer "missing."

    However, Knock will not retroactively trigger any audience-entry triggered workflows for users that are identified after being added to the audience.

  </Accordion>
</AccordionGroup>



# Designing workflows
Learn how to design notifications using Knock's workflow builder, then explore advanced features such as batching, delays, and more.

## Overview
Learn more about how to design and create powerful cross-channel notification workflows in Knock.
---
title: Designing workflows
description: Learn more about how to design and create powerful cross-channel notification workflows in Knock.
tags: ["steps", "workflows", "functions"]
section: Designing workflows
---

The Knock workflow builder enables you to craft notification workflows that combine functions, channels, and conditional logic to determine which of your users to notify across which channels when a given event takes place in your product.

## How the Knock notification engine works

As you start to dig into workflows, it's helpful to understand the basics of what happens in Knock when you [trigger a workflow](/send-notifications/triggering-workflows).

When Knock receives a workflow trigger (like the one below) for one of your workflows, it will produce a **workflow run** for **each recipient** you send in your workflow trigger.

```js title="A workflow trigger for three recipients"
await knock.workflows.trigger("comment-created", {
  // The user who performed the action (optional)
  actor: "user_0",
  // The list of recipients
  recipients: ["user_1", "user_2", "user_3"],
  // Data to be passed to the template
  data: {
    page_name: "Marketing brief",
    comment_body: "Hey team — can we take another look at this?",
  },
});
```

In the example above we've included three recipients, so our workflow trigger will produce three separate workflow runs.

## The workflow canvas

All Knock workflows consist of three basic parts:

- A **trigger step** that starts the workflow
- **Channel steps** that send notifications to your configured channels
- **Function steps** that control the flow of the workflow and produce state for use in templates

### The trigger step

Every workflow starts with a trigger step. When you want to run a workflow, you send a trigger call to the Knock API with an `actor`, a list of `recipients`, and a `data` payload with any information you want to use in the notification templates of the workflow. (More on this in [triggering workflows](/send-notifications/triggering-workflows).) When the workflow is triggered, it creates a workflow run for each of the `recipients` passed in the trigger call.

A trigger step can optionally have [conditions](/designing-workflows/step-conditions), which determine if the workflow should execute. When the conditions on the trigger step are not met, the workflow will terminate.

### Channel steps

A channel step sends a notification to a recipient. When the workflow engine reaches a channel step, it looks for relevant channel data on the recipient. As an example, an email channel step will look for the `email` property on the recipient. If no relevant channel data for that recipient is found, the step is skipped. If channel data is found, then the step will send a notification.

Each channel has a notification template (designed by you in the Knock dashboard) which inserts the `data` from your trigger call into a [styled template](/send-notifications/designing-workflows/template-editor) for that step's given channel.

You can add any of the major [channel types supported by Knock](/integrations/overview#supported-channel-providers) into your workflow. By default, we show all of our supported channel types, but you'll need to configure a provider with each channel before you can actually use them in a workflow. For more information on how to configure channels in your Knock account, see our [integration guides](/integrations/overview).

### Function steps

A function is a step in a workflow that does something to the data being passed in your trigger call. You can use functions by entering the workflow builder and adding function steps onto the canvas.

We currently support the following functions:

- [Batch](/send-notifications/designing-workflows/batch-function) (aggregate trigger calls that have the same value for a specified batch key)
- [Branch](/send-notifications/designing-workflows/branch-function) (evaluate conditions to determine which path a workflow should take)
- [Delay](/send-notifications/designing-workflows/delay-function) (wait an amount of time before proceeding to the next workflow step)
- [Fetch](/send-notifications/designing-workflows/fetch-function) (execute an HTTP request to fetch additional data for a workflow)
- [Throttle](/send-notifications/designing-workflows/throttle-function) (limits the number of executions of the workflow for the recipient over a window of time)
- [Trigger workflow](/send-notifications/designing-workflows/trigger-workflow-function) (execute a nested workflow with trigger data derived from parent workflow data and environment variables)

## Step conditions

Each workflow step can have one or more conditions that determine, at workflow execution time, if the step should execute. Conditions are one way you can add control flow logic to your notification workflows.

[Read more about step conditions](/send-notifications/designing-workflows/step-conditions).


## Delay function
Learn more about the delay workflow function within Knock's notification engine.
---
title: Delay function
description: Learn more about the delay workflow function within Knock's notification engine.
tags: ["steps", "delays", "wait", "functions"]
section: Designing workflows
---

A delay function does just what it sounds like: it delays the execution of the workflow for some amount of time, then proceeds to the next step. There are three types of delays we support in Knock today: "wait for fixed interval", "wait for a dynamic period", and "wait until a relative timestamp."

## Wait for a fixed interval

The "wait for fixed interval" delay type waits for an interval of time (provided by you in the workflow editor) and then proceeds to the next step.

Fixed interval delay functions are helpful for the following use cases:

- Check to see if a user's seen or read an in-app message before sending an email
- Remind a user about a pending invite they haven't accepted

## Wait for a dynamic period

You can also set the length of your delay dynamically using a variable. You can use any of the data, recipient, actor, or environment variables associated with the workflow run to set your duration.

When specifying a dynamic delay period you must provide one of the following:

- An [ISO-8601 timestamp](https://en.wikipedia.org/wiki/ISO_8601) (e.g. `2022-05-04T20:34:07Z`) which must be a datetime in the future
- A duration unit (e.g `{ "unit": "seconds", "value": 30 }`)
- A window rule (e.g `{ "frequency": "daily", "hours": 9, "minutes": 30 }`)

A dynamic delay must be available to be resolved via the `key` you specify on the given schema, meaning that if you specify a key of `delayUntil` in your `data` schema, your workflow trigger data must contain either an ISO-8601 timestamp, a valid duration unit, or a valid window rule.

When the key specified is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the delay will be **skipped**.

<AccordionGroup>
  <Accordion title="Using a fixed timestamp">
    Timestamp-based delays are helpful for reminders about resources in your product that need to be completed or addressed by a specific point in time. As an example, if a user has a task that's due three days from now and you want to remind them 24 hours before it's due, you can set a timestamp delay for the task's due date minus 24 hours.

    #### An example timestamp

    ```json title="Setting a delay until timestamp"
    {
      "delayUntil": "2024-01-05T14:00:00Z"
    }
    ```

    You can then reference that in your delay step settings as `data.delayUntil`.

  </Accordion>
  <Accordion title="Using durations">
    A duration will take the current time that the delay step is executing and add the duration to it to produce the delay until time. A duration object is an entity that you can set on recipients, tenants, environment variables, or in your data payload and reference on your delay step.

    #### The duration schema

    ```typescript title="A relative duration"
    type Duration = {
      unit: "seconds" | "minutes" | "hours" | "days" | "weeks";
      value: number;
    };
    ```

    #### An example duration

    Let's say you want to express a duration that delays for 15 minutes, here's how you structure that:

    ```json title="Setting a duration"
    {
      "delayDuration": {
        "unit": "minutes",
        "value": 15
      }
    }
    ```

    You then reference that as `data.delayDuration` in the delay step configuration.

  </Accordion>
  <Accordion title="Using window rules">
    A window rule determines a dynamic interval for when the delay should close. It allows you to express rules like "delay until Monday at 9am".

    The window rule will always be evaluated in the [recipient's timezone](/concepts/recipients#recipient-timezones) (when set) and will fall back to the account default timezone, or "Etc/UTC".

    #### The window rule schema

    ```typescript title="A window rule"
    type WindowRule = {
      frequency: "hourly" | "daily" | "weekly" | "monthly",
      // The specific days the rule is valid on
      days?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun"> | "weekdays" | "weekends",
      // The hour which the rule should evaluate (defaults to 0)
      hours?: number,
      // The minute at which the rule should evaluate (default to 0)
      minutes?: number,
      // What day of the month should this rule execute (useful when monthly)
      day_of_month?: number,
      // How often should this rule repeat? Defaults to 1
      interval?: number
    };
    ```

    #### Example window rule

    Let's say you want to express setting a window rule for delaying until Monday at 9am, here's how you might structure that on your recipient:

    ```json title="Recipient delay window"
    {
      "delayUntil": {
        "frequency": "weekly",
        "days": ["mon"],
        "hours": 9
      }
    }
    ```

    Now you can set the delay window key to `recipient.delayUntil` to reference this window rule.

  </Accordion>
</AccordionGroup>

## Wait until a relative timestamp

You can use our relative delay to wait some time before or after a timestamp that you provide in your workflow payload. This computes a delay time for a fixed interval relative to a dynamic timestamp.

Relative delay functions are helpful for various scenarios, including:

- Appointment reminders: send a notification one day before an appointment time
- Follow-up reminders: send a follow-up message two hours after an event

When configuring a relative delay, you'll specify:

- A fixed delay interval (provided by you in the workflow editor)
- Whether the delay should occur before or after the dynamic timestamp
- The `key` for the dynamic timestamp (which can come from your trigger data, recipient data, or other sources)

As in the dynamic delay section above, the key specified must be available to be resolved. If the key is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the delay will be skipped.

## Using workflow cancellation with delays

In cases where you're waiting to see if a user will complete an action before sending a notification, you can use our [workflow cancellation API](/send-notifications/canceling-workflows) to ensure a user doesn't receive an unnecessary reminder.

If the user completes the action you were going to remind them about, cancel the workflow to keep any additional notifications from being sent.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I set per-environment delay periods?">
    Often when you're testing your Knock workflows, you'll want your delay durations to be shorter in non-production environments to aid with testing. To set per-environment delay duration you can:

    - Create a new variable under **Settings** > **Variables** with a relative duration as JSON (`{ "unit": "seconds", "value": 30 }`) and a name of `delayDuration`. You can set per-environment values to specify a shorter or longer window as needed
    - Set your delay duration to "Wait until a dynamic interval"
    - Specify that your delay duration will come from an environment variable
    - Set the key to `delayDuration`, which will resolve the delay duration from the variable you created

  </Accordion>
  <Accordion title="How can I cancel an open delay?">
    You can use the [workflow cancellation API](/send-notifications/canceling-workflows) to cancel a delayed workflow. You must use a unique cancellation key to cancel a previously triggered workflow run.
  </Accordion>
  <Accordion title="How long can a workflow be delayed?">
    A workflow can be delayed for a maximum of 365 days (1 year).
  </Accordion>
  <Accordion title="What are the guarantees around delayed workflows?">
    Knock will ensure that your delayed workflow run will execute within ~1 - 5s of the delayed time.
  </Accordion>
  <Accordion title="How can I see delayed workflow runs?">
    We currently don't have a way to view all delayed workflow runs with pending messages. If this is a feature you need, please reach out as we'd love to hear your use case.
  </Accordion>
  <Accordion title="What happens to paused workflow runs when I update the underlying workflow?">
    Workflow recipient runs will always reference the workflow version that was current when the run was triggered, so your changes will not be reflected in workflow runs that are already in flight. If you need to stop a delayed workflow run because you've updated your workflow, you can use the [workflow cancellation API](/send-notifications/canceling-workflows).
  </Accordion>
</AccordionGroup>


## Batch function
Learn more about the batch workflow function within Knock's notification engine.
---
title: Batch function
description: Learn more about the batch workflow function within Knock's notification engine.
tags: ["steps", "batch", "batched messages", "batching", "digests", "functions"]
section: Designing workflows
---

A batch function collects notifications that have to do with the same subject, so you can send fewer notifications to your users.

Batch functions are helpful when a recipient needs to be notified about a lot of activity happening at once, but doesn't need a notification for every single activity within the batch.
Commenting is a common use case. If a user leaves ten comments in a page in fifteen minutes, you don't want to send the user ten separate notifications. You want to send them one notification about the ten comments they just received.

## How batching works

Here's a step-by-step breakdown of how a batch function works:

- When a given per-recipient workflow run hits a batch step, the batch function will stay open for an interval of time which you define (the [batch window](#setting-the-batch-window)).
- While that interval is open, the batch function aggregates any additional incoming triggers **for that recipient**. If a [batch key](#selecting-a-batch-key) is provided in your batch step, the incoming triggers **for that recipient** will be grouped into **separate batches based on batch key.**
- When the batch window interval closes, the workflow continues to the next step, with the data collected in the batch available in the workflow run scope. You can read more in the ["using batch variables" section](#using-batch-variables) of this guide.

<Callout
  emoji="🌠"
  text={
    <>
      By default the batch will only return the first (or last) 10 items to be
      rendered in your template. This limit can be configured on our Enterprise
      Plan (up to 100 items). The batch can, however, accumulate{" "}
      <strong>any number of items</strong> over the window that it's open.
    </>
  }
/>

## Selecting a batch key

A batch function always batches incoming notifications **per recipient**. If you do not provide a batch key, your batch function will just batch per recipient. If you do provide a batch key, your batch function will batch by recipient and then by your batch key. A batch key resolves to a value in your `data` payload by which to group incoming notifications.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">A quick tip.</span> Here's a helpful way to
      think about batching. By default the batch function batches on a key of{" "}
      <code>recipient_id</code>. When a batch key is provided, it batches on a
      key of <code>concat(recipient_id, batch_key)</code>.
    </>
  }
/>

As an example, in a document editing app where a recipient is receiving notifications about activity across different pages, you can provide a batch key of `page_id` and the user will receive different batch notifications about each page that was included in the batch.

<figure>
  <Image
    src="/images/functions/functions_batch_page.png"
    alt="Using the batch function to batch new comment notifications by page."
    width={1710}
    height={550}
    className="rounded-md mx-auto border border-gray-200"
  />
  <figcaption>
    Using the batch function to batch new comment notifications by page.
  </figcaption>
</figure>

Here's a detailed walkthrough of how this example might work in practice:

- You have a `new-comment` workflow that includes a batch step.
- You send six trigger calls to that workflow: three about `page A` and three about `page B`. The trigger calls are all for the same recipient Elmo.
- If your batch step does not have a batch key, Elmo will receive a batched notification about six activities.
- If your batch step includes a batch key of `page_id`, Elmo will receive two notifications: one for the three activities about `page A` and one for the three activities about `page B`.

## Setting the batch window

The batch window determines the length of time that the batch will be open, with the window opening from the **first** time the batch is triggered.

### Set a fixed batch window

You can set a fixed duration batch window using the "Batch for a fixed window" option in the batch step. The window accepts a relative duration, which can be specified in seconds, minutes, hours, or days.

The batch is opened when it is first triggered for a given recipient. The batch is closed after the fixed duration of time has elapsed.

### Set a dynamic batch window using a variable

You can also set the length of your batch windows dynamically using a variable. You can use any of the data, recipient, actor, or environment variables associated with the workflow run to retrieve your dynamic batch window.

When specifying a dynamic batch window you must provide one of the following:

- An [ISO-8601 timestamp](https://en.wikipedia.org/wiki/ISO_8601) (e.g. `2022-05-04T20:34:07Z`) which must be a datetime in the future
- A relative duration (e.g `{ "unit": "seconds", "value": 30 }`)
- A window rule (e.g `{ "frequency": "daily", "hours": 9, "minutes": 30 }`)

A dynamic window must be available to be resolved via the `key` you specify on the given schema, meaning that if you specify a key of `batchWindow` in your `data` schema, your workflow trigger data must contain either an ISO-8601 timestamp, a valid duration unit, or a valid window rule.

When the key specified is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the batch will be **skipped**.

<AccordionGroup>
  <Accordion title="Using a fixed timestamp">
    A fixed timestamp will tell Knock to close the batch window at the exact date time you provide. It must be a valid ISO-8601 timestamp in the future.

    #### An example timestamp

    ```json title="Setting a batch until timestamp"
    {
      "batchUntil": "2024-01-05T14:00:00Z"
    }
    ```

    You can then reference that in your batch step settings as `data.batchUntil`.

  </Accordion>
  <Accordion title="Using durations">
    A duration will take the current time that the batch step is executing and add the duration to it to produce the batch window closing time. A duration object is an entity that you can set on recipients, tenants, environment variables, or in your data payload and reference on your batch window.

    #### The duration schema

    ```typescript title="A relative duration"
    type Duration = {
      unit: "seconds" | "minutes" | "hours" | "days" | "weeks";
      value: number;
    };
    ```

    #### An example duration

    Let's say you want to express a duration that will always close a batch window 1 day after the batch is started, here's how you structure that:

    ```json title="Setting a duration"
    {
      "batchDuration": {
        "unit": "days",
        "value": 1
      }
    }
    ```

    You then reference that as `data.batchDuration` in the batch step configuration.

  </Accordion>
  <Accordion title="Using window rules">
    A window rule determines when the next occurrence of the batch window should be executed. It allows you to express rules like "batch until Monday at 9am", or "keep the batch window open for 2 weeks until the next Friday."

    The window rule will always be evaluated in the [recipient's timezone](/concepts/recipients#recipient-timezones) (when set) and will fall back to the account default timezone, or "Etc/UTC".

    #### The window rule schema

    ```typescript title="A window rule"
    type WindowRule = {
      frequency: "hourly" | "daily" | "weekly" | "monthly",
      // The specific days the rule is valid on
      days?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun"> | "weekdays" | "weekends",
      // The hour which the rule should evaluate (defaults to 0)
      hours?: number,
      // The minute at which the rule should evaluate (default to 0)
      minutes?: number,
      // What day of the month should this rule execute (useful when monthly)
      day_of_month?: number,
      // How often should this rule repeat? Defaults to 1
      interval?: number
    };
    ```

    #### Example window rule

    Let's say you want to express setting a window rule for batching weekly on a Monday at 9am, here's how you might structure that on your recipient:

    ```json title="Recipient batch window"
    {
      "batchWindow": {
        "frequency": "weekly",
        "days": ["mon"],
        "hours": 9
      }
    }
    ```

    And now you can set the batch window key to `recipient.batchWindow` to reference this window rule.

  </Accordion>
</AccordionGroup>

**Please note**: an open batch window will never be extended by a subsequent workflow trigger with a different dynamic batch window specified. Once a given batch has been opened by a workflow trigger, its window interval is immutable.

When the key specified is missing, or resolves to an invalid value, a corresponding error will be logged on the workflow run and the batch will be **skipped**.

### Using a sliding batch window

By default, all batch windows are fixed, where the closing of the batch window is determined by the first trigger that starts the batch. In some situations, you may wish to "extend" the batch window when a new trigger is received to recompute the closing time of the batch. This option is supported in the batch step as a "sliding window."

When a sliding window is enabled on a batch function, subsequent workflow triggers that are detected by the already-open batch window will add the configured default window duration onto the already-open batch window. Let's walk through an example:

- 🎛️ [Initial batch window: 1 minute]
- Trigger: the batch opens with a closing window of `now() + 1 min`
- ⏲️ [30 seconds pass]
- Trigger: new item added to the batch, the closing window is recomputed to be `now() + 1 min`, a total of 1 minute and 30 seconds from when the batch was opened
- ⏲️ [1 minute passes]
- The batch closes after 1 minute and 30 seconds

#### Setting a maximum batch window duration

When using a sliding batch window, you must set an extension limit for the batch. This value represents the maximum amount of time that a batch window can remain open if it is extended by subsequent workflow triggers.
This "Max window limit" option is displayed once you enable a sliding window by selecting "Extend window when new activities are received," and can be set as any duration unit.

Once configured, Knock will compute the maximum extended batch window for subsequent triggers as the time your batch was initially opened plus the maximum window duration. For example:

- 🎛️ [Initial batch window: 12 hours]
- 🎛️ [Max extension limit: 24 hours]
- Trigger: the batch opens with a closing window of `now() + 12 hrs`
- ⏲️ [6 hours pass]
- Trigger: new item added to the batch, the closing window is recomputed to be `now() + 12 hrs`, a total of 18 hours from when the batch was opened
- ⏲️ [Another 7 hours pass]
- Trigger: new item added to the batch, the closing window is recomputed to be `now() + 12 hrs`, which would be a total of 25 hours. Because this exceeds the maximum extension limit, the window is set to close 24 hours after it was opened
- ⏲️ [Another 3 hours pass]
- Trigger: new item added to the batch. The closing window is not recomputed because the maximum extension has already been reached
- ⏲️ [Another 8 hours pass]
- The batch closes after 24 hours

If you configure your maximum window with a value that is _less_ than the initial window duration, subsequent batched triggers will shorten the overall window. If this new maximum duration has already elapsed, the batch window will immediately close and the workflow run will proceed.

- 🎛️ [Initial batch window: 24 hours]
- 🎛️ [Max extension limit: 12 hours]
- Trigger: the batch opens with a closing window of `now() + 24 hrs`
- ⏲️ [23 hours pass]
- Trigger: new item added to the batch, the closing window is recomputed to be `now() + 24 hrs`, a total of 47 hours from when the batch was opened. This exceeds the configured maximum of 12 hours, so the window is set to close 12 hours after it was opened
- Because 12 hours have already elapsed, the batch window closes immediately (after 23 hours have elapsed)

To avoid confusion, we recommend always choosing a max extension limit duration that is greater than your initial batch window duration.

## Setting the maximum activity limit

Optionally, you can also set a maximum limit for the number of activities allowed to be accumulated in a given batch, at anywhere between 2 and 1000 activities.

When this option is set, your batch window will close as soon as the number of activities accumulated in the batch reaches the maximum limit set, regardless of the amount of time remaining in its fixed or sliding batch window.

## Setting the batch order

Although batches will accumulate every activity added to the batch, only ten items will be returned in `activities` once the batch step window closes. There are two options for which ten activity objects will be returned when the batch step closes:

- **The first ten (default):** The ten oldest activity objects added to the batch step will be returned.
- **The last ten:** The ten newest activity objects added to the batch will be returned.

Note that for both settings, the `activities` variable will always be sorted in chronological order (oldest to most recent).

## Immediately flushing the first item in a batch

Batch steps optionally support a mode to immediately flush the first item in a batch. This mode is useful when you want to immediately notify a user about the first item in a batch, and then accumulate additional items over a window of time.

To enable this mode, you can toggle on "Immediately flush leading item" in the "Advanced settings" section of the batch step.

When this mode is enabled, the first item for an unopened batch will "open" the batch and the usual batching rules will apply. However, unlike a normal batch, the first item will **not be included in the `activities` of the batch** and will instead continue execution past the batch step.

If you want to branch on whether the first item in a batch was flushed or not, you can use the `total_activities` variable to do so. When it is set to 1, you know that you're working with the first item in a batch.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Please note:</span> if there is never a second
      item added to the batch, the batch will noop on closing as there is
      nothing in it to execute.
    </>
  }
/>

## Working with batches in your templates

Another important aspect of batch functions is that they generate state that can be used in your templates. Let's continue the commenting example we used above.

In this scenario, we'll want different copy in our notification for when a batch includes one item ("Jane left a comment") v. when a batch includes more than one item ("Jane left _n_ comments").

We can address use cases like this by referencing the `total_activities` variable within our workflow.
Here's an example of a message template that uses this variable to determine what type of copy to use:

```markdown
{% if total_activities > 1 %}
{{ actor.name}} left {{ total_activities }} comments on {{ page_name }}
{% else %}
{{ actor.name}} left a comment on {{ page_name }}.
{% endif %}
```

Here's a list of the variables that you can use to work with batch-related state.

- `total_activities`. The number of activities included within the batch. (An example: In the notification "Dennis Nedry left 8 comments for you", the `total_activities` count equals eight).
- `total_actors`. The number of unique actors that triggered activities included within the batch. (An example: In the notification "Dennis Nedry and two others left comments for you", the `total_actors` count equals three, Dennis plus the two others you mentioned in the notification).
- `activities`. A list of up to ten of the activity objects included within the batch, where each activity equals the state sent across in your trigger call. The `activities` variable lists the _first_ or _last_ ten activity objects added to the batch (configurable by setting the [batch order](#setting-the-batch-order)). Each activity includes any data properties you sent along in the trigger call, as well as any user properties for your actor and recipient(s). You can use the activities variable to create templates like this:

  ```
  {% for activity in activities %}
  <p>{{ activity.actor.name }} commented on {{ activity.pageName }} with:</p>

  <blockquote>
  {{ activity.content }}
  </blockquote>
  {% endfor %}
  ```

- `actors`. A list of up to ten of the unique actors included within the batch, where each actor is a user object with the properties available on your Knock user schema. The `actors` variable lists the _first_ or _last_ ten actors added to the batch.

### Setting the batch render limit (beyond 10)

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> The render
      limit setting for batch activities and actors is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan.</a>
    </>
  }
/>

By default, up to ten items will be returned in `activities` and `actors` variables inside your templates after the batch window closes.

On the Enterprise plan, you can configure the maximum number of `activities` and `actors` to be rendered in your templates beyond the default limit of 10, to any number between 2 and 100.

## Using workflow cancellation with batches

If you want to remove an item from a batch (example: a user deletes a comment), you can use our [workflow cancellation API](/send-notifications/canceling-workflows) to cancel a batched item, thereby removing it from the batch.

<Callout
  emoji="⛔"
  text={
    <>
      <span className="font-bold">Important:</span> Once a batch window has been
      opened, it will remain open until its full duration has elapsed. Any
      workflow cancellation will remove the specific individual workflow run
      that it references from the batch.
      <br />
      <br />
      Because of this behavior, it's important to remember that <span className="font-bold">
        canceling a workflow run that opened a batch window will never close the
        batch window itself.
      </span> Any subsequent triggers to that recipient/workflow key combination
      will add activities to the open batch, and those activities will proceed when
      the batch window closes if their respective workflow runs are not also canceled.
      See the FAQs below for a workaround to close an open batch window.
    </>
  }
/>

---

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I set per-environment batch windows?">
    Often when you're testing your Knock workflows, you'll want your batch windows to be shorter in non-production environments to aid with testing. To set per-environment batch windows you can:

    - Create a new variable under **Settings** > **Variables** with a relative duration as JSON (`{ "unit": "seconds", "value": 30 }`) and a name of `batchWindow`. You can set per-environment values to specify a shorter or longer window as needed
    - Set your batch window to "Batch for a dynamic interval"
    - Specify that your batch window will come from an environment variable
    - Set the key to be `batchWindow`, which will resolve the batch window from the variable you created

  </Accordion>
  <Accordion title="Can I close a batch early?">
    Right now we don't offer a way to close a batch from a workflow trigger. One workaround is to use a [sliding batch window](/designing-workflows/batch-function#using-a-sliding-batch-window) and then set the max extension window to be a very small duration (i.e. 1 second), meaning that the batch will immediately close when a subsequent trigger occurs.
  </Accordion>
  <Accordion title="How can items be removed from a batch?">
    You can use the [workflow cancellation API](/send-notifications/canceling-workflows) to remove an item that has been accumulated into an active batch. If all items have been removed from the batch when its window closes, any channel steps proceeding will be skipped.
  </Accordion>
  <Accordion title="How many items can a batch contain?">
    A batch can support an unbounded number of items per recipient, although we will only ever return either the first 10 or last 10 items to be rendered in your template. On Enterprise plan, you can configure to include up to 100 via the [render limit setting](/designing-workflows/batch-function#setting-the-batch-render-limit-beyond-10).
  </Accordion>
  <Accordion title="How many items can I reference in my templates from a batch?">
    We will by default expose at most 10 activities to your template rendered in your batch (available under the `activities` variable). The `total_activities` will always include the total amount of bundled
    activities in the batch. On Enterprise plan, you can configure to include up to 100 via the [render limit setting](/designing-workflows/batch-function#setting-the-batch-render-limit-beyond-10).
  </Accordion>
  <Accordion title="How can I change the order of the batch to retrieve the last 10 items instead of the first 10 items?">
    You can use the "Batch order" setting on the batch step to set if you want the first 10 items (the default) or the last 10 items added to the batch.
  </Accordion>
  <Accordion title="Once activities are batched in an activity, how can I access them?">
    You can use the `activities` property in your template to access the items included in the batch. Each `activity` will include any `data` sent along with the workflow trigger that was batched.
  </Accordion>
  <Accordion title="Is batching the same as digesting notifications?">
    You can think about batching as a per-recipient, per-workflow summary of notifications that should be sent together. Many of our Knock customers use batching as a form of digest to reduce the number of notifications that their users receive. If you have more advance digesting needs that aren't covered by our current batching implementation, [please get in touch](mailto:support@knock.app).
  </Accordion>
  <Accordion title="Do you support per-recipient batch windows and timezones?">
    We're currently working on this feature! If you'd like early access, please [get in touch with us](mailto:support@knock.app?subject=Per%20recipient%20batch%20windows).
  </Accordion>
  <Accordion title="How can I query for messages or feed items that were generated from activities with given workflow trigger call data?">
    When messages are generated from a batch step, the workflow trigger call data for the first (or last) 10 activities of the batch will be combined into one single entity at batch closing time.
    You will be able to filter messages or feed items using the `trigger_data` parameter of our API, which will filter the results to only the items whose workflow trigger call's data
    contain the given `trigger_data` value.

    This means that using the `trigger_data` parameter will only return items for which the combined workflow trigger call data of the
    first (or last) 10 activities contain the value used on the `trigger_data` parameter. If you are using a value for the `trigger_data` parameter which is not included in the
    first (or last) 10 activities of an item, then the item will be returned.

    To understand how the combined trigger call data will look like, let's take a look at the following example:

    Let's consider the case where a message was generated after a batch step with 2 batched activities closes.
    The first activity was generated by workflow trigger call with the following trigger data: `{page: "A"}`.
    The second activity was generated by a workflow trigger with the following trigger data: `{page: "B"}`.
    When the batch closes, the trigger data of both activities will be merged into a single object that will contain the `{page: "B"}`.
    If we try to filter messages or feed items using the `trigger_data` filter with value`{page: "A"}`, the message in the example won't be returned.

  </Accordion>
  <Accordion title="Can I dynamically extend the batch window?">
    Yes, if you use the [sliding batch window](#using-a-sliding-batch-window) option then the batch window can always be extended past its original setting. When combined with a dynamic batch window from a variable, this allows you to control exactly when a specific batch window should close.
  </Accordion>
  <Accordion title="Can I close a batch window by the number of items in the batch?">
    Yes, you can optionally set the [maximum activity limit](#setting-the-maximum-activity-limit) to conditionally close the batch window based on the number of items contained in the batch.
  </Accordion>
  <Accordion title="Is the order of my batch activities guaranteed?">
    We cannot guarantee the order of requests made within quick succession (&lt; 2s) and the order they appear in the batch. If you need a guaranteed order, then you will need to enqueue requests with latency in your system.
  </Accordion>
</AccordionGroup>


## Branch function
Learn more about the branch workflow function within Knock's notification engine.
---
title: Branch function
description: Learn more about the branch workflow function within Knock's notification engine.
tags:
  [
    "steps",
    "branch",
    "switch",
    "conditions",
    "conditional",
    "if else",
    "branching",
  ]
section: Designing workflows
---

The branch function allows you to execute discrete branches of logic within your workflows using our powerful [conditions builder](/concepts/conditions) to specify the criteria for when a branch should execute.

You can think about the branch function in Knock as an `if/else` step, with the ability to add multiple `else if` clauses. Each branch has access to the full [workflow run scope](/concepts/conditions#condition-types) to evaluate conditions. Knock will execute the first branch whose conditions evaluate to `true`.

<Image
  src="/images/branch-step.png"
  alt="Branching by a recipient plan type"
  width={1710}
  height={550}
  className="rounded-md mx-auto border border-gray-200"
/>

## Adding conditions to branches

Each non-default branch must have at least one condition for the branch function to be valid. Conditions are added through the conditions builder, which allows you to compose conditions via `and` or `or` boolean operators. You can build conditions for branches that contain any of the types called out in the [conditions documentation](/concepts/conditions#condition-types), including access to any messages previously generated within the workflow run.

## The default branch

For each branch step, a default branch must always exist, although the default branch does not need to contain any steps. When none of the preceding branches evaluate to `true`, the default branch is executed.

## Terminating branches

Each branch in a branch function can optionally terminate the workflow. This can be useful to ensure that for certain cases you don't want the workflow to continue executing.

You can toggle the ability to terminate the branch by checking the "Exit the workflow at the end of the branch" under the conditions section.

## Managing branches

Branches within your branch function can be:

- Renamed for clarity to give a visual indicator of when the branch executes
- Re-ordered to change the execution order
- Deleted, removing all steps inside of the branch

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note</strong>: the default branch cannot be deleted or re-ordered.
    </>
  }
/>

## Debugging branches

You can debug branch execution in the [workflow debugger](/send-notifications/debugging-workflows). During a workflow run for a workflow with branches, we'll highlight the specific branch paths that were executed to help you debug. We'll also highlight the conditions that led to why a particular branch was executed.

<Image
  src="/images/branch-step-debugging.png"
  alt="Debugging a workflow run with a branch step"
  width={1600}
  height={900}
  className="rounded-md mx-auto border border-gray-200"
/>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do branches work with delays, throttles, and batch functions?">
    Yes, absolutely. You can nest delays, throttles, batches, and other branch
    steps inside of branches as well.
  </Accordion>
  <Accordion title="What's the maximum depth or number of branch steps I can have in a workflow?">
    The maximum depth for branches is set at 5. If you have needs that go beyond
    this, please reach out to discuss.
  </Accordion>
  <Accordion title="What's the maximum number of branches I can have in a branch function?">
    The maximum number is currently 10 branches, including the default,
    per-branch function.
  </Accordion>
  <Accordion title="Can I have conditions on the execution of the branch step itself?">
    No, you cannot have step conditions on the branch step.
  </Accordion>
</AccordionGroup>


## Fetch function
Learn more about the fetch workflow function within Knock's notification engine.
---
title: Fetch function
description: Learn more about the fetch workflow function within Knock's notification engine.
tags: ["steps", "fetch", "request", "http", "functions"]
section: Designing workflows
---

A fetch function executes an HTTP request as a step in a workflow. Any data returned to a fetch function is merged into the original trigger `data` provided on workflow trigger and made available to all subsequent steps in the workflow.

With the fetch function, you can acquire additional data for your channel step templates that may not be immediately available when you first trigger a workflow. A common case is combining a fetch function with a [batch function](/send-notifications/designing-workflows/batch-function) to retrieve trigger data for a group of activities after a batch window has closed. You can also use the fetch function to trigger side effects in your systems as Knock processes your workflow.

## Building a request

As with channel steps, you use the Knock template editor to configure the shape of your request. For each fetch step, you can edit the following attributes:

- **Request method** - You can select one of <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-blue-100 dark:bg-transparent dark:border-blue-600">GET</span> (default), <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-green-100 dark:bg-transparent dark:border-green-600">POST</span>, <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-yellow-100 dark:bg-transparent dark:border-yellow-500">PUT</span>, <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-red-100 dark:bg-transparent dark:border-red-500">DELETE</span>, or <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-purple-100 dark:bg-transparent dark:border-purple-500">PATCH</span>.
- **URL** - A valid HTTP URL.
- **Headers** - Any headers Knock should include in the request. You manage these via a key-value editor, with the key being the header name and the value being the header value.
- **Query parameters** - Any query parameters to encode into the URL. You also manage these via a key-value editor.
- **Request body** - When building a <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-green-100 dark:bg-transparent dark:border-green-600">POST</span> or <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-yellow-100 dark:bg-transparent dark:border-yellow-500">PUT</span> request, you can build a request body to include in the request. Knock will always encode the request body as JSON.

<figure>
  <Image
    src="/images/functions/fetch-function-editor.png"
    width={1015}
    height={907}
    alt="Using the request template editor to configure a fetch function."
    className="rounded-md mx-auto border border-gray-200"
  />
  <figcaption>
    Using the request template editor to configure a fetch function.
  </figcaption>
</figure>

Aside from the request method selector, each of the above fields is a Liquid-compatible input. This means you can use Liquid variables and control flow to inject variable data, access Knock-controlled workflow state attributes (e.g., `recipient`), and dynamically shape the request per workflow run.

See the [Knock template editor reference](/send-notifications/designing-workflows/template-editor) for a detailed guide on working with Liquid templates in Knock.

## Request execution

When executing the request for a fetch function, Knock expects the following from your service:

- The response to the request is one of: `200 OK`, `201 Created`, or `204 No Content`.
- If the request response contains data, it's encoded as JSON and can be decoded into a map/dictionary/hash.
- The response to the request takes no longer than 15 seconds for Knock to receive.

### Merging data

When the response sent to Knock for a fetch function request contains JSON data, Knock will merge the decoded result into the `data` you originally passed to [the workflow trigger call](/send-notifications/triggering-workflows). Knock uses a shallow-merge strategy here where:

- Data from the request overwrites the original workflow run data.
- Top-level attributes are merged, and nested attributes are completely overwritten.

_The merged data result from a fetch function step then becomes the global trigger data for all subsequent steps in the workflow run._

The example below illustrates how this could look in practice.

```json title="Example response data merge for fetch function steps"
// Original trigger data
{
  "foo": "bar",
  "metadata": {
    "count": 1
  }
}

// Fetch function response data
{
  "biz": "baz",
  "metadata": {
    "query_count": 1
  }
}

// Merge result
{
  "foo": "bar",
  "biz": "baz",
  "metadata": {
    "query_count": 1
  }
}
```

### Specifying the Response Path

You can specify where in the trigger data the response from the fetch step should be placed. To do so, click on "Manage Settings" from the fetch step within your workflow template editor. From there, you can specify the response path.

The response path can be any string. To create nested keys within the trigger data, use dot (`.`) notation. For example, specifying `foo.bar` will place the response under the `bar` key within the `foo` object.

### Error handling

Knock will automatically retry request execution for a fetch function following certain types of errors. The first retry will be delayed by 30 seconds, and the second by 60 seconds. These retryable errors are:

- **Server errors** - Any `5xx` level HTTP error code.
- **Request timeouts** - This is any fetch function request from Knock that does not receive a completed response within the 15 second limit.

All other errors or unexpected responses are immediately fatal. These include:

- Any other HTTP response code.
- Some issue with the structure of the request, such as an invalid URL.
- Any issue JSON-encoding a request body.
- Response data that cannot be JSON-decoded as expected.

After two failed retries for a retryable error or any non-retryable error, Knock will mark the fetch function step as a failure and halt your workflow run.

## Testing fetch functions

As you develop, you can execute test runs of your fetch step from right within the template editor. This should look and feel similar to executing test runs of your workflows, but here Knock will execute just your fetch step, ignoring any other steps that may exist before or after.

To run a fetch step test:

1. Click the button that sits to the right of the URL field in the template editor. This should open the Knock test runner modal.
2. Specify the appropriate trigger parameters (actor, recipient, trigger data, and tenant) for the test run. **NOTE:** If your fetch step expects data from a preceding batch step or fetch step, you'll need to explicitly include it here in the "Data" field. Since Knock will test this step in isolation, it cannot know what preceding data may be present when the full workflow runs.
3. Click the "Run test" button in the modal. The modal will close and the test console should display a loading state as Knock executes the test.
4. When the test run has completed, Knock will load the result into the test console for your review. You can then use use the "Request" and "Response" buttons to toggle between the two views in the test console. The "Response" section will show any data returned by the request that would be made accessible to subsequent steps in your workflow.

<video
  className="mb-12 rounded-md border border-gray-200"
  autoPlay
  loop
  muted
  playsInline
>
  <source src="/videos/fetch-step-test-runner.mp4" type="video/mp4" />
</video>

**When running fetch step tests, Knock will not retry a failed request on any error.** For the retryable errors [outlined above](#error-handling), Knock will indicate in the test console result that they would be retried during a full workflow run.

## Debugging fetch functions

You can use the [workflow run logs](/send-notifications/debugging-workflows) to debug your fetch function steps. For each fetch function, you can expect to see in the logs:

- The request URL (with encoded query parameters), headers, and body as sent by Knock.
- The duration of the request (in milliseconds).
- The response headers and body data.

In the workflow run overview, you'll also see any data that Knock successfully received from your fetch function steps and merged into your workflow run state.

<figure>
  <Image
    src="/images/functions/fetch-function-success.png"
    width={1075}
  height={1235}
  alt="Viewing log details for a successful fetch function step."
    className="rounded-md mx-auto border border-gray-200"
    />

  <figcaption>
    Viewing log details for a successful fetch function step.
  </figcaption>
</figure>

If the request encounters an error, you can also expect to see details about the error in the logs. And finally, if the fetch function retries the request on a retryable error, you can expect to see details enumerated for each request attempt.

<figure>
  <Image
    src="/images/functions/fetch-function-error.png"
    width={1052}
    height={958}
    alt="Viewing log details for an unsuccessful fetch function step."
    className="rounded-md mx-auto border border-gray-200"
  />

  <figcaption>
    Viewing log details for an unsuccessful fetch function step.
  </figcaption>
</figure>

See the [guide on debugging workflows](/send-notifications/debugging-workflows) for more details about workflow debugging and run logs.

## Securing fetch requests

Adding security to your fetch requests guards your endpoint from the outside world. There are currently two options to do this within Knock: using authentication headers, or adding request signing.

### Adding authentication via headers

One option for adding authentication is to use a **shared secret** between Knock and your service's endpoint that you inject into the headers of the request. You can use our [secret variables](/concepts/variables#setting-secret-variables) to create and store this secret within Knock, ensuring that it can be unique per environment and also obfuscated within the dashboard across all usage.

Variables can be accessed under the `vars` namespace in liquid. To add a secret into a header you use the syntax `{{ vars.your_variable_name }}` in the header value field.

### Adding request signing

Another option is to enable **request signing**, which will sign the request against a signing key that Knock generates and that can be used to guarantee that the request is coming from Knock.

You can enable request signing for the fetch function by going to the "Manage settings" modal in the top right corner when editing the request template. Once you enable request signing, Knock will generate a signing key that will be used to sign the request. This same key can then be used within your application to verify the request came from Knock via a signature added to the request as a `x-knock-signature` header.

**Verifying the signature**

The signature is generated with an HMAC using the SHA256 algorithm and, before being encoded, is comprised of the timestamp and the stringified JSON payload of the request. We encode `"timestamp in numerical form"."stringified payload"` as the signature of the request.

The `x-knock-signature` header is a string comprised of the timestamp used in the encoding and the encoded value above. It will look like this: `t=timestamp,s=encoded-signature`

To test that the payload sent has not been compromised, you can recreate the signature using the shared secret key and compare to the one sent in the header.

1. Split the `x-knock-signature` on the comma (",") and extract the values of timestamp and signature.
2. Construct the value of the signature by concatenating:

   - The timestamp (as a string)
   - The character `.`
   - The stringified JSON payload

3. Generate the signature with an HMAC and SHA256 algorithm using the signing key from the fetch function.
4. Compare your generated signature with the one extracted in step one; they should match exactly. If the timestamp is more than five minutes old compared to the current time, you may decide you want to reject the payload for additional security.


## Throttle function
Learn more about the throttle workflow function within Knock's notification engine.
---
title: Throttle function
description: Learn more about the throttle workflow function within Knock's notification engine.
tags: ["steps", "functions"]
section: Designing workflows
---

A throttle function allows you to limit the number of times a workflow is executed for a recipient within a given window. For example, in an alerting system, your recipients might only want to receive a single email _per hour_ for a given alert. A throttle lets you express this logic within Knock.

Throttle functions are helpful when you want to control how often a workflow is executed for a recipient without needing to implement the logic within your own application layer.

## How throttling works

Throttling works like a gate. When the throttle step is executed, the gate is checked; if the threshold over the window has been exceeded, then the workflow stops execution. If the threshold has not been met, then the workflow will proceed.

Throttle functions have 3 pieces of configuration:

1. **A throttle window**: the length of the throttle period.
2. **A throttle threshold**: the number of invocations allowed within the window. Defaults to 1 if none provided.
3. **A throttle key** (optional): An optional value to specify as the throttle key for the workflow run.

## Setting a throttle window

The throttle window determines how long a throttle is active for the recipient. The window opens the first time the throttle function is executed in a workflow run for a recipient.

### Set a fixed throttle window

You can set a fixed duration throttle window using the "Throttle for a fixed window" option in the throttle step. The window accepts a relative duration, which can be specified in seconds, minutes, hours, or days.

### Set a dynamic throttle window

You can also set the length of your throttle windows dynamically using a variable. You can use any of the data, recipient, actor, or environment variables associated with the workflow run to set your dynamic throttle window.

When specifying a dynamic window you must provide one of the following:

- An **[ISO-8601 timestamp](https://en.wikipedia.org/wiki/ISO_8601)** (e.g. `2022-05-04T20:34:07Z`) which must be a datetime in the future
- A relative duration unit (e.g `{ "unit": "seconds", "value": 30 }`)
- A window rule (e.g `{ "frequency": "daily", "hours": 9, "minutes": 30 }`)

A dynamic interval must be available to be resolved via the `key` you specify on the given schema, meaning that if you specify a key of `throttleWindow` in your `data` schema, your workflow trigger data must contain either an ISO-8601 timestamp, a valid duration unit, or a valid window rule.

When the key specified is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the throttle will be **skipped**.

<AccordionGroup>
  <Accordion title="Using a fixed timestamp">
   A fixed timestamp will tell Knock to close the throttle window at the exact datetime you provide. It must be a valid ISO-8601 timestamp in the future.

    #### An example timestamp

    ```json title="Setting a throttle until timestamp"
    {
      "throttleUntil": "2024-01-05T14:00:00Z"
    }
    ```

    You can then reference that in your throttle step settings as `data.throttleUntil`.

  </Accordion>
  <Accordion title="Using durations">
    A duration will take the current time that the step is executing and add the duration to it to produce the throttle window close time. A duration object is an entity that you can set on recipients, tenants, environment variables, or in your data payload and reference on your throttle step.

    #### The duration schema

    ```typescript title="A relative duration"
    type Duration = {
      unit: "seconds" | "minutes" | "hours" | "days" | "weeks";
      value: number;
    };
    ```

    #### An example duration

    Let's say you want to express a duration that throttles for 15 minutes, here's how you structure that:

    ```json title="Setting a duration"
    {
      "throttleDuration": {
        "unit": "minutes",
        "value": 15
      }
    }
    ```

    You then reference that as `data.throttleDuration` in the throttle step configuration.

  </Accordion>
  <Accordion title="Using window rules">
    A window rule determines a dynamic interval for when the throttle should close. It allows you to express rules like "throttle until Monday at 9am."

    The window rule will always be evaluated in the [recipient's timezone](/concepts/recipients#recipient-timezones) (when set) and will fall back to the account default timezone, or "Etc/UTC".

    #### The window rule schema

    ```typescript title="A window rule"
    type WindowRule = {
      frequency: "hourly" | "daily" | "weekly" | "monthly",
      // The specific days the rule is valid on
      days?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun"> | "weekdays" | "weekends",
      // The hour which the rule should evaluate (defaults to 0)
      hours?: number,
      // The minute at which the rule should evaluate (default to 0)
      minutes?: number,
      // What day of the month should this rule execute (useful when monthly)
      day_of_month?: number,
      // How often should this rule repeat? Defaults to 1
      interval?: number
    };
    ```

    #### Example window rule

    Let's say you want to express setting a window rule for throttling until Monday at 9am, here's how you might structure that on your recipient:

    ```json title="Recipient throttle window"
    {
      "throttleWindow": {
        "frequency": "weekly",
        "days": ["mon"],
        "hours": 9
      }
    }
    ```

    Now you can set the throttle window key to `recipient.throttleWindow` to reference this window rule.

  </Accordion>
</AccordionGroup>

## Setting a throttle threshold

The throttle threshold determines how many invocations are allowed in the window before the threshold takes effect. By default, this value is set to 1, but you can change it as needed.

For example, if you want to say that you want to allow 5 invocations over a 1-minute window, then you would set the throttle threshold to 5.

## Selecting a throttle key

A throttle function always runs per recipient. If you do not provide a throttle key, your throttle function will throttle for the executing step per recipient. If you do provide a throttle key, your throttle function will be evaluated for the key and executing step.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">A quick tip.</span> Here's a helpful way to
      think about throttling. By default, the throttle function throttles on a
      key of <code>recipient_id</code>. When a throttle key is provided, it
      throttles on a key of <code>concat(recipient_id, throttle_key)</code>.
    </>
  }
/>

Custom throttle keys must be shorter than 64 characters long after being JSON and URL encoded.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use a dynamic throttle window?">
    Yes! A dynamic throttle window can come from a variety of dynamic sources
    like the recipient, the environment, or within the data payload.
  </Accordion>
  <Accordion title="What happens when a throttle is hit?">
    When a throttle is hit, the workflow will stop execution. You will be able
    to see this in your workflow run logs.
  </Accordion>
  <Accordion title="Can an active throttle be canceled?">
    We haven’t added this ability, but if this is something you’re looking to
    do, please reach out to us to discuss your use case. We’d love to hear more.
  </Accordion>
  <Accordion title="What’s the maximum time a throttle can be open for?">
    A throttle is allowed to be opened for a maximum of 31 days. If you have a
    use case for a longer throttle window, please [get in
    touch](mailto:support@knock.app).
  </Accordion>
  <Accordion title="Can I have multiple throttle steps per workflow?">
    Absolutely, each throttle step is executed independently in a workflow, so
    you can have as many as you need.
  </Accordion>
  <Accordion title="Can I throttle across workflows?">
    Currently, you cannot throttle across Knock workflows. In the future, we
    will be exploring adding the ability to rate-limit the number of
    notifications a recipient can receive in a given window of time, which will
    work across workflows.
  </Accordion>
  <Accordion title="Can I extend the throttle window past 31 days?">
    Currently, you cannot extend the throttle window past 31 days. If you need
    to throttle a workflow to run at most once per recipient, you can consider
    using [workflow trigger
    frequency](/send-notifications/triggering-workflows#controlling-workflow-trigger-frequency)
    instead.
  </Accordion>
</AccordionGroup>


## Trigger workflow function (Beta)
Learn more about the trigger workflow function within Knock's notification engine.
---
title: Trigger workflow function
description: Learn more about the trigger workflow function within Knock's notification engine.
tags: ["steps", "functions"]
section: Designing workflows
---

<Callout
  emoji="🚧"
  text={
    <>
      Trigger workflow function is currently in beta. If you'd like early
      access, or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Trigger workflow function beta access">
        get in touch
      </a>
      .
    </>
  }
/>

A trigger workflow function enables you to invoke a workflow from within another workflow. This function allows you to compose complex notifications by reusing logic across multiple workflows, improving maintainability and reducing duplication.

When using the trigger workflow function, you can utilize the data passed directly from the parent workflow or specify custom data for use when triggering the nested workflow.

## How trigger functions work

The trigger workflow step functions similarly to a standard workflow trigger, executing a specified workflow with a specified payload. The payload is constructed based on the configuration settings defined in the step.

Like other functions, the trigger workflow function runs independently for each recipient in the parent workflow. This means that if your parent workflow has three recipients, the trigger function will execute three times, creating distinct workflow runs each time. This behavior ensures that each recipient's context and data is properly isolated in the nested workflow.

## Configuring a trigger function

<Image
  src="/images/functions/functions_trigger_workflow_settings.png"
  alt="Configure trigger workflow function settings"
  className="rounded-md mx-auto border border-gray-200"
  width={500}
  height={620}
/>

<Steps>
  <Step title="Select an active workflow">
    <ul>
      <li>Choose from any currently *active* workflows in your system</li>
    </ul>
  </Step>
  <Step title="Configure step settings for trigger data">
    <ul>
      <li>Recipients</li>
      <li>Actor (optional)</li>
      <li>Tenant (optional)</li>
      <li>Data (optional)</li>
      <li>Cancellation key (optional)</li>
    </ul>
  </Step>
</Steps>

### Selecting the workflow

You can select any active workflow for use in the trigger workflow step. The trigger function will always use the most recently committed version of the selected workflow. To ensure that the correct workflow version is triggered, you must [commit](/concepts/commits) any intended changes to the selected workflow. Any uncommitted changes to the selected workflow will not be reflected when the step is executed.

If the selected workflow is later set to inactive or is archived, the trigger workflow step will be in an invalid state and the step will be skipped.

### Setting the trigger data

The trigger workflow function uses strings or [Liquid](/designing-workflows/template-editor/reference-liquid-helpers) variables to define the trigger data for the nested workflow. You can reference any variables and data available in the parent workflow run.

| Field              | Type   | Default Value                     | Description                                            |
| ------------------ | ------ | --------------------------------- | ------------------------------------------------------ |
| `recipients`       | string | `{{ recipient.id }}`              | The recipient(s) who will receive the nested workflow. |
| `actor`            | string | `{{ actor.id }}`                  | The user or system initiating the nested workflow.     |
| `tenant`           | string | `{{ tenant.id }}`                 | The tenant context for the nested workflow.            |
| `data`             | string | `{{ data \| json }}`              | Data payload passed to the nested workflow.            |
| `cancellation_key` | string | `{{ workflow.cancellation_key }}` | Unique identifier used to cancel nested workflow runs. |

### Handling Errors

When configuring the trigger workflow function, you may encounter the following errors:

- **Liquid Rendering Error**: This occurs when there is a syntax error in the Liquid template used for defining trigger data. Ensure that all variables and expressions are correctly formatted and available in the parent workflow context.

- **Invalid Trigger Data**: If the resolved trigger data for the nested workflow is invalid, the workflow execution will fail. This can happen if required fields are missing or contain incorrect values. Double-check the data being passed to ensure it meets the expected format and requirements of the nested workflow.

## Workflow cancellation

When using trigger workflow functions, both parent and nested workflows can be canceled if they contain cancelable steps (batch, delay, or fetch functions) and are configured with cancellation keys.

If the parent workflow is canceled before the trigger workflow step executes, the nested workflow will not be triggered, so no separate cancellation is needed.

If you need to cancel a nested workflow that has already been triggered, you can do so by making a separate cancellation request using the cancellation key configured in the trigger workflow step. Canceling the parent workflow after the trigger workflow step has executed will not automatically cancel the nested workflow - you'll need to cancel each workflow separately.


## Step conditions
Learn more about how to use step conditions within the Knock workflow builder.
---
title: Step conditions
description: Learn more about how to use step conditions within the Knock workflow builder.
tags:
  [
    "triggers",
    "conditions",
    "conditionals",
    "steps",
    "routing",
    "conditional send",
  ]
section: Designing workflows
---

Step conditions allow you to apply control flow to your workflow runs on a per-step basis. You can use the [Knock conditions editor](/concepts/conditions#the-conditions-editor) to associate one or more conditions with any step in your workflow. Then, for each workflow run, Knock will evaluate these conditions to determine if the step should execute.

Some examples of the kinds of step conditions you can design include:

- Only execute a workflow if `shouldExecute == true`.
- Only send an email if an in-app notification was not previously read or seen.
- Only send an in-app notification if the `recipient.plan == "pro"`.
- Only execute a delay step if `delay == true` in the workflow trigger.
- Only send an email in your development environment if the recipient's email matches a particular domain.

See our [guide on the Knock conditions model](/concepts/conditions) for more information about how conditions work across Knock and how to [debug your conditions within your workflow runs](/concepts/conditions#debugging-conditions).

In this guide, we cover features specific to step conditions, most importantly message status conditions.

## Types of step conditions

### Trigger step conditions

A [trigger step](/designing-workflows/overview#the-trigger-step) can have one or more step conditions, which will be evaluated on the trigger of the workflow for the recipient. When the conditions evaluate to false then the workflow **will be halted** and no other steps will be executed.

### Other step conditions

For all function and channel steps, step conditions will be evaluated when the step is executed. If the conditions on the step evaluate to false, then the step will be **skipped** and the subsequent step will be invoked, or the workflow will terminate if there are no other steps to execute.

## Message status conditions

Message status conditions allow you to build a check for one workflow step that evaluates against the [delivery or engagement status](/send-notifications/message-statuses) of a message sent from a preceding step. When building a step message status condition, you'll use the conditions editor to select:

- Any preceding channel step that may produce a message, using it's `ref`.
- An asserting (`"has"`) or negating (`"has not"`) condition operator.
- The expected delivery or engagement status case.

### Status cases

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Available statuses cases will vary.</span>{" "}
      While you can reference any preceding channel step in a message status
      condition, you will be presented with a different set of options depending
      on the case (asserting or negating) and the target step's channel type.
      In-app feed channel steps support certain engagement status options ("seen
      but not read") that others do not. The "read" and "link clicked" status
      conditions often require that{" "}
      <a href="/send-notifications/tracking">Knock tracking</a> has been
      enabled.
    </>
  }
/>

<table>
  <thead>
    <tr>
      <th width="25%">Case</th>
      <th width="25%">Limits</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <strong>skipped</strong>
      </td>
      <td>-</td>
      <td>The target step was skipped and did not generate a message.</td>
    </tr>
    <tr>
      <td>
        <strong>failed delivery</strong>
      </td>
      <td>-</td>
      <td>
        The message failed to deliver and Knock has exhausted all retries.
      </td>
    </tr>
    <tr>
      <td>
        <strong>bounced</strong>
      </td>
      <td>-</td>
      <td>
        The message was successfully sent to the delivery provider but failed to
        send due to a bounce.
      </td>
    </tr>
    <tr>
      <td>
        <strong>sent</strong>
      </td>
      <td>-</td>
      <td>The message has been successfully sent to the delivery provider.</td>
    </tr>
    <tr>
      <td>
        <strong>delivered</strong>
      </td>
      <td>-</td>
      <td>
        The message has been successfully sent to the delivery provider, and
        Knock has confirmed delivery to your recipient.
      </td>
    </tr>
    <tr>
      <td>
        <strong>seen</strong>
      </td>
      <td>
        <i>In-app channels only</i>
      </td>
      <td>The message has been rendered in the feed.</td>
    </tr>
    <tr>
      <td>
        <strong>seen but not read</strong>
      </td>
      <td>
        <i>In-app channels only</i>
      </td>
      <td>
        The message has been rendered in the feed, but not yet marked as read by
        your recipient.
      </td>
    </tr>
    <tr>
      <td>
        <strong>read</strong>
      </td>
      <td>
        <i>In-app channel or Knock open tracking required</i>
      </td>
      <td>The message has been marked as read.</td>
    </tr>
    <tr>
      <td>
        <strong>read but not clicked</strong>
      </td>
      <td>
        <i>Knock link tracking required</i>
      </td>
      <td>
        The message has been marked as read but no links have been clicked.
      </td>
    </tr>
    <tr>
      <td>
        <strong>interacted with</strong>
      </td>
      <td>
        <i>In-app channels only</i>
      </td>
      <td>The recipient has clicked on the message.</td>
    </tr>
    <tr>
      <td>
        <strong>link clicked</strong>
      </td>
      <td>-</td>
      <td>The recipient has clicked at least one link in the message.</td>
    </tr>
    <tr>
      <td>
        <strong>archived</strong>
      </td>
      <td>-</td>
      <td>The message has been archived.</td>
    </tr>
  </tbody>
</table>

### Evaluation timing

Knock evaluates message status conditions, like all conditions, immediately when executing a workflow step. This means that you may need to account for time between steps when building these conditions, especially those that require some amount of recipient engagement or delivery confirmation. [See below](#example-conditionally-sending-an-email-if-an-in-app-notification-was-not-seen) for an example of using a delay step for this purpose.

### Multiple messages

In certain cases, such as when using a [channel group](/integrations/overview#channel-groups), a single channel step can produce multiple messages. In these cases, Knock uses the message with the **highest** status for the condition evaluation.

To determine each message's highest status, Knock looks at both its [delivery status](/send-notifications/message-statuses#delivery-status) plus each of its [engagement statuses](/send-notifications/message-statuses#engagement-status), choosing the highest value status from the group. Knock uses the following combined delivery and engagement status hierarchy (ordered from lowest to highest):

- `undelivered`
- `bounced`
- `delivery_attempted`
- `queued`
- `not_sent`
- `sent`
- `delivered`
- `seen`
- `read`
- `interacted` + `link_clicked`
- `archived`

## Example: conditionally sending an email if an in-app notification was not seen

One common use-case for step conditions is conditionally sending a notification based on whether the recipient has seen a preceding notification delivered on another channel. You can think of this concept as channel escalation, or intelligent routing.

In order to implement this, your workflow will need:

- An in-app notification channel step to send the initial message
- A delay step so that we wait a period of time before executing the email step
- An email channel step to send the escalated message

Next, we'll add a condition to our email channel step that will tell Knock to only send the email if the in-app notification has not yet been seen. To do this you will:

1. Select a "Step message status" condition type.
2. Select the `ref` of the in-app step (by default named `in_app_feed_1`).
3. Select the negating "has not" operator.
4. And finally, select the "been seen" status case option.

<figure>
  <Image
    src="/images/notifications/message-status-condition-example.png"
    alt="Setting a condition on an email step that passes when the message produced by the preceding in-app step has not been seen after a 5-minute delay."
    width={2984}
    height={1672}
    className="rounded-md mx-auto border border-gray-200"
  />
  <figcaption>
    Setting a condition on an email step that passes when the message produced
    by the preceding in-app step has not been seen after a 5-minute delay.
  </figcaption>
</figure>

That's all it takes to build intelligent message routing in Knock!

## Advanced: How Knock models status conditions

The message status condition editor provides some useful abstractions on top of Knock's [conditions model](/concepts/conditions#modeling-conditions). Under the hood, Knock stores each status condition using our standard `variable`, `operator`, and `argument` trio, with some special caveats:

- The `variable` will always be either `refs.<ref>.delivery_status` or `refs.<ref>.engagement_status`.
- The `operator` will be a hierarchical comparison operator for a delivery status condition or an inclusionary operator for an engagement status condition.
- The `argument` will be a reserved status case string.

Below we provide example models for each of the status conditions made available in the editor.

#### Skipped cases

```json title="'has been skipped' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "equal_to",
  "argument": "$message.skipped"
}
```

<br />

```json title="'has not been skipped' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "not_equal_to",
  "argument": "$message.skipped"
}
```

#### Failed delivery cases

```json title="'has failed delivery' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "equal_to",
  "argument": "$message.undelivered"
}
```

#### Bounced cases

```json title="'has bounced' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "equal_to",
  "argument": "$message.bounced"
}
```

#### Sent cases

```json title="'has been sent' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "greater_than_or_equal_to",
  "argument": "$message.sent"
}
```

<br />

```json title="'has not been sent' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "less_than",
  "argument": "$message.sent"
}
```

#### Delivered cases

```json title="'has been delivered' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "greater_than_or_equal_to",
  "argument": "$message.delivered"
}
```

<br />

```json title="'has not been delivered' case"
{
  "variable": "refs.email_1.delivery_status",
  "operator": "less_than",
  "argument": "$message.delivered"
}
```

#### Seen cases

```json title="'has been seen' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.seen"
}
```

<br />

```json title="'has been seen but not read' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.seen_not_read"
}
```

<br />

```json title="'has not been seen' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "not_contains",
  "argument": "$message.seen"
}
```

#### Read cases

```json title="'has been read' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.read"
}
```

<br />

```json title="'has been read but not clicked' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.read_not_link_clicked"
}
```

<br />

```json title="'has not been read' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "not_contains",
  "argument": "$message.read"
}
```

#### Interacted cases

```json title="'has been interacted with' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.interacted"
}
```

<br />

```json title="'has not been interacted with' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "not_contains",
  "argument": "$message.interacted"
}
```

#### Link clicked cases

```json title="'has had a link clicked' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.link_clicked"
}
```

<br />

```json title="'has not had a link clicked' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "not_contains",
  "argument": "$message.link_clicked"
}
```

#### Archived cases

```json title="'has been archived' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "contains",
  "argument": "$message.archived"
}
```

<br />

```json title="'has not been archived' case"
{
  "variable": "refs.email_1.engagement_status",
  "operator": "not_contains",
  "argument": "$message.archived"
}
```


## Channel steps
Learn more about channel steps within Knock's notification engine.
---
title: Channel steps
description: Learn more about channel steps within Knock's notification engine.
tags: ["steps", "channels", "functions"]
section: Designing workflows
---

A channel step within a workflow is the building block to produce a notification for a recipient. Channel steps house your notification templates and represent a notification to be delivered on a single channel type (e.g. email, push, SMS, in-app, etc).

For a channel step to be valid it must have a [channel or channel group](/integrations/overview#channel-specific-features) associated with it.

## Channel step execution

When a channel step is executed Knock does the following:

1. Runs through any [step conditions](/designing-workflows/step-conditions) to see if the step should be executed.
2. Checks the recipient has the information required to send notifications via this channel. (e.g. for an email channel, do they have an `email` address set? For a push channel do they have the [required channel data](/send-notifications/setting-channel-data) configured?)
3. Checks the [recipient's preferences](/preferences/overview) to see if they have opted out from receiving notifications on this channel or from this workflow.
4. Checks the channel's [send windows](/designing-workflows/send-windows) to see if the notification should be sent now or at a later time.

If the step continues, Knock will render [the template](/designing-workflows/template-editor) associated with the step and enqueue a message to [deliver to the provider](/send-notifications/delivering-notifications) via the configured credentials on the channel.

## Channel support

You can read more about configuring channels in our [integrations guide](/integrations/overview).

### In-app notifications

The Knock [Feed API](/reference#feeds) gives developers a way to deliver in-app notifications to feeds, inboxes, and other notification-based experiences.

There are a few ways to power in-app notifications in your product using Knock:

- **Use our [React SDK](https://github.com/knocklabs/javascript/tree/main/packages/react).** The Knock notification feed component provides real-time updates, pagination, badge behavior, filtering, and more. It's a great way to quickly add an in-app feed to your product if you use React.
- **Leverage our [client-side JS SDK](https://github.com/knocklabs/javascript/tree/main/packages/client).** This is a good approach if you need to use a component library outside of React JS but are still in the JS ecosystem.
- **Integrate with our [API directly](/reference#feeds).** If you're not working within the JS ecosystem in your client, you can integrate directly with the Knock Feed API to power your in-app notifications.

### Out-of-app channels

We support notification delivery to the following out-of-app channel types: [email](/integrations/email/overview), [push](/integrations/push/overview), [SMS](/integrations/sms/overview), and 3rd-party [chat apps](/integrations/chat/overview) (such as Slack). You can see a list of which providers we support within each channel type in the **Integrations** > **Channels** section of the Knock dashboard.


## Send windows
Learn how to control when notifications are delivered using send windows.
---
title: Send windows
description: Learn how to control when notifications are delivered using send windows.
tags: ["send windows", "steps", "channels", "workflows"]
section: Designing workflows
---

You can use send windows to specify when a channel step should send a message. For example, if you want to ensure your customers don’t receive a given transactional email from your product outside of working hours, you can set send windows for Monday - Friday, between 9:00 a.m. and 6:00 p.m. local user time.

Messages generated outside of this window will be [queued](https://docs.knock.app/send-notifications/message-statuses#3-queued) until the next open window, at which time Knock will resume delivery to the downstream provider.

Send windows are evaluated using the recipient's local time, specified by the user `timezone` [property](/concepts/users#optional-attributes). If the user's timezone is not set, the [account default timezone](/manage-your-account/account-timezone) will be used.

## Modeling send windows

Knock models send windows as a list of send window objects. Each day must have 1 send window specified.

The send window object has the following properties:

| Property | Description                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `day`    | Day of the week. One of: ”monday”, ”tuesday”, ”wednesday”, ”thursday”, ”friday”, ”saturday”, ”sunday”.                                           |
| `type`   | Whether notifications should be sent or not sent for this send window. One of: ”send”, ”do_not_send”.                                            |
| `from`   | An optional ISO-8601 time-only format string specifying the start of the window (defaults to 00:00:00). Only supported if type is set to ”send”. |
| `until`  | An optional ISO-8601 time-only format string specifying the end of the window (defaults to end of day). Only supported if type is set to ”send”. |

In our JSON representation this will look something like:

```json title="Example send window"
{
  "day": "monday",
  "type": "send",
  "from": "09:00:00",
  "until": "17:00:00"
}
```

## The send windows editor

When creating or modifying a channel step, you can use the send window editor to configure send windows. If notifications are enabled for a given day of the week, you can also specify the time range during which messages will be sent on that day.

<figure>
  <Image
    src="/images/notifications/send-windows-editor.png"
    alt="Send windows editor"
    width={500}
    height={509}
    className="rounded-md mx-auto border border-gray-200"
  />
  <figcaption>Send windows editor</figcaption>
</figure>


## Partials
Learn how to create reusable pieces of content using partials.
---
title: Partials
description: Learn how to create reusable pieces of content using partials.
tags:
  ["partials", "templates", "custom blocks", "message templates", "workflows"]
section: Designing workflows
---

Partials are reusable pieces of content you can use across any of your channel templates. HTML partials can be enabled as "blocks" for use in Knock’s drag-and-drop email editor.

In this page, we'll walk through how to create partials and use them in your templates using Knock's code editor or visual editor.

## Managing partials

### Creating and editing partials

To get started, navigate to the "Partials" page under the "Developers" section of the main sidebar where you can create a new partial.

When creating or editing partials, you can use the following properties:

| Property      | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `Name`        | A name for your partial.                                                                        |
| `Key`         | A unique key for your partial.                                                                  |
| `Type`        | The type of content you want to create. This can be HTML, markdown, plaintext, or JSON.         |
| `Description` | An optional description of your partial.                                                        |
| `Is block`    | Whether or not to enable this partial as a block within the visual editor (HTML partials only). |
| `Icon name`   | An icon to display for this partial within the visual editor.                                   |

Partials are environment-specific and follow the same version control model as the rest of Knock.

### Editing partial content

After creating a partial, you can edit its content in the code editor.

You can include Liquid variables in your content which will be scoped to your partial. When using the partial in a template, you can pass in values for these variables. To include a variable in your partial, use the following syntax: `{{ variable_name }}`.

<Callout
  emoji="🚨"
  text={
    <>
      <strong>Note:</strong> Partials must be committed before they can be used
      by templates in a given environment. Templates will always use the
      published version of a partial.
      <br />
      <br />
      If you're using a partial in a template that is not yet committed or has unpublished
      changes, you will not see your latest changes.
    </>
  }
/>

#### Editing HTML partials

HTML partials display a preview alongside the editor. Open the preview by clicking the "Preview" button or using the `Cmd + ]` keyboard shortcut on Mac, or `Ctrl + ]` on Windows.

- Select an [email layout](/integrations/email/layouts) to preview the partial within.
- Use the `<style>` tag to add CSS to your partial, which will be inlined when rendering your email messages.
- Edit the placeholder variable values in the preview sidebar. These values are just for the preview and will not be used in your final messages. The preview text will also appear alongside the variable name in the code editor typeahead information.

### Archiving partials

Partials can be archived from the "Partials" page or the partial's details page.

<Callout
  emoji="🚨"
  text={
    <>
      <strong>Note:</strong> If an archived partial is used in a template, it
      will continue to render until the workflow containing that template is
      published again.
      <br />
      <br />
      After the workflow has been published, the partial will not render in your
      messages.
    </>
  }
/>

## Using partials in templates

Partials can be used in templates with the code editor or visual editor.

You can also include partials in other partials. Knock will render partials recursively up to a maximum depth of 5.

### In the code editor

Use partials by using the render tag with the following syntax: `{% render 'partial_key' %}`. You can also use the partial button in the toolbar to insert a partial.

Pass variables in to your partial using the following syntax: `{% render 'partial_key', variable_name: 'value' %}`. You can pass in plain text values or Liquid expressions like `{% render 'partial_key', variable_name: data.variable_name %}`.

The Knock render tag does not support the `for` and `with` modifiers.

To replicate the `for` modifier, use the Liquid `for` block.

```liquid title="Partials in a loop"
{% for item in data.items %}
  {% render 'partial_key', variable_name: item.value %}
{% endfor %}
```

To replicate the `with` modifier, use the `{% assign %}` tag to re-assign a variable.

```liquid title="Alternative to the 'with' modifier"
{% assign item = data.item %}
{% render 'partial_key', variable_name: item.value %}
```

### In the visual editor

HTML partials can be used in the visual editor if they are enabled as blocks. Add a partial to your template by dragging it from the "Custom blocks" section of the sidebar into the template.

Click a custom block to open the inspect panel to edit variable values. You can enter a plain text value or a Liquid expression like `{{ data.variable_name }}`.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why can't I see my partial in the editor or preview?">
    To use a partial in the visual editor, it must be an HTML partial and enabled as a block.

    Partials must be committed before they can be used
    by templates in a given environment. Templates will always use the
    published version of a partial.

    If you're using a partial in a template that is not yet committed or has unpublished
    changes, you will not see your latest changes.

  </Accordion>
</AccordionGroup>


## Template editor

## Overview
Learn how to use the Knock template editor to design notifications for your product.
---
title: The template editor
description: Learn how to use the Knock template editor to design notifications for your product.
tags:
  [
    "template",
    "liquid",
    "steps",
    "variants",
    "localization",
    "internationalization",
    "languages",
  ]
section: Designing workflows
---

Each channel step you add to a workflow will have its own notification template. This template is what determines what the notifications sent to your user look like for a given channel.

In this page we'll walk through the key features of the Knock template editor and how you can use them to design your notifications.

We'll cover:

- Inserting variables from your trigger call into your notification template.
- Using liquid syntax to add logic and control flow to your notification template.
- Visual editing with drag-and-drop components.
- How to preview and test your notification template.
- Why we recommend storing all of your notification templates in Knock.

<Callout
  emoji="💡"
  text={
    <>
      All templates in Knock use the Liquid templating language. You can learn
      more in{" "}
      <a href="https://shopify.github.io/liquid/basics/introduction/">
        the Liquid documentation
      </a>
      .
    </>
  }
/>

## Personalize notifications with template variables

To inject a variable into your notification template, enclose it with double curly braces: `{{ a_variable }}`.

You can use curly braces to reference a number of different variable types in your templates. We've included a few common types below.

You can find the [full list of supported variables here](/designing-workflows/template-editor/variables).

### Data payload variables

All variables sent in the `data` payload of your workflow trigger call. If you send through `{ "a_variable": "something" }` in your data payload you can reference this as `{{ data.a_variable }}` in your template.

<Callout
  emoji="💡"
  text={
    <>
      Note: if you want to reference all of the data passed to the workflow, you
      can use the <code>data</code> variable.
    </>
  }
/>

### User properties

To reference a user property (such as `name`), use the `actor` and `recipient` namespaces. This looks up the actor or the recipient of a given notification, and then finds the specified property for that user. Here's a code example where a recipient's name and plan are injected into a notification template:

```
Hey there {{ recipient.name }},

You just upgraded to the {{ recipient.plan }} plan.

Thanks,
The team @ Knock
```

[Full list of Knock variables available →](/designing-workflows/template-editor/variables)

## Adding control flow and iteration to your template

The Knock template editor uses Liquid tags to create the logic and control flow for notification templates. To learn more about Liquid, you can check out [its documentation](https://shopify.github.io/liquid/basics/introduction/).

Here are a few Liquid tag types that are commonly used in Knock notification templates.

**If and else-if statements.** For when you want to show different copy depending on a user property or a data variable from your trigger call. In the example below, we show different copy depending on whether a batch of comments includes one or many comments.

```liquid
{% if total_activities > 1 %}
  {{ actor.name }} left {{ total_activities }} comments on {{ page_name }}
{% else %}
  {{ actor.name}} left a comment on {{ page_name }}.
  > {{ comment_body }}
{% endif %}
```

**For loops.** You can use Liquid's `for...in...` tag to iterate over a list of items. We can add this to our example from above to iterate over the comments in a batch and add each one to our notification.

```liquid
{% if total_activities > 1 %}
  {{ actor.name}} left {{ total_activities }} comments on {{ data.page_name }}

  {% for activity in activities %}
  > {{ activity.data.comment_body }}
  {% endfor %}

{% else %}
  {{ actor.name}} left a comment on {{ data.page_name }}.
  > {{ data.comment_body }}
{% endif %}
```

There are also a number of [Liquid filters](/designing-workflows/template-editor/reference-liquid-helpers) you can use to mutate the variables you pass into a notification template. Here's an example that uses the `split` and `first` filters to pull the first name for a given user.

```liquid
You've been invited by {{ actor.name | split: " " | first }} to
join {{ data.account_name }} on Knock.
```

To learn more about the variables, Liquid keywords, and other helper functions available to you in the Knock template editor, check out our [liquid helper reference](/designing-workflows/template-editor/reference-liquid-helpers).

## Visual editing with drag-and-drop components

The Knock template editor includes a visual editor you can use to compose your template with drag-and-drop components.

<Callout
  emoji="🛣"
  text={
    <>
      <span className="font-bold">Note: </span>The visual template editor is
      currently only available for email templates.
    </>
  }
/>

When you're in the visual template editor you'll see a **Components** panel on the right with a number of components for use in your template.

Once you add a new component to the document, the Components pane will automatically switch to **Inspect** mode, where you can edit various attributes of the newly added component. While in inspect mode, you can remove the component by clicking the `x` icon in the top-right corner of the component or access additional menu items from the Inspect pane header.

As a reminder, **you still have full access to the variables data as well as liquid tags** when editing any of the text content fields of any components. The visual template editor makes it easier to introduce elements into your notification template while still giving you the full flexibility and power of code.

A few other component features to note:

- **Markdown (and Blockquote) components** support liquid and basic Markdown syntax. You can learn more about Markdown in [its documentation](https://www.markdownguide.org/basic-syntax/).
- **Button components** can be configured to use your brand colors by default, so you can ensure your brand elements are consistent across all of your product messaging. To configure your brand colors, head over to the branding settings page in your dashboard. ("Settings" page → "Branding" tab)
- **HTML components** can contain any valid HTML markup and provide an "escape hatch" for advanced use cases where more complex markups are needed.

If you ever want to take complete control of the notification template and just work in HTML and CSS, you can enter the code editor via the "Enter code editor" button found at the bottom of the editor. When opting out of the visual template editor, any components used in the template document will be translated into the equivalent HTML for you to take over.

### Updating component styles

When using the visual template editor, a handful of CSS styles are auto-generated and included in the email layout to provide base styles for certain components. If you want to globally configure these component styles to match your design system, you can do so by updating your email layout to override the base styles we generate for components. You can learn more about updating base component styles in email layouts [here](/integrations/email/layouts#updating-base-component-styles).

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Reminder: </span>The visual template editor
      will only render component styles when you are in preview mode. Your
      layout (and its styles) is not rendered in editor mode.
    </>
  }
/>

## Previewing and testing your notification template

Once you've finished editing your notification template, you can select "Preview" in the toggle in the top left of the template editor pane to enter preview mode.

<Callout
  emoji="🧩"
  text={
    <>
      <span className="font-bold">Note: </span>When you enter preview mode for
      an email template, you'll see your email content wrapped within the
      template's selected <a href="/integrations/email/layouts">Layout</a>.
    </>
  }
/>

Your notification preview is populated with the data available in the lefthand variable explorer pane. You can use the actor and recipient dropdowns to change the user data used in your preview, and you can click on any of your data variables to edit their preview value.

To test your notification, click "Save" and navigate back to the workflow canvas by clicking the back arrow in the top-left corner. You can run actual notification tests by clicking "Run a test" in the top-right corner. Just choose your actor and recipient, provide and trigger call data that you'd like included in your test, and click "Run test."

All test runner notifications are tracked under "Messages" and have a source of "Test runner" to distinguish them from notifications you've triggered via the Knock API.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why store all of my notification templates in Knock?">
    This is a common question that we hear from our customers, particularly those who currently maintain templates for their notifications in other third-party tools (often more than one!).

    While [planning a migration](/guides/implementation-guide) will require some upfront effort, we recommend using Knock as the source of truth for your notification templates for a number of reasons:

    - **A consistent editing experience.** When you manage all of your templates in Knock, your content authors have access to a unified template editor for a consistent experience across all delivery channels. Teams who collaborate on messaging can work with a single templating language (Liquid) for dynamic content.
    - **Cross-channel engagement analytics.** With Knock [link and open tracking](/send-notifications/tracking) in your message templates, you have access to cross-channel engagement analytics for each of your notification use cases in a centralized tool.
    - **Unlock greater efficiency.** In the same way that Knock combines the logic and delivery of all of your notifications into a single API, using Knock as the source of truth for your templates means streamlining your process for cross-functional work on notifications. All changes to your message content, regardless of delivery channel, will follow the same steps for previewing, testing, and committing updates to production.
    - **Work with your templates programmatically.** With our [Management API](/mapi) or [CLI](/cli), you can work with all of your cross-channel templates as code via a single API. This enables you to integrate your templates with other tools, automate updates, and more.
    - **Reusable content blocks.** Our [Partials](/designing-workflows/partials) feature allows you to create content blocks of various types that can be reused across all of your notification templates. This enables updates across all delivery channels with a single change when necessary.
    - **Reference data from other resources stored in Knock.** In addition to the context that you pass to Knock on your workflow trigger calls and [reference as dynamic content](/designing-workflows/template-editor/variables) in your notifications (like `recipient` and `tenant` properties, or custom `data` payload variables), the Knock template editor also allows you to [reference data](/designing-workflows/template-editor/referencing-data) from any Users, Objects, and Tenants that exist within your Knock environment.

        Referencing data is a powerful way to share context across entities in your templates without needing to manually pass the data in the `data` argument of your workflow trigger, and isn't possible with other templating solutions.

  </Accordion>
</AccordionGroup>


## Variables
A reference guide for the variables available in the Knock template editor.
---
title: "Template editor variables"
description: "A reference guide for the variables available in the Knock template editor."
tags: ["liquid", "template", "variables"]
section: Designing workflows
---

When you build workflows in Knock, we auto-generate certain pieces of state (as a result of batch functions and other workflow steps) that you can use to control the copy you display to your end users in your notification templates.

| Variable           | Description                                                                                                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activities`       | A list of the activity objects included within the batch, where each activity equals the state sent across in your trigger call, and also includes the actor who performed the message and a timestamp of when the activity occurred. |
| `actor`            | A serialized `Recipient` of the actor that triggered the workflow (may be `null`). Will include any custom properties set.                                                                                                            |
| `actors`           | A list of up to 10 of the unique actors included within the batch.                                                                                                                                                                    |
| `current_message`  | A serialized `CurrentMessage` (see below).                                                                                                                                                                                            |
| `data`             | The complete data passed to the workflow trigger.                                                                                                                                                                                     |
| `recipient`        | A serialized `Recipient` of the recipient of the workflow. Will include any custom properties set.                                                                                                                                    |
| `tenant`           | A serialized `Tenant` (see below) which is set when a `tenant` is passed to the workflow trigger.                                                                                                                                     |
| `timestamp`        | The time in which the activity occurred, as an ISO-8601 datetime string.                                                                                                                                                              |
| `total_activities` | The count of activities associated with a workflow run.                                                                                                                                                                               |
| `total_actors`     | The count of unique actors associated with a workflow run.                                                                                                                                                                            |
| `vars`             | Account and environment-specific variables.                                                                                                                                                                                           |
| `workflow`         | A serialized `Workflow` (see below).                                                                                                                                                                                                  |

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note:</span> all of the <code>data</code>{" "}
      supplied to your workflow trigger is always available for use in your
      template under the <code>data</code> key.
    </>
  }
/>

### Recipient (User or Object)

A serialized `User` or `Object`. The properties available are:

| Variable       | Description                                                                                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__typename`   | Either `User` or `Object`                                                                                                                                                                      |
| `id`           | The id of the recipient                                                                                                                                                                        |
| `collection`   | The collection of the object (only set for `Object` recipients)                                                                                                                                |
| `*`            | Any custom properties set                                                                                                                                                                      |
| `created_at`   | A datetime field for when the recipient was created (if set)                                                                                                                                   |
| `updated_at`   | A datetime field for when the recipient was last updated                                                                                                                                       |
| `subscription` | An optional set of properties set on a `subscription`. Only available when a workflow is triggered via a [Subscription](/concepts/subscriptions).                                              |
| `schedule`     | A serialized `Schedule` including the `id`, `last_occurrence_at`, and `next_occurrence_at` of the schedule. Only available when a workflow is triggered via a [Schedule](/concepts/schedules). |
| `preferences`  | The preference set for the recipient. Will contain a completely resolved `PreferenceSet` object, including tenant and environment defaults.                                                    |

### Activity

A serialized `Activity`, which represents a workflow trigger for the recipient. Activities may be accumulated during a batch operation. The properties available are:

| Variable      | Description                                        |
| ------------- | -------------------------------------------------- |
| `id`          | The unique id of the activity                      |
| `*`           | Trigger data sent that generated the activity      |
| `inserted_at` | The datetime of when the activity was generated    |
| `updated_at`  | The datetime of when the activity was last updated |

### CurrentMessage

Provides access to the currently generated `Message` that the template is rendered against. The properties available are:

| Variable      | Description                                       |
| ------------- | ------------------------------------------------- |
| `id`          | The id of the message                             |
| `inserted_at` | The datetime of when the message was created      |
| `updated_at`  | The datetime of when the message was last updated |

### Workflow

Provides access to serialized properties about the currently executing workflow. The properties available are:

| Variable     | Description                                   |
| ------------ | --------------------------------------------- |
| `id`         | The id of the version of the current workflow |
| `key`        | The unique key of the workflow                |
| `categories` | A list of categories set for the workflow     |

### Tenant

A serialized `Tenant`. The properties available are:

| Variable               | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `id`                   | The id of the tenant                                      |
| `*`                    | Any custom properties set on the tenant                   |
| `settings.preferences` | The default preferences set for the tenant.               |
| `settings.branding`    | The branding set for the tenant.                          |
| `created_at`           | A datetime field for when the tenant was created (if set) |
| `updated_at`           | A datetime field for when the tenant was last updated     |


## Referencing data
A guide for working with data in your templates.
---
title: "Referencing data in templates"
description: A guide for working with data in your templates.
tags: ["liquid", "template", "objects", "users", "tenants"]
section: Designing workflows
---

In addition to the [variables](/designing-workflows/template-editor/variables) available as part of the workflow run scope, you can also reference data from the users, objects, and tenants that exist within your Knock environment.

Referencing data is a powerful way to share context across entities in your templates without needing to manually pass the data in the `data` argument of your workflow trigger.

## Referencing users via the `user` filter

To reference a user, you can use the `user` filter. This will return a serialized `User`, which you can then use to output data in your template.

Users returned will have all custom properties available, as well as the `id`, `name`, `email`, `phone_number`, `created_at`, and `updated_at` properties.

```liquid title="Referencing a user via a static identifier"
{% assign user = "chris" | user %}
```

 <br />
 
```liquid title="Referencing a user via a dynamic identifier"
{% assign user = data.other_user_id | user %}
```

## Referencing objects via the `object` filter

To reference an object, you can use the `object` filter. This will return a serialized `Object`, which you can then use to output data in your template. When referencing an object, you'll also need to specify the `collection` of the object you're loading.

Objects returned will have all custom properties available, as well as the `id`, `collection`, `created_at`, and `updated_at` properties. Read more about [working with objects](/concepts/objects).

```liquid title="Referencing an object in the 'projects' collection via a static identifier"
{% assign project = "proj_1" | object: "projects" %}
```

 <br />
 
```liquid title="Referencing an object in the 'projects' collection via a dynamic identifier"
{% assign project = data.project_id | object: "projects" %}
```

## Referencing tenants via the `tenant` filter

To reference a tenant, you can use the `tenant` filter. This will return a serialized `Tenant`, which you can then use to output data in your template.

Tenants returned will have all custom properties available, as well as the `id`, `created_at`, and `updated_at` properties. Read more about [working with tenants](/concepts/tenants).

```liquid title="Referencing a tenant via a static identifier"
{% assign tenant = "acme" | tenant %}
```

 <br />
 
```liquid title="Referencing a tenant via a dynamic identifier"
{% assign tenant = data.other_tenant_id | tenant %}
```

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens if I reference a user, object, or tenant that doesn't exist?">
    If you reference a user, object, or tenant that doesn't exist, the value will be `null` in your template. Trying to use it to output data will return an empty string.

    If you want to conditionally display data based on whether a user, object, or tenant exists, you can do so using Liquid's `if` statement.

  </Accordion>
  <Accordion title="How can I ensure that only certain users, objects, or tenants are available in my template?">
    Knock cannot constrain the entities that are available in your template based on the recipient of the workflow run or the tenant passed in. It is your responsibility to ensure that any entities loaded as part of executing a template are accessible to the recipient.
  </Accordion>
</AccordionGroup>


## Liquid helpers
A reference guide to help you work with the Liquid templating language in Knock.
---
title: "Liquid helpers"
description: A reference guide to help you work with the Liquid templating language in Knock.
tags: ["liquid", "template", "variables", "currency", "timezone", "pluralize"]
section: Designing workflows
---

The Knock template editor uses Liquid syntax for control flow and variable declaration. Here are a few of the most common Liquid keywords our customers use within Knock. For a complete reference guide, we recommend the excellent [Liquid documentation](https://shopify.github.io/liquid/).

| Keyword         | Description                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| `{{ }}`         | Denotes rendering output of an object or variable.                                                      |
| `{% %}`         | Denotes logic and control flow.                                                                         |
| `if/else/elsif` | Conditional branching.                                                                                  |
| `case/when`     | Creates a switch statement to execute a particular block of code when a variable has a specified value. |
| `and/or`        | Add additional conditions to a tag.                                                                     |
| `for`           | Repeatedly executes a block of code.                                                                    |
| `assign`        | Creates a new named variable.                                                                           |
| `capture`       | Captures the string inside of the opening and closing tags and assigns it to a variable.                |
| `render`        | Renders a partial with the given key and attributes.                                                    |

## Knock-specific Liquid helpers

| Helper             | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Example                                                                           |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `timezone`         | Takes an ISO 8601 timestamp and returns it in the [IANA tz database timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) provided. You can use the built-in `timestamp` [template variable](/designing-workflows/template-editor/variables) to reference the current datetime. When formatting with the `date` filter, we recommend using the `timezone` option on the `date` filter instead. | <code>{"{{ timestamp \| timezone: \"America/New_York\"}"}}</code>                 |
| `date`             | This filter has been extended to take an additional `timezone` option.                                                                                                                                                                                                                                                                                                                                           | <code>{"{{ startDate \| date: \"%-I:%M %p %Z\" , \"America/New_York\" }}"}</code> |
| `format_number`    | Takes an integer and formats it to the local number format of the `locale` provided to format_number helper.                                                                                                                                                                                                                                                                                                     | <code>{"{{ 10000 \| format_number: \"en\" }}"}</code>                             |
| `currency`         | Takes an integer and returns a USD formatted value with two decimal points. You can pass a currency type and a `locale` through to the currency helper to tell it which currency to use.                                                                                                                                                                                                                         | <code>{"{{ 10 \| currency: \“GBP\”, \"en\" }}"}</code>                            |
| `rounded_currency` | Takes an integer and returns a USD formatted value rounded to nearest whole number. You can pass a currency type and a `locale` through to the currency helper to tell it which currency to use.                                                                                                                                                                                                                 | <code>{"{{ 10.99 \| rounded_currency: \"GBP\", \"en\" }}"}</code>                 |
| `json`             | Takes a value and returns as a formatted JSON string.                                                                                                                                                                                                                                                                                                                                                            | <code>{"{{ recipient \| json }}"}</code>                                          |
| `pluralize`        | Takes an integer and a pluralize helper with two strings. If the integer is one, the helper returns the first string. If the helper is greater than one, it returns the second string.                                                                                                                                                                                                                           | <code>{"{{ total_actors \| pluralize: \"user\", \"users\" }}"}</code>             |
| `titlecase`        | Takes a string and reformats it into Title case.                                                                                                                                                                                                                                                                                                                                                                 | <code>{"{{ project_name \| titlecase }}"}</code>                                  |
| `md5`              | Takes a string and returns an md5 hash.                                                                                                                                                                                                                                                                                                                                                                          | <code>{"{{ recipient.id \| md5 }}"}</code>                                        |
| `sha256`           | Takes a string and returns an sha256 hash.                                                                                                                                                                                                                                                                                                                                                                       | <code>{"{{ recipient.id \| sha256 }}"}</code>                                     |
| `hmac_sha256`      | Takes a string and returns an hmac hash given a key provided to hmac_sha256 helper.                                                                                                                                                                                                                                                                                                                              | <code>{"{{ recipient.id \| hmac_sha256: \"some-key\" }}"}</code>                  |
| `intersect`        | Returns the intersection of two arrays (the elements common to both).                                                                                                                                                                                                                                                                                                                                            | <code>{"{{ arr1 \| intersect: arr2 }}"}</code>                                    |
| `from_markdown`    | Takes a string of markdown and converts it to HTML.                                                                                                                                                                                                                                                                                                                                                              | <code>{"{{ data.comment_body \| from_markdown }}"}</code>                         |

### Localization parameters

A few of Knock's Liquid helpers (such as `currency` and `format_number`) take an optional locale parameter to format the output of the helper into a localized format. You can find a list of supported locales below. If we're missing a locale that you'd like us to support, please [reach out](mailto:support@knock.app).

**Supported locales:** `af`, `ar`, `az`, `be`, `bg`, `bn`, `bs`, `ca`, `cs`, `cy`, `da`, `de`, `el,` `en`, `eo`, `es`, `et`, `eu`, `fa`, `fi`, `fr`, `gl`, `he`, `hi`, `hr`, `hu`, `id`, `is`, `it`, `ja`, `ka`, `km`, `kn`, `ko`, `lb`, `lo`, `lt`, `lv`, `mk`, `ml`, `mn`, `mr`, `ms`, `nb`, `ne`, `nl`, `nn`, `or`, `pa`, `pl`, `pt`, `rm`, `ro`, `ru`, `sk`, `sl`, `sq`, `sr`, `sw`, `ta`, `te`, `th`, `tr`, `tt`, `ug`, `ur`, `uz`, `vi`, `wo`, `zh`



# Managing recipients
Learn more about how to manage notification recipients with Knock.

## Overview
Learn more about managing recipients within Knock.
---
title: Overview
description: Learn more about managing recipients within Knock.
section: Managing recipients
---

[Recipients](/concepts/recipients) in Knock are the [users](/concepts/users) and [objects](/concepts/objects) that receive notifications. In this section, we walk you through managing recipient data for your environment, using both our API and Dashboard.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note</strong>: you may think it's odd to think about Objects as a
      recipient of a notification. We use Objects as a way to model non-user
      recipients that you may need to send a notification to from your system.
    </>
  }
/>

#### Quick links

- [Identifying recipients](/managing-recipients/identifying-recipients)
- [Setting preferences](/preferences/overview#set-a-users-preferences)
- [Setting channel data](/managing-recipients/setting-channel-data)

## Recipients and environments

Your recipient data exists **per environment**, meaning that each [environment](/concepts/environments) you have in your Knock account will contain a unique set of recipient data. If you have recipients that need to span across environments, then you should identify those recipients across each environment.

## Storing recipient data in Knock

In Knock, we refer to the process of storing recipient data as "identifying" one or many recipients. Your recipient data must exist in Knock to send notifications to those recipients or to reference the recipient within a notification template.

Identifying recipients is done programmatically via our REST API, either individually, in bulk, or inline when specifying a recipient in other calls.

[Learn more about identifying recipients ->](/managing-recipients/identifying-recipients)

### Why store recipient data in Knock

If you're used to sending notifications via single-channel APIs, the idea of storing recipient data in a messaging platform such as Knock may sound odd to you.

Here are a few reasons why we store recipient data in Knock:

- **Multi-channel notifications.** When you're using a single-channel API, you can pass through the recipient's email address or phone number when you trigger a message. In a multi-channel platform like Knock, that would mean passing through _all_ of a recipient's channel information every time you trigger a notification. By keeping a recipient model in Knock, you can update a recipient's channel information once, then reference them via their recipient ID from that point on. We take care of the rest.
- **Stateful in-app notifications.** The Knock Feed API returns a stateful feed of the in-app notifications a given recipient has received from your product. The Knock recipient model is used to store a given recipient's notification feed and to give you a way to retrieve that feed via the recipient identifier you keep for them in your product.
- **Preferences model.** The Knock recipient model enables advanced functionality such as preferences support, where you store a given recipient's notification preferences in Knock and we reference that recipient's preferences during the run of a given notification workflow.
- **Leverage recipient traits in notification templates.** The Knock recipient model also enables you to store custom traits on a given recipient that you can reference in a notification template. This is helpful when you want to add conditional copy to a notification based on a recipient's role or plan.

We do not take storing your recipient data lightly. You can learn more about our security posture and best practices on [our security page](/security).

## Fetching recipient data

From the API you can retrieve information about the recipient data that you have stored inside of Knock. Recipient information is accessible from both the client-side and server-side using the appropriate [API keys](/developer-tools/api-keys).

You can find more about retrieving recipients in the [API reference](/reference).

## Working with recipients in the dashboard

The Knock dashboard also provides access to the Users and Objects that you have identified within each environment. From the dashboard you can:

- Search for a specific recipient by id, name, or email
- View the recipient, including any custom properties set
- View recipient channel data
- View and manage recipient preferences
- View recent messages sent to the recipient
- View recent workflow runs for the recipient
- View any schedules for the recipient


## Identifying recipients
Learn more about how to identify your user and object recipients to power your notifications.
---
title: Identifying recipients
description: Learn more about how to identify your user and object recipients to power your notifications.
tags: ["recipients", "inline identify", "identify"]
section: Managing recipients
---

To send notifications to a recipient (or to reference a recipient as an actor in a notification), Knock needs the recipient's data to be stored in Knock. This process is known as **identifying** and works across user and object recipients.

There are three different methods to identify recipients:

- Individual identification
- Bulk identification
- Inline identification

In this guide we discuss each of these methods.

<Callout
  emoji="🌠"
  text={
    <>
      <strong>Note</strong>: all identification methods in Knock use an upsert
      approach. This means any existing data for a recipient is merged during
      the upsert operation.
    </>
  }
/>

## Explicitly identifying recipients

### Individually identifying recipients

You can use the individual identification API to upsert a single recipient's data into Knock. The individual identify API is useful to ensure that user data is updated on an ongoing basis, like when a user updates their profile information inside of your product and you need to ensure it's reflected within Knock.

<MultiLangCodeBlock snippet="users.identify" title="Identify a user" />

[API reference ->](/reference/#identify-user)

### Bulk identifying recipients

While identifying individual recipients is useful, you may also need to identify multiple recipients at once. This can be useful when you're importing data into Knock to get started.

<MultiLangCodeBlock snippet="users.bulkIdentify" title="Bulk identify users" />

[API reference ->](/reference/#bulk-identify-users)

## Inline identifying recipients

It's also possible to inline identify recipients while issuing calls to certain resources within Knock. Inline identifying will always upsert the recipients being passed in before executing the remainder of the request. This can be useful for ensuring that your recipients exist within Knock before executing calls that reference those recipients.

You can also inline identify actors in the same way.

Inline identification works with any endpoint that accepts a list of recipients:

- [Workflow triggers](/reference#trigger-workflow)
- [Subscriptions](/reference#add-subscriptions)
- [Schedules](/reference#create-schedules)

<MultiLangCodeBlock
  snippet="workflows.trigger-with-user-identification"
  title="Trigger your workflow"
/>

[API reference ->](/reference#trigger-workflow-inline-identify)

### How inline identification works

When passing a set of recipients to be inline identified, Knock will guarantee that the recipients are identified **before** any other action is executed. That makes it possible to lazily create recipients within Knock using inline identification, only creating them when needed.

## Setting properties while identifying recipients

When identifying recipients you pass a set of properties for the recipient that are persisted. No properties on the recipient are required except for `id`. Generally, the best practice here is to use your internal identifier for your users as the `id`.

<Callout
  emoji="🙈"
  text={
    <>
      <strong>Note:</strong> Although an <code>id</code> is the only required
      recipient property, triggering a workflow for a recipient which has only
      an <code>id</code> and no other properties can result in{" "}
      <a href="/designing-workflows/channel-step">channel steps</a> other than
      an In-app feed being skipped. This occurs when Knock does not have the
      necessary recipient data to deliver a notification.
    </>
  }
/>

There are some reserved property names for recipients that have special meaning:

- `name`: The given name of the recipient
- `email`: A valid email address to deliver email notifications to
- `locale`: A locale code for the recipient, used for internationalizing content
- `phone_number`: A E.164 compliant phone number field used when sending SMS messages
- `created_at`: An ISO-8601 datetime of when the recipient was created

A recipient also accepts any number of custom properties, which are key-value pairs that you define. It's useful to store custom properties on your recipients so that you can reference these attributes when sending notifications, or for use in message templates.

### Setting preferences and channel data

It's also possible to set preferences and channel data for a recipient during the identification process.

Preferences are passed as a dictionary under the `preferences` key, where the key represents the preference set id:

```json title="Setting preferences inline"
{
  "preferences": {
    "default": {
      "channel_types": { "email": true }
    }
  }
}
```

Channel data is passed as a dictionary under the `channel_data` key, where the key represents the channel id:

```json title="Setting channel data"
{
  "channel_data": {
    "some-uuid-for-a-channel": {
      "tokens": ["my-push-token"]
    }
  }
}
```

## When to identify recipients in Knock

Knock provides a flexible set of APIs for you to manage your user data as you scale with us. Ultimately, it's up to you to decide upon the best approach for how you manage your user data with Knock.

Below we discuss some common scenarios to consider.

### Initial setup: inline vs. bulk identification

When you're first getting started with Knock, you'll likely have a number of existing recipients that you want to migrate into Knock. If you're looking to get started with Knock quickly, you can use [inline identification](#inline-identifying-recipients) to start calling your workflows without any prerequisite calls to the Knock API.

If you first want to get all your recipients into Knock, the easiest path forward would be via our [bulk identification flow](#bulk-identifying-recipients).

### Identifying recipients on an ongoing basis: jobs vs. inline identification

Once you've migrated your current recipients into Knock, you'll want to continue to update this data in Knock for two key cases:

1. When new recipients sign up for your product.
2. When Knock-relevant data about a user changes, like a name or an email address.

One common approach is to make subsequent calls to the Knock's user identify API following such events. For example, you could do this via a deferred job in your backend systems.

Another option is to offload these updates to your workflow trigger calls via inline identification. If you always send Knock the full set of data for your recipients [via workflow trigger calls](/reference#trigger-workflow-inline-identify), you can keep your user data up to date in Knock without any additional handling on your end.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I set a user's preferences while inline identifying?">
    Preferences can be set during a workflow trigger using [inline identify](/send-notifications/triggering-workflows/api#identifying-recipients-inline). One or more preference sets (including [per-tenant preferences](/preferences/tenant-preferences)) can be upserted by passing a dictionary of [PreferenceSets](/preferences/overview), where each key in the dictionary is the preference set ID.

    Unlike the `setPreferences` [method](/preferences/overview#set-a-users-preferences), setting preferences inline requires you to explicitly provide the `default` preference set key when updating default preferences.

    <Callout
      emoji="🚨"
      text={
        <>
          <strong>Please note:</strong> setting preferences inline will always
          upsert the preference set, meaning that changes will override any existing
          preferences. We generally recommend against using inline preferences to
          ensure the integrity of your data.
        </>
      }
    />


    <br />

    <MultiLangCodeBlock
      title="Setting preferences during a workflow trigger"
      snippet="workflows.trigger-with-user-preferences"
    />

  </Accordion>
</AccordionGroup>


## Setting channel data
Learn about how to set channel data for your recipients and users to make it easy to connect recipients with push and chat channels.
---
title: Setting channel data
description: Learn about how to set channel data for your recipients and users to make it easy to connect recipients with push and chat channels.
tags: ["channels", "slack", "push", "tokens", "recipients", "msteams", "teams"]
section: Managing recipients
---

Some channel integrations require user and channel-specific data to send notifications. Push channels like APNs (Apple Push Notification Service) and FCM (Firebase Cloud Messaging) are good examples, where both require that there are device-specific tokens that target the user in a push notification. Slack is another good example, where the channel data from a Slack integration in your product is stored on a Knock [object](/concepts/objects).

At Knock we call this concept <a href="/reference#channel-data">`ChannelData`</a>. `ChannelData` lives under a [user](/concepts/users) or an [object](/concepts/objects) and stores channel-specific data to be used when that user or object is included as a recipient on a [triggered workflow](/send-notifications/triggering-workflows).

## Things to know about channel data

- For channel types that require channel data (such as [push](/integrations/push/overview) channels and [chat](/integrations/chat/overview) channels like Slack), the channel step will be skipped during a workflow run if the required `channel_data` is not stored on the recipient.
- Knock stores channel data for you but makes no assumptions about whether the stored channel data is valid. That means that if a push token expires, it's your responsibility to omit/update that token for future notifications.
  - For push providers, Knock offers an opt-in [token deregistration](/integrations/push/token-deregistration) feature that automatically removes invalid tokens from a recipient's channel data when messages bounce.
- Setting channel data always requires a `channel_id`, which can be obtained in the Dashboard under **Integrations** > **Channels**. A channel ID is always a UUID v4.

## Setting channel data

Before getting or setting channel data, you must first configure that channel in your environments. You can do this inside the Knock dashboard under **Integrations** > **Channels**. Once the channel for which you want to store channel data has been created, you're ready to store the channel data for your users and objects.

There are three ways of setting channel data for a given recipient:

1. Explicitly using the set channel data method
2. Inline through a workflow trigger
3. When identifying a recipient

<AccordionGroup>
  <Accordion title="Explicitly setting for Users">
    You can set channel data for a given user using the `users.setChannelData` method. Please note that the channel data will always be overwritten with each `set` call.

    In the example below, we're setting a user's device token when they download our mobile app so we can send them push notifications. If this token wasn't set for the user, they wouldn't receive push notifications from our notification workflows.

    <MultiLangCodeBlock
      snippet="users.setChannelData"
      title="Set channel data for a User"
    />

  </Accordion>
  <Accordion title="Explicitly setting for Objects">
    You can set channel data for a given object using the `objects.setChannelData` method. Please note that the channel data will always be overwritten with each `set` call.

    In the example below, we're setting an object's Slack channel ID and access token, presumably after a user in our product has decided to connect the object to their Slack workspace. This enables us to send Slack notifications to the connected Slack channel when an event is triggered within the scope of the object.

    <MultiLangCodeBlock
      snippet="objects.setChannelData.slack"
      title="Set channel data for an Object"
    />

    You can learn more about objects in our [concept guide](/concepts/objects) and [API reference](/reference#objects).

  </Accordion>
  <Accordion title="Setting channel data inline">
    For both user and object recipients, channel data can be specified inline during a [workflow trigger call](/send-notifications/api#identifying-recipients-inline).

    When setting channel data inline for a recipient entity, you must supply the channel data as a dictionary containing the channel ID as a key, and a dictionary of channel data to set for that channel.

    <MultiLangCodeBlock
      snippet="workflows.trigger-with-user-channel-data"
      title="Trigger workflow with inline channel data"
    />

  </Accordion>
  <Accordion title="Setting channel data on an identify request">
    For both [user](/reference#identify-user) and [object](/reference#set-object) recipients, channel data can be specified as a recipient property on an identify request.

    When setting channel data for a recipient entity on an identify request, you must supply the channel data as a dictionary containing the channel ID as a key, and a dictionary of channel data to set for that channel. The below example is for a `User`, but the same pattern can be followed for an `Object`.

    <MultiLangCodeBlock
      snippet="users.identifyChannelData"
      title="Identify a User with channel data"
    />

  </Accordion>
</AccordionGroup>

## Getting channel data

To retrieve the currently set channel data, you can use the `getChannelData` method on `users` and `objects`. If
channel data is not set for the recipient you'll receive a `404` response.

<AccordionGroup>
  <Accordion title="Getting channel data for a User">
    <MultiLangCodeBlock
      snippet="users.getChannelData"
      title="Get channel data for a User"
    />
  </Accordion>
  <Accordion title="Getting channel data for an Object">
    <MultiLangCodeBlock
      snippet="objects.getChannelData"
      title="Get channel data for an Object"
    />
  </Accordion>
</AccordionGroup>

## Clearing channel data

Any previously set channel data can be cleared by issuing an `unsetChannelData` call. Unsetting channel data for a recipient requires a valid channel ID to be passed.

<Callout
  emoji="🔁"
  text={
    <>
      <strong>Token deregistration.</strong> For push providers, Knock can
      automatically remove invalid tokens from a recipient's channel data when
      messages bounce. Learn more about this opt-in feature in our{" "}
      <a href="/integrations/push/token-deregistration">
        token deregistration guide
      </a>
      .
    </>
  }
/>

<AccordionGroup>
  <Accordion title="Unset channel data for a User">
    <MultiLangCodeBlock
      snippet="users.unsetChannelData"
      title="Unset channel data for a User"
    />
  </Accordion>
  <Accordion title="Unset channel data for an Object">
    <MultiLangCodeBlock
      snippet="objects.unsetChannelData"
      title="Unset channel data for an Object"
    />
  </Accordion>
</AccordionGroup>

## Provider data requirements

Channel data requirements for each provider are listed below. Typically `channel_data` comprises a `token` or other value that is used to uniquely identify a user's device.

### Push channels

<AccordionGroup>
  <Accordion title ="APNs (Apple Push Notification Service)">
    | Property | Type       | Description               |
    | -------- | ---------- | ------------------------- |
    | tokens\* | `string[]` | One or more device tokens |
    
  </Accordion>
  <Accordion title ="FCM (Firebase Cloud Messaging)">
    | Property | Type       | Description               |
    | -------- | ---------- | ------------------------- |
    | tokens\* | `string[]` | One or more device tokens |

  </Accordion>
  <Accordion title ="Expo">
    | Property | Type       | Description               |
    | -------- | ---------- | ------------------------- |
    | tokens\* | `string[]` | One or more device tokens |

  </Accordion>
  <Accordion title ="OneSignal">
    | Property     | Type       | Description            |
    | ------------ | ---------- | ---------------------- |
    | player_ids\* | `string[]` | One or more player_ids |

  </Accordion>
</AccordionGroup>

### Chat app channels

<AccordionGroup>
  <Accordion title ="Slack">
    | Property    | Type                | Description                      |
    | ----------- | ------------------- | -------------------------------- |
    | connections | `SlackConnection[]` | One or more connections to Slack |

    A `SlackConnection` can have one of two schemas, depending on whether you're using standard Slack OAuth scopes or an incoming webhook.
    We cover Slack app scopes in detail in our [Slack scopes guide](/in-app-ui/react/slack-kit).

    If you're using standard Slack OAuth with access token scopes, your `SlackConnection` schema looks like this. You'll use
    either a `channel_id` or `user_id` depending on whether you're storing connection data to message a channel or user in Slack:

    | Property     | Type     | Description        |
    | ------------ | -------- | ------------------ |
    | access_token | `string` | A bot access token |
    | channel_id   | `string` | A Slack channel ID |
    | user_id      | `string` | A Slack user ID    |

    If you're using a Slack app with the `incoming-webhook` scope your `SlackConnection` schema is quite simple:

    | Property             | Type     | Description                                                                 |
    | -------------------- | -------- | --------------------------------------------------------------------------- |
    | incoming_webhook.url | `string` | The Slack incoming webhook URL (to be used instead of the properties above) |

  </Accordion>
  <Accordion title ="Discord">
    | Property    | Type                  | Description                        |
    | ----------- | --------------------- | ---------------------------------- |
    | connections | `DiscordConnection[]` | One or more connections to Discord |

    A `DiscordConnection` has the following schema:

    | Property             | Type     | Description                                                                   |
    | -------------------- | -------- | ----------------------------------------------------------------------------- |
    | channel_id           | `string` | A Discord channel ID                                                          |
    | incoming_webhook.url | `string` | The Discord incoming webhook URL (to be used instead of the properties above) |

  </Accordion>
  <Accordion title ="Microsoft Teams">
    | Property    | Type                  | Description                        |
    | ----------- | --------------------- | ---------------------------------- |
    | connections | `MsTeamsConnection[]` | One or more connections to MsTeams |

    An `MsTeamsConnection` can have one of two schemas, depending on whether you're using a Microsoft Teams bot or an incoming webhook.

    If you're using a Microsoft Teams bot, your `MsTeamsConnection` schema looks like this. You'll use either
    `ms_teams_channel_id` or `ms_teams_user_id` depending on whether you're storing connection data to message
    a channel or user in Microsoft Teams:

    | Property            | Type     | Description                    |
    | ------------------- | -------- | ------------------------------ |
    | ms_teams_tenant_id  | `string` | A Microsoft Entra tenant ID    |
    | ms_teams_team_id    | `string` | A Microsoft Teams team ID      |
    | ms_teams_channel_id | `string` | A Microsoft Teams channel ID   |
    | ms_teams_user_id    | `string` | A Microsoft Teams user ID      |

    If you're using an incoming webhook, your `MsTeamsConnection` schema is quite simple:

    | Property             | Type     | Description                       |
    | -------------------- | -------- | --------------------------------- |
    | incoming_webhook.url | `string` | The Microsoft Teams incoming webhook URL (to be used instead of the properties above) |

  </Accordion>
</AccordionGroup>


## Deleting users
Learn more about how user deletions work within Knock and how deletion can help with data privacy controls.
---
title: Deleting users
description: Learn more about how user deletions work within Knock and how deletion can help with data privacy controls.
tags: ["right to be forgotten", "gdpr", "rtbf", "forgotten"]
section: Managing recipients
---

Knock provides a programmatic user deletion API that you can use to hard delete users and the data associated with users. This can be especially useful in fulfilling GDPR right-to-be-forgotten requests.

<Callout
  emoji="🚨"
  text={
    <>
      <strong>Note</strong>: deleting users is a destructive operation and once
      deleted, the data for that user <strong>cannot be recovered</strong>.
    </>
  }
/>

<MultiLangCodeBlock snippet="users.delete" title="Delete a user" />

## What data is deleted for a user?

When a user is deleted in Knock, we will **hard delete**:

- All system and custom properties set on the user
- All preferences associated with the user
- All channel data associated with the user
- All subscriptions associated with the user
- All schedules associated with the user
- All messages sent to that user, including the content of those messages and any debugging events associated
- All activity associated with a user, including the workflow run logs the user was a recipient of

**Note**: deletion requests can take up to 10 minutes to process. During this time, you may still see some data associated with the user.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I delete users from the Knock dashboard?">
    Yes, you can manually delete individual users from the Knock dashboard.
  </Accordion>
  <Accordion title="Is Knock GDPR compliant?">
    Yes, Knock is GDPR compliant.
  </Accordion>
  <Accordion title="Can I use the user deletion API to programmatically power GDPR right-to-be-forgotten requests?">
    Absolutely. You can use our single-user deletion endpoint, or batch up
    deletion requests per-day using our bulk delete endpoint.
  </Accordion>
  <Accordion title="I need to suppress a user from ever receiving notifications again from our platform, is that possible?">
    Please get in touch with us if you have this requirement.
  </Accordion>
  <Accordion title="If I delete a user and then re-use the identifier for that deleted user, what happens?">
    You can re-add the same user using the previous user's identifier. The new
    user will not inherit any of the past user's data, given that will have been
    deleted.
  </Accordion>
</AccordionGroup>


## Merging users
Learn more about merging user data.
---
title: Merging users
description: Learn more about merging user data.
section: Managing recipients
---

You might run into the scenario where you've identified an invited user to send them a notification and then that user "graduates" to a fully-fledged user after they sign up, leaving you with two users in Knock. That's where the merge users method comes in handy.

Merging two users will merge the `secondary` user (the invited user in our example) into the `primary` user (the signed-up user), and the secondary user will be deleted in the process.

<MultiLangCodeBlock snippet="users.merge" title="Merge two users together" />
<br />

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note</strong>: performing a merge is a destructive operation and
      cannot be undone.
    </>
  }
/>

### What's merged?

- **Properties**: Properties are deep merged, but if there are any conflicts between the secondary and primary user then the value is selected from the primary user.
- **Preferences**: Preference sets are shallow merged between the users. Any preference sets that don't exist on the primary from the secondary are added.
- **Channel data**: Channel data is shallow merged from the secondary to the primary. Any channel data that doesn't exist on the primary from the secondary is added, determined by the channel_id.
- **Message history**: The past 30 days of message history of the secondary user will now be owned by the primary recipient.
- **Activities**: Any activities from the past 30 days that the secondary user was an `actor` or `recipient` of will be transferred to the primary user.

If you need to retain more than 30 days worth of history, please contact us.



# Send notifications
Learn how to send and debug notifications using Knock.

## Triggering workflows

## Overview
Learn more about how to trigger cross-channel notification workflows in Knock.
---
title: Triggering workflows
description: Learn more about how to trigger cross-channel notification workflows in Knock.
tags: ["trigger", "notify", "data", "actor"]
section: Send notifications
---

Knock executes workflow runs when workflows are triggered. A workflow can be triggered in these ways:

- By a [direct API call](/send-notifications/triggering-workflows/api) to the `trigger` endpoint
- By a [source event](/send-notifications/triggering-workflows/events)
- On a [recurring, or one-off schedule](/send-notifications/triggering-workflows/schedules)
- When a user becomes [a member of an audience](/send-notifications/triggering-workflows/audiences)

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note:</strong> Recipients can opt out of notifications through
      preferences. Knock handles all preference-based opt-outs automatically.
      Learn more about <a href="/preferences/overview">preference management</a>
      {""}.
    </>
  }
/>

## Conditionally executing a workflow trigger

A trigger step can have one or more [step conditions](/designing-workflows/step-conditions) that determine if the workflow executes. When conditions evaluate to false, the workflow terminates and no other steps execute.

## Controlling workflow trigger frequency

Sometimes you need to limit how often a recipient runs through a workflow. For example, you might want an account signup workflow to run only once per recipient. Workflow trigger frequency controls this behavior.

Trigger frequency lets you set if a workflow should run every time or at most once per recipient. By default, workflows trigger every time for a recipient.

When you specify "Once per recipient" frequency, you can include the tenant in this control. This ensures your workflow triggers once per-recipient, per-tenant.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens when I trigger a workflow whose status is set to Inactive?">
    A workflow whose [status](/concepts/workflows#workflow-status) is set to
    `Inactive` will return a `workflow_inactive` [error](/reference#error-codes)
    when triggered and will not generate any workflow recipient runs.
  </Accordion>
</AccordionGroup>


## With the API
Learn more about how to trigger cross-channel notification workflows in Knock via the API.
---
title: Triggering workflows via the API
description: Learn more about how to trigger cross-channel notification workflows in Knock via the API.
tags: ["trigger", "notify", "data", "actor"]
section: Send notifications
---

The trigger API endpoint executes workflows for your recipients. When you call the `trigger` endpoint, Knock runs your specified [Recipients](/concepts/recipients) and `data` through the workflow.

<MultiLangCodeBlock
  snippet="workflows.trigger"
  title="Trigger a Knock workflow"
/>

Learn more about triggering workflows in [our API reference](/reference#workflows).

## Trigger payload

| Property         | Type                  | Description                                                                                                 |
| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| key\*            | string                | The human-readable key of the workflow from the Knock dashboard                                             |
| actor            | RecipientIdentifier   | An identifier of who or what performed this action (optional)                                               |
| recipients\*     | RecipientIdentifier[] | One or more recipient references of who/what to notify for this workflow                                    |
| data             | map                   | A map of properties that are required in the templates in this workflow                                     |
| cancellation_key | string                | A unique identifier to reference the workflow when canceling                                                |
| tenant           | string                | An optional identifier of the owning tenant object for the notifications generated during this workflow run |

## Recipient identifiers

When you want to identify a recipient in a workflow, either as an actor or as a recipient you can send either:

- A string indicating a user that you have previously identified to Knock (e.g. `user-1`).
- A reference of an object that you have previously set within Knock (e.g. `{ id: "project-1", collection: "projects" }`).
- A complete `Recipient`, to be identified inline during the workflow execution.

## Response

Triggering a workflow will always return a unique UUID v4 representing the workflow run.

```json title="Trigger workflow response"
{
  "workflow_run_id": "05f8a70d-e42a-46dc-86fa-aada5752f6cf"
}
```

<br />

<Callout
  emoji="💡"
  text={
    <>
      Note: a workflow run ID is a unique identifier that represents the
      workflow run for all recipients of the workflow. Each individual in the
      workflow run will have a unique workflow recipient run ID, which is
      derived from the workflow run id.
    </>
  }
/>

## Passing data to your trigger

Pass schema data required by the workflow in your `trigger` call. The payload must be a valid JSON object.

The workflow builder determines which data keys are required.

<Callout
  emoji="💡"
  text={
    <>
      For more information on validating trigger data and working with JSON
      schemas, see our guide on{" "}
      <a href="/developer-tools/validating-trigger-data">
        validating trigger data
      </a>
      .
    </>
  }
/>

## Attributing the action to a user or object

Pass an `actor` in your trigger call to attribute the workflow run to a specific user or object.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-actor"
  title="Triggering a Knock workflow with an actor"
/>

Calling a workflow trigger with an actor:

- Records who triggered the workflow
- Links the actor to any in-app feed messages
- Includes the actor in batch steps via the `actors` key
- Excludes the actor from notifications when they are a [subscriber](/concepts/subscriptions) to an Object recipient

## Generating a cancellation key

Include a `cancellation_key` in your `trigger` call to enable workflow cancellation.

You can read more about canceling workflows [in our guide](/send-notifications/canceling-workflows).

The key should uniquely identify the workflow run you want to cancel. We recommend using:

- A UUID v4
- A hash of relevant workflow data
- A timestamp combined with recipient and workflow identifiers

## Identifying recipients inline

You can pass a complete `Recipient` entity to the `recipients` or `actor` property when triggering a workflow. When passing the recipient, the recipients will be guaranteed to be identified **before** the workflow is triggered for the recipient with the properties passed in.

| Property        | Description                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `id`            | Required. An identifier for this user or object                                                        |
| `collection`    | Required when identifying an object. Indicates the collection the object belongs to                    |
| `channel_data`  | A dictionary containing a `channelId` key and a dictionary of channel data to be set for the recipient |
| `preferences`   | A dictionary containing a preference set ID key and a `PreferenceSet` object to set for the recipient  |
| `$trigger_data` | Any recipient-specific trigger data to merge in with the `data` available on the workflow run          |
| \*              | An arbitrary set of key/value pairs to set for the recipient                                           |

```json title="Example inline recipient definition"
{
  "id": "user-1",
  "name": "Jean Luc-Picard",
  "email": "jpicard@starfleet.org",
  "channel_data": {
    "4672d685-c586-4ec6-ad88-52185262af97": {
      "tokens": ["apns-push-token"]
    }
  },
  "preferences": {
    "default": {
      "channel_types": {
        "email": true,
        "sms": false
      }
    }
  }
}
```

## Per-recipient trigger data

You can pass per-recipient data to your trigger by passing a dictionary of data under the `$trigger_data` property for each recipient. Any data provided under this property will be merged with the data passed in the `data` property to produce the final data available for the recipient's workflow run.

```json title="Example per-recipient data"
{
  "data": {
    "role": "Lieutenant"
  },
  "recipients": [
    {
      "id": "jeanluc",
      "name": "Jean-Luc Picard",
      "$trigger_data": {
        "role": "Captain"
      }
    }
  ]
}
```

## Multi-tenancy in notifications

You can optionally pass a `tenant` to your `trigger` call. If you are a product that allows users to belong to multiple tenants,
you'll want to pass a `tenant` to Knock in your trigger calls so that you can make sure a given user's in-app feed is scoped to the
tenants to which they belong in your product.

You can read more about [supporting multi-tenancy in our guide](/concepts/tenants).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I trigger a workflow for a single recipient?">
    You can trigger a workflow for a single recipient by passing a single
    recipient identifier to the `recipients` property in your trigger call.
  </Accordion>
  <Accordion title="How do I trigger a workflow for multiple recipients?">
    You can trigger a workflow for multiple recipients by passing an array of
    recipient identifiers to the `recipients` property in your trigger call.
  </Accordion>
  <Accordion title="How do I trigger a workflow for an object?">
    You can trigger a workflow for an object by passing an object identifier to
    the `recipients` property in your trigger call.

    An object identifier looks like:

    ```json
    {
      "id": "project-1",
      "collection": "projects"
    }
    ```

  </Accordion>
  <Accordion title="How do I trigger a workflow for the subscribers of an object?">
    You can trigger a workflow for the subscribers of an object by passing an object identifier to the `recipients` property in your trigger call. Knock will automatically create a workflow run for each subscriber of the object.

    <MultiLangCodeBlock
      snippet="workflows.trigger-with-object-as-recipient"
      title="Workflow trigger with an object as a recipient"
    />

  </Accordion>
  <Accordion title="How do I trigger a workflow for an audience?">
    It's not yet possible to trigger a workflow for an audience via the API. If you're looking to trigger a workflow for a specific audience, please get in touch with us. We're currently considering how to best support this use case and would love to discuss your specific needs.
  </Accordion>
  <Accordion title="What's the maximum number of recipients I can trigger a workflow for?">
    You can trigger a workflow for up to 1000 recipients at a time. If you need to manage a larger list of recipients, you might want to consider using our [subscriptions feature](/concepts/subscriptions) to have Knock manage the set of recipients who need to be notified instead.
  </Accordion>
  <Accordion title="Can I bulk trigger workflows?">
    It's not currently possible to issue bulk trigger requests to the API. If you need to trigger workflows for multiple recipients with per-recipient data, you can pass per-recipient trigger data.
  </Accordion>
  <Accordion title="How do I cancel a workflow run?">
    You can cancel a workflow run by calling the `cancel` endpoint.

    <MultiLangCodeBlock
      snippet="workflows.cancel"
      title="Cancel a workflow run"
    />

  </Accordion>
  <Accordion title="Can I validate the data I'm passing to a workflow trigger?">
    Yes, you can [validate the data you're passing to a workflow trigger](/developer-tools/validating-trigger-data) by
    providing a JSON schema in your workflow trigger step.
  </Accordion>
</AccordionGroup>


## On a schedule
Learn more about how to trigger cross-channel notification workflows in Knock on a schedule.
---
title: Triggering workflows on a schedule
description: Learn more about how to trigger cross-channel notification workflows in Knock on a schedule.
tags: ["trigger", "notify", "data", "actor"]
section: Send notifications
---

Schedules allow you to express complex repeating schedules for your workflow triggers so that you can trigger workflows on a one-off or a recurring basis for one or more recipients.

You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

[Learn more about schedules](/concepts/schedules)

## Creating a schedule

You can create a workflow schedule via the API. Schedules cannot be created in the Knock dashboard.

```typescript title="Creating a schedule for multiple recipients"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

const schedules = await knock.workflows.createSchedules("park-alert", {
  recipients: ["jhammond", "esattler", "dnedry"],
  repeats: [
    // Repeat daily at 9.30am only on weekdays
    {
      frequency: "daily",
      days: "weekdays",
      hours: 9,
      minutes: 30,
    },
  ],
});
```

## Providing per-recipient schedule data

It's possible to provide per-recipient schedule data to your workflow runs by setting the `data` property on each schedule created via the API. When your schedule runs, the data provided will be set on the workflow run for each recipient.

## Reviewing scheduled workflow runs

You can see all scheduled workflow runs under the **Schedules** section of a given workflow. Please note that this tab will only display if there are recipient schedules configured for the workflow.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I set up a workflow to trigger on a schedule for all my users?">
    Yes, but you'll need to add each user to the schedule manually via the API.
    There's no way to automatically add all users to a schedule.
  </Accordion>
  <Accordion title="Can I trigger a workflow for a set of subscribers to an object?">
    No, it's currently not possible to trigger a workflow for a set of
    subscribers to an object.
  </Accordion>
</AccordionGroup>


## From an event
Learn more about how to trigger cross-channel notification workflows in Knock via an event.
---
title: Triggering workflows via an event
description: Learn more about how to trigger cross-channel notification workflows in Knock via an event.
tags: ["trigger", "source", "event", "segment", "cdp", "customer data platform"]
section: Send notifications
---

Events from customer data platforms like [Segment](/integrations/sources/segment) or direct HTTP webhook integrations trigger workflows.

Event-triggered workflows decouple notifications from your backend systems — enabling non-developers to set up and configure notifications based on business events in your product.

Event-triggered workflows require that you have one or more [Sources](/integrations/sources/overview) configured and connected to Knock.

## Configuring an event trigger

You can create and manage event triggers for your workflows in the **Sources** section (under **Developers** in the sidebar) or directly from the workflow builder when you click the "Trigger" step.

From the Trigger step sidebar, if you have events connected to Knock you'll see the option to switch the trigger type to "Event" from the dropdown menu. Once here, you can select an event that will trigger this workflow when it's received. You can also map the critical fields needed to run a workflow to the fields that will be in the incoming event payload.

[Learn more about sources](/integrations/sources/overview)

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I trigger a workflow for multiple recipients from a single event?">
    Yes, it's possible to override the default behavior of a source event
    trigger to point the trigger to a property on the event that resolves to a
    list of recipients.
  </Accordion>
  <Accordion title="Can I cancel a workflow run triggered by an event?">
    Yes, you can cancel any workflow that contains a pause step (batch, delay,
    or fetch function). The ability to cancel depends on the workflow structure,
    not how it was triggered. See our guide on [canceling
    workflows](/send-notifications/canceling-workflows) for details.
  </Accordion>
</AccordionGroup>


## For an audience (Beta)
Learn more about how to trigger cross-channel notification workflows in Knock via an audience.
---
title: Triggering workflows via an audience
description: Learn more about how to trigger cross-channel notification workflows in Knock via an audience.
tags: ["trigger", "audience"]
section: Send notifications
---

<Callout
  emoji="🚧"
  text={
    <>
      <strong>Note:</strong> Audiences is in beta. To request early access,{" "}
      <a href="mailto:support@knock.app?subject=Audiences beta access">
        contact us
      </a>
      .
    </>
  }
/>

Audience workflow triggers execute a workflow run when a user joins a specific audience.

An audience consists of users who share a common characteristic, such as users on a paid plan or users who made a purchase in the past 30 days.

To use audience triggers, you need an [audience](/concepts/audiences) created in Knock. Create an audience in the "Audiences" section of the dashboard.

## Configuring an audience trigger

Configure an audience trigger by selecting "Audience" trigger type in the workflow builder and selecting your target audience.

Remember: you must have an audience created in Knock before you can use it to trigger workflows.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I trigger a workflow to all users in an audience?">
    No, workflows trigger only for **new users** who join an audience.
  </Accordion>
  <Accordion title="Can I specify multiple audiences as a trigger source of a workflow?">
    No, a workflow accepts only one audience as its trigger source.
  </Accordion>
  <Accordion title="Can I trigger a workflow for a user who is removed from an audience?">
    No, workflows trigger only when users join an audience.
  </Accordion>
  <Accordion title="Can I prevent a workflow from being run if the user has already run through the workflow?">
    Yes, use the workflow trigger frequency setting to control if a workflow
    should trigger for users who have already completed the workflow.
  </Accordion>
</AccordionGroup>


## Canceling workflows
Learn more about canceling workflows in Knock and see code examples to get started.
---
title: Canceling workflows
description: Learn more about canceling workflows in Knock and see code examples to get started.
tags: ["cancellations", "cancellation_key", "cancel", "batch", "remove"]
section: Send notifications
---

Canceling a workflow allows you to stop a workflow run mid-execution. This action will stop the workflow from sending new messages to recipients. This can be useful in situations like reminder workflows, where a notification needs to be canceled once a user has performed an intended action.

Only workflows with a step that can pause the run can be canceled, since otherwise Knock will _immediately_ send a notification to your recipients. The three steps that can pause a workflow run are:

- [Batch functions](/send-notifications/designing-workflows/batch-function) will pause workflows while the batch window is open.
- [Delay functions](/send-notifications/designing-workflows/delay-function) will pause workflows for the configured delay window.
- [Fetch functions](/send-notifications/designing-workflows/fetch-function) may pause workflows during a [retry backoff](/send-notifications/designing-workflows/fetch-function#error-handling).

## Canceling a triggered workflow

To perform a cancellation, you first need to provide a `cancellation_key` in the [workflow trigger](/send-notifications/triggering-workflows) request. Knock will use this key to uniquely identify the triggered workflow for cancellation.

You can read about generating workflow cancellation keys and some best practices in the [triggering workflows guide](/send-notifications/triggering-workflows/api#generating-a-cancellation-key).

<MultiLangCodeBlock
  snippet="workflows.cancel"
  title="Canceling a triggered workflow"
/>

### Schema

| Property         | Type                  | Description                                                                    |
| ---------------- | --------------------- | ------------------------------------------------------------------------------ |
| key\*            | string                | The human readable key of the workflow from the Knock dashboard                |
| cancellation_key | string                | A unique identifier for the workflow run                                       |
| recipients       | RecipientIdentifier[] | A list of specific recipient identifiers to cancel the workflow for (optional) |

## Canceling for subsets of recipients

In some cases you may need to cancel a workflow for a subset of recipients only. You can do this by specifying the recipients list on the cancellation:

<MultiLangCodeBlock
  snippet="workflows.cancel-with-recipients"
  title="Canceling for subsets of recipients"
/>

## Gotchas and recommendations

There are a few fundamentals to consider when using workflow cancellations:

1. A cancellation cannot be performed on a specific channel step, it can only be performed against the _entire_ workflow.

2. You cannot cancel a given workflow run after it has finished. If you need to revoke messages for persistent channels like the in-app feed, then you can `archive` a message instead.

3. Workflow cancellations are both deferred and executed concurrently to the workflow run itself. The [cancel workflow API](/reference#cancel-workflow) will return a `204 No Content` response on success, but this only means Knock has successfully enqueued the cancellation request, _not_ that the cancellation has been performed. **We recommend against issuing a cancellation request within 5 seconds of a given workflow trigger**. Cancellations issued too soon after a workflow trigger may not cancel the intended target. Cancellations issued prior to a workflow trigger may overtake and cancel the subsequent workflow.

4. Canceling a workflow with a [batch step](/send-notifications/designing-workflows/batch-function) will not close the open batch window. Read more [here](/designing-workflows/batch-function#using-workflow-cancellation-with-batches).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I cancel a workflow run for a specific recipient if they were notified via an object subscription?">
    Yes, you can. Because workflow cancellation requests can be scoped to one or
    more specific recipients, you can target any recipient who was notified via
    an object subscription, even if that recipient was not explicitly included
    in the workflow trigger request.
  </Accordion>
</AccordionGroup>


## Delivering notifications
Learn how Knock sends in-app and out-of-app notifications to email, SMS, push, and chat channels (such as Slack).
---
title: Delivering notifications
description: Learn how Knock sends in-app and out-of-app notifications to email, SMS, push, and chat channels (such as Slack).
tags: ["delivery", "channels", "delivery status", "retry logic", "resilience"]
section: Send notifications
---

## Overview

When a workflow is executed, its [channel steps](/designing-workflows/channel-step) may produce zero or more messages for the workflow run's recipient. Each message is then sent to its channel's provider using Knock's resilient sending pipeline which handles retries and logging for you.

## Retry logic

### Send retries

We will retry sending notifications to the underlying provider when:

- There is an error contacting the provider (e.g. a network connection issue).
- The provider responds with a retryable error (e.g. server overloaded, rate limit exceeded).
- There is a transient error in our sending pipeline.

We will retry delivery up to **8 times over a 30-minute window**, utilizing an exponential back-off strategy with jitter.

We will also change the [message delivery status](/send-notifications/message-statuses#delivery-status) and emit corresponding [message events](/send-notifications/message-statuses#message-events) during this delivery lifecycle. You can expect to see:

- A `queued` status when the message has been enqueued for a delivery attempt.
- A `delivery_attempted` status when Knock has attempted delivery but the attempt has failed. The delivery may or may not be retried.
- A `bounced` status when the provider indicates a message has been bounced and Knock will not retry.
- An `undelivered` status when Knock has failed to deliver the message and will not retry (either retries have been exhausted or an unretryable error was encountered).

### Delivery status retries

For certain channel types where it is supported by the provider, we run [delivery status](/send-notifications/message-statuses#delivery-status) checks. In these cases, we poll the provider's API to try to confirm delivery.

On success, we update the message delivery status to `delivered`. We retry a delivery status check when:

- There is an error contacting the provider (e.g. a network connection issue).
- The provider indicates the request is retryable (e.g. there's no delivery status being presented yet).
- There is a transient error in the delivery status check pipeline.

For specific providers, on failure we will update the delivery status to `undelivered` or `bounced` depending on the error status. We will not retry a delivery status check in these cases.

We will retry delivery status checks up to **10 times over a 30-minute window,** utilizing an exponential back-off strategy with jitter.

## Sending logs and debugging

For all out-of-app providers you can find logs of the requests we make and the responses we receive under the "Logs" tab of an individual message in the dashboard. You can use these logs to understand any errors coming from the provider while we were executing your requests.

If you find an error that you cannot fix yourself, please contact [our support team](mailto:support@knock.app) for help.


## Message statuses
How to work with the Knock message statuses to understand notification delivery and engagement rates.
---
title: Message statuses
description: How to work with the Knock message statuses to understand notification delivery and engagement rates.
tags: ["delivery status", "engagement status", "delivery rates"]
section: Send notifications
---

Knock uses the [Message](/concepts/messages) model to represent a notification delivered to a recipient on a particular channel. Knock Messages can have one or more statuses, which indicate the delivery state of your notification or how your recipient is engaging with the message. Knock captures changes in message status as Message Events, which you can hook into with [outbound webhooks](/developer-tools/outbound-webhooks/overview).

Knock manages two types of notification statuses:

- **Delivery status** — Was the message successfully delivered to your messaging providers and to your recipient? Delivery statuses are mutually exclusive, hierarchical, and implicitly managed by Knock as part of notification delivery.
- **Engagement status** — How has your recipient engaged with the notification once received? A message can have multiple engagement statuses, or none. Knock will implicitly manage some engagement statuses for you, but you can also manage them yourself via the Knock API.

## Delivery status

When you trigger a Knock workflow, any channel step within that workflow generates a Message for each recipient. Once the message is generated, Knock manages delivery to the recipient via the downstream provider for your channel (e.g. SendGrid for email delivery). Knock uses delivery statuses to track this lifecycle and show you where a given message resides within it.

You can use the "Logs" tab in the message detail view in the Knock dashboard to examine the history of requests Knock makes to the downstream provider to determine delivery status. The "Delivery status" field will show you the current status for your message.

<figure>
  <Image
    src="/images/notifications/delivery-status-lifecycle.png"
    width={1993}
    height={1333}
    className="rounded-md mx-auto"
    alt="Knock message delivery status lifecycle"
  />
  <figcaption>
    Figure 1 — The Knock message delivery status lifecycle.
  </figcaption>
</figure>

Figure 1 above illustrates the full delivery status lifecycle. As the diagram implies, a message can only ever have one delivery status at a time. Plus, not all delivery statuses are available to all channels.

Lastly, delivery statuses are also hierarchical. Knock considers certain statuses more precedent than others when performing comparisons for things like [message status conditions](/designing-workflows/step-conditions#message-status-conditions).

Below we break down each status in detail (including any channel-specific limitations) in ascending order of precedence.

### 1) Undelivered

We attempted to deliver your message, we encountered an error, and _we will not retry delivery_. Your message has not made it from Knock to your provider.

You can use the message delivery logs to help debug what may have gone wrong between Knock and the downstream provider. See our guide on [message delivery retries](/send-notifications/delivering-notifications#retry-logic) for more details on how delivery attempts and retries at Knock work.

### 2) Bounced

Your message was successfully sent to the downstream provider, but the message was dropped by your provider due to bad recipient data, resulting in a bounce, and _we will not retry delivery_.

You can use the message delivery logs to help debug what may have gone wrong between Knock and the downstream provider. See our guide on [message delivery retries](/send-notifications/delivering-notifications#retry-logic) for more details on how delivery attempts and retries at Knock work.

### 3) Delivery attempted

We attempted to deliver your message, but we encountered an error. If we deem the error retryable and we have not hit our retry limit, we will re-enqueue the message for another delivery attempt.

You can use the message delivery logs to help debug what may have gone wrong between Knock and the downstream provider. See our guide on [message delivery retries](/send-notifications/delivering-notifications#retry-logic) for more details on how delivery attempts and retries at Knock work.

### 4) Queued

Your message has been created and has been queued to be sent to the provider. This may be the first attempt to deliver the message, or it may be a retry following an error. Messages sent outside a send window will remain queued until their scheduled send time.

### 5) Not sent

Your message was processed successfully but was not sent to the downstream provider because your channel is in [sandbox mode](/integrations/overview#sandbox-mode).

### 6) Sent

Your message has successfully made it from Knock to the delivery provider. It is their responsibility to ensure the message is properly _delivered_ to the recipient. Knock may be awaiting further information to determine if the message was successfully delivered.

On a per-channel level, `sent` means that:

- **Chat** — Your message has successfully been sent by Knock to the destination chat platform.
- **Email** — Your message made it to the delivery provider. We're waiting to learn if it made it to recipient.
- **In-app** — In-app messages automatically skip to the [`delivered`](#7-delivered) status. We always successfully deliver the message to the Knock Feed API.
- **Push** — Your message has successfully been sent by Knock to the destination push platform.
- **SMS** — Your message made it to the delivery provider. We're waiting to learn if it made it to recipient.
- **Webhook** — Webhook messages automatically skip to the [`delivered`](#7-delivered) status when Knock receives a `2xx`-status response from your endpoint.

### 7) Delivered

We've received confirmation from the delivery provider that your message was successfully sent to the recipient.

On a per-channel level, `delivered` means that:

- **Email** — Your message was successfully delivered to the recipient's email service provider.
- **In-app** — Your message was successfully delivered to the recipient's feed.
- **Push** — We do not support delivery tracking for push channels, so push channel messages will never have a delivery status greater than `sent`. However, you can introduce a handler into your mobile app to update a given message's [engagement status](#engagement-status) when the message has successfully made it to your recipient's device, using the `knock_message_id` from the push notification payload.
- **SMS** — Your message was successfully sent to the recipient's SMS provider. Note that not all SMS delivery providers support delivery tracking. See the [Knock integration guides for SMS providers](/integrations/sms/overview) for more information.
- **Chat** — Delivery tracking is not available for chat platforms, so chat channel messages will never have a delivery status greater than `sent`. In most cases, a `sent` status will also mean that the message has been delivered to the recipient.
- **Webhook** — Your message was successfully delivered to your webhook endpoint.

## Engagement status

Once delivered, Knock uses a set of engagement statuses to track how the recipient interacts with the notification. There are a few important things to note about how this works:

- **Engagement statuses are mutually inclusive.** Unlike delivery status, a message can have zero, one, or multiple engagement statuses. As an example, an in-app message can have an engagement status of both `seen` and `marked as read`.
- **Engagement statuses are hierarchical.** Like delivery status, engagement statuses have a concept of hierarchy. Knock sometimes uses this hierarchy when evaluating [message status step conditions](/designing-workflows/step-conditions#message-status-conditions).
- **Implicitly managed only sometimes.** In a couple cases, Knock will manage engagement status on your behalf. The [Knock React SDK](/in-app-ui/react/overview) will set engagement statuses for your in-app feed channels. Knock will also manage engagement statuses for any channel configured to use [Knock link and open tracking](/send-notifications/tracking). For other cases, you can use the [Knock Message status API](/reference#update-message-status) to explicitly manage engagement statuses yourself.

Knock will include the set of current engagement statuses for your message in API responses as a list under the `engagement_statuses` field. Knock also uses timestamp columns to model the latest such action for each engagement type.

Below we review the possible engagement statuses and various per-channel caveats for how they work.

### Seen

| Timestamp field | Badge  |
| --------------- | ------ |
| `seen_at`       | `seen` |

Knock only implicitly manages this status for the in-app feed channel.

The `seen` status indicates that the message has been retrieved for display in the recipient's in-app feed at least once. The timestamp represents the time of the most recent action. The `seen` status is separate from an [opened/read status](/send-notifications/message-statuses#2b-marked-as-read--opened-read_at-iso8601-timestamp), in that it doesn't indicate the recipient has explicitly interacted with the message itself.

### Marked as read / opened

| Timestamp field | Badge  |
| --------------- | ------ |
| `read_at`       | `read` |

The message has been opened and read by the recipient at least once. The timestamp represents the time of the most recent action.

Knock will implicitly manage this status only for the following channel configurations:

- **Email** — [Knock open tracking](/send-notifications/tracking) needs to be enabled.
- **In-app** — When you're using the [Knock ReactFeedProvider SDK](/in-app-ui/react/feed).
- **Push** — Not currently supported.
- **SMS** — Not directly supported. But, if [Knock link tracking](/send-notifications/tracking) is enabled, we will count a link-click action as also an open event.
- **Chat** — Not directly supported. But, if [Knock link tracking](/send-notifications/tracking) is enabled, we will count a link-click action as also an open event.
- **Webhook** — Not currently supported.

### Link clicked

| Timestamp field                     | Badge          |
| ----------------------------------- | -------------- |
| `link_clicked_at` -or- `clicked_at` | `link_clicked` |

A link within your message was clicked by the recipient. The timestamp represents the time of the most recent action.

Knock will implicitly manage this status only for the following channel configurations:

- **Email** — [Knock link tracking](/send-notifications/tracking) needs to be enabled.
- **In-app** — [Knock link tracking](/send-notifications/tracking) needs to be enabled for link-clicks to count towards this status. In addition, for in-app messages where the message is itself a link, message clicks will also count. (Note: that clicking “mark all as read” does not result in a message being marked as clicked; rather, as the phrasing implies, we bulk update the message engagement statuses to opened/read.)
- **Push** — Not currently supported.
- **SMS** — [Knock link tracking](/send-notifications/tracking) needs to be enabled.
- **Chat** — [Knock link tracking](/send-notifications/tracking) needs to be enabled.
- **Webhook** — Not currently supported.

### Interacted

| Timestamp field | Badge        |
| --------------- | ------------ |
| `interacted_at` | `interacted` |

Knock only implicitly manages this status for the in-app feed channel.

For the in-app feed case, this indicates that your recipient has explicitly clicked on the notification cell in their feed. The timestamp represents the time of the most recent action.

### Archived

| Timestamp field | Badge      |
| --------------- | ---------- |
| `archived_at`   | `archived` |

Knock only implicitly manages this status for the in-app feed channel.

The message has been archived by the recipient. The timestamp represents the time of the most recent action.

## Message events

Knock records each change in message status, whether delivery or engagement, as a message event. You can view these events in chronological order of occurrence in the message timeline view in the Knock dashboard. Knock also uses these message events to power webhooks. See our [guide on outbound webhooks](/developer-tools/outbound-webhooks/overview) to learn more about how you can hook into the Knock message status lifecycle.


## Link & open tracking
How to use Knock tracking to extend your ability to observe user engagement from right within your Knock account.
---
title: Link and open tracking
description: How to use Knock tracking to extend your ability to observe user engagement from right within your Knock account.
tags: ["link tracking", "open tracking", "open rates", "link clicks"]
section: Send notifications
---

## Overview

Knock provides opt-in, provider-agnostic tracking capabilities for your notifications. These are:

- **Link tracking** — Knock will wrap URLs in your notification and capture link-click events before directing your recipient to the destination.
- **Open tracking** — Currently for email channels only. Knock uses a 1x1 transparent "tracking pixel" to determine when a recipient opens and reads your email notifications.

Many of the providers Knock integrates with offer their own versions of open and link tracking. You can configure your channels to use provider-owned tracking in these cases.

With Knock tracking, you get the same features with cross-channel tracking events surfaced as first-class entities in a single place: your Knock account.

### Availability

<table>
  <thead>
    <tr>
      <th>Channel</th>
      <th>Link tracking available?</th>
      <th>Open tracking available?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Email</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>In-app feed</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>Push</td>
      <td>❌</td>
      <td>❌</td>
    </tr>
    <tr>
      <td>SMS</td>
      <td>✅</td>
      <td>❌</td>
    </tr>
    <tr>
      <td>Chat</td>
      <td>✅</td>
      <td>❌</td>
    </tr>
    <tr>
      <td>Webhook</td>
      <td>❌</td>
      <td>❌</td>
    </tr>
  </tbody>
</table>

## Configuring Knock tracking

You can configure Knock tracking on a per-environment basis, using your channel's [per-environment configurations](/integrations/overview#per-environment-configurations). Open and link tracking will always default to `OFF` when you first create a channel.

<figure>
  <Image
    src="/images/notifications/knock-tracking-channel-configuration.png"
    alt="Configuring Knock tracking for an email channel"
    className="rounded-md mx-auto border border-gray-200"
    width={500}
    height={536}
  />
  <figcaption>Configuring Knock tracking for an email channel.</figcaption>
</figure>

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">
        In-app feed channels do not have an open tracking configuration option.
      </span>{" "}
      In-app feed open tracking is enabled implicitly whenever you use the{" "}
      <a href="/in-app-ui/react/feed">
        <code>KnockFeedProvider</code> component
      </a>
      . If you're building your own in-app feed view with a Knock SDK, then you'll
      need to manage open tracking yourself by manually marking messages as read.
    </>
  }
/>

### Step-level overrides

You can also configure Knock tracking on a per-workflow level. If a channel step in your workflow supports Knock tracking, you'll see tracking option toggles just below the channel selector form in the workflow editor. These toggles will reflect the environment-level channel configurations you have set until you modify them otherwise.

Step-level overrides allow you to opt-out of tracking for a specific workflow step, or vice versa.

<figure>
  <Image
    src="/images/notifications/knock-tracking-step-level-overrides.png"
    alt="Configuring Knock tracking for a workflow step"
    className="rounded-md mx-auto border border-gray-200"
    width={1218}
    height={635}
  />
  <figcaption>Configuring Knock tracking for a workflow step.</figcaption>
</figure>

## Working with Knock tracking

### Message events

Knock tracking events will be available in the message detail view in the Knock Dashboard.

When open tracking is enabled for an email channel, Knock will capture email-open actions as `message.read` events. You'll see a "Read at" timestamp reflecting the time of latest open event and a "Message read" item in the timeline view for each open action.

When link tracking is enabled, Knock will capture link-click actions as `message.link_clicked` events. You'll see a "Clicked at" timestamp reflecting the time of the latest link-click event and a "Message link clicked" item in the timeline view for each link-click action.

### Link-click trigger conditions

When link tracking is enabled for your channel, you can stitch link-click events into your workflows as a step condition. For example, you can require that at least one link in a previous channel step has been clicked for the current step to execute.

See the [step conditions guide](/designing-workflows/step-conditions) for more details.

### Knock Webhooks

If you use Knock's outbound webhooks, you can hook into the `message.read` and `message.link_clicked` events captured via Knock tracking. See the [outbound webhooks guide](/developer-tools/outbound-webhooks/overview) for more details.

## How it works

### Link-click tracking

When Knock renders a workflow step template into a notification message, it will additionally wrap URLs as trackable links. When a recipient opens one of these trackable links, Knock will record a link-click event before redirecting the user to the target destination. Knock defers the link-click event capture process, so redirects should be fast.

Knock is able to identify many types of URLs for tracking:

- **Hyperlinks** — Knock will replace HTML anchor tag and Markdown link target URLs with trackable links.
- **Chat app JSON** — Knock will traverse chat app JSON blobs (e.g. Slack Block Kit) and replace URL cards or anchor tags found within.
- **Bare URLs** — In Markdown templates, Knock will replace full-form URLs with trackable links wrapping the origin URL. For example, `https://foobar.com/` would become `[https://foobar.com/](<knock-trackable-link>)`.

There are two types of trackable links Knock may generate: standard and short. Standard links encode the target URL (and other event metadata) into a variable-length token added to the link path. Short links instead use a lookup key added to the link that maps to a record of the target URL. The short link lookup key will always be 10-characters in length, with short links always 31-characters long in total.

Given their brevity and consistent length, Knock will use short links for channels that often have character constraints. Specifically these are:

- All SMS channels
- WhatsApp chat channel

### Link-click tracking domains

In all cases, Knock trackable links will use one of the following domains:

- `https://c.knock.app/`
- `https://c1.knock.app/`
- `https://c2.knock.app/`
- `https://c3.knock.app/`
- `https://c1.knoclick.com/`

### Email-open tracking

Knock uses a 1x1 transparent PNG image to power email open tracking, often called a "tracking pixel." When you enable open tracking for an email channel, we embed a link to this image in the footer of the email message. The URL to load the image contains an identifier we can use to associate the image with the notification. When your recipient opens the email and loads the image for view, we register an open event with the associated message.

#### Email-open tracking limitations

Using tracking pixels to record email-open events has limitations. For one, it requires your recipients to use an HTML-enabled email client. In addition, many contemporary email providers and applications provide robust user privacy protections that purposefully limit open tracking capabilities. Some providers automatically block remote content (including images); others will cache images after an initial request, limiting our ability to track repeat opens.

Knock tracking tries to capture email-open events in as many possible cases, while still respecting end-user privacy restrictions.

Here are the email open tracking limitations we are currently aware of:

<table>
  <thead>
    <tr>
      <th>Email provider / app</th>
      <th>Limitation</th>
      <th>Effect</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Mail.app (iOS & macOS)</td>
      <td>Optional remote content blocking</td>
      <td>When enabled by the recipient, open tracking will not work.</td>
    </tr>
    <tr>
      <td>iCloud Mail</td>
      <td>Remote content blocking</td>
      <td>
        This is enabled by default, and when enabled open tracking will not
        work.
      </td>
    </tr>
    <tr>
      <td>Gmail (Android, iOS, Web)</td>
      <td>Remote image caching</td>
      <td>
        Gmail may preload the image, registering a false open event. Repeat
        email opens may not register.
      </td>
    </tr>
    <tr>
      <td>Protonmail</td>
      <td>Remote image caching</td>
      <td>
        Images are always preloaded a single time following email delivery. Open
        tracking will not work.
      </td>
    </tr>
  </tbody>
</table>

## Video walkthrough

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.loom.com/embed/dec0e1f7371b456fbb0ebcd0036382b5"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>
<br />

## Frequently asked questions

<AccordionGroup>
  <Accordion title="My channel provider supports link or engagement tracking natively. What are the advantages of using Knock tracking?">
    Many of our [supported integrations](/integrations/overview) offer native link or engagement tracking that can be enabled in your Knock dashboard under that integration's [channel settings](/concepts/channels#channel-settings). Knock supports enabling these native tracking solutions alongside or instead of Knock tracking. 
    
    There are several Knock-tracking-specific features to keep in mind when configuring your channel's tracking settings:

    - **Cross-channel reporting.** Knock link and open tracking allows you to analyze user engagement across all of your delivery channels in a single tool.
    - **Step conditions.** With Knock tracking, you can use message engagement events to [power conditional logic in your workflows](/designing-workflows/step-conditions).
    - **Capture events via webhooks.** When Knock tracking is enabled, you can power other event-based flows in your product with Knock's [outbound webhooks](/developer-tools/outbound-webhooks/overview).

  </Accordion>
  <Accordion title="Can my provider report engagement metrics back to Knock?">
    No. While some providers offer native open and link tracking that can be enabled in your Knock dashboard under that integration's [channel settings](/concepts/channels#channel-settings), these native tracking solutions will not report back to Knock and do not enable the same functionality.
  </Accordion>
</AccordionGroup>


## Testing workflows
Learn more about how to test workflows you build in Knock.
---
title: Testing workflows
description: Learn more about how to test workflows you build in Knock.
tags: ["test", "testing", "CI", "continuous integration"]
section: Send notifications
---

Once you've built your workflow, you'll want to test it to make sure it works as expected. Knock provides a number of tools to help you test your workflows.

## The workflow test runner

You can use the Knock workflow test runner to test an end-to-end workflow and verify that it works as expected.

To use the workflow test runner, navigate to the workflow you want to test and click "Run a test." You'll have options to select the workflow's recipient, actor, tenant, and input any data that you'd like to pass to the workflow.

Two things to know about workflow test configuration:

- The data field is populated using the workflow's schema as defined in your templates. You can click "Reset" at any time to reset the data field to the latest and greatest schema for your workflow.
- The recipient and actor fields can contain either a [user](/concepts/users) or an [object](/concepts/objects). Use the toggle above the field to switch between these options.

When you run a test workflow, every step of the workflow will execute as it normally would. You'll see an affordance to "View log" when the workflow runs to see its output and what was sent. You can learn more about Knock logs and our debugger [here](/send-notifications/debugging-workflows).

You can also use the workflow test runner to run a test payload for a [source event trigger](/integrations/sources/overview#workflow-triggers). If your workflow is triggered by an event, you will automatically see a JSON payload of the last received event that you can use to run a test. You can edit this payload or click "Fetch the latest event" to get the most recent from your source.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Note:</span> The workflow test runner uses the
      last saved version of the workflow, not the last committed version. This
      means that you don't need to commit workflow changes before testing them
      using the test runner. This is different than calling the workflow with
      the API, which will always use the last committed version of the workflow.
    </>
  }
/>

## Testing workflows using the Knock CLI

You can also generate workflow runs using the `workflow run` command from the Knock CLI. You can learn more in our [CLI reference](/cli#workflow-run).


## Debugging workflows
Learn more about how to work with Knock's workflow debugger and API logs to easily debug your notification workflows.
---
title: Debugging workflows
description: Learn more about how to work with Knock's workflow debugger and API logs to easily debug your notification workflows.
tags: ["debugger", "logs", "errors"]
section: Send notifications
---

Sometimes you'll encounter issues with a workflow run that require more visibility into the Knock engine. Knock comes pre-built with a powerful workflow debugger that you can use to understand the state of individual workflow runs.

Using the workflow debugger, you can answer questions such as:

- What messages did this workflow run generate?
- Why did this step not produce any messages?
- Did this recipient have preferences set that opted them out from receiving a notification?
- What prevented this step from executing?

You can see a video of our workflow debugger in action here:

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.loom.com/embed/77c2a99f63914dda83abf6653b4711b8"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>

## Accessing the workflow debugger

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Data subject to retention policy enforcement.
      </span>{" "}
      See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

You can access the workflow debugger from our "Logs" page, which you'll find in the left hand environment sidebar in the dashboard. From there:

1. Find an API log that triggered a workflow run (**hint**: you can use the filters to find only workflow API requests)
2. In the right hand panel, click the "Workflow runs" tab
3. Select a workflow run for any recipient to view the debugger

**Note**: you can also use the debugger to look at test runs as well.



# Preferences
Learn how to power notification preferences with Knock.

## Overview
Learn how to implement notification preferences in Knock.
---
title: "Preferences overview"
description: "Learn how to implement notification preferences in Knock."
tags: ["recipients", "conditions", "prefs", "preferences"]
section: Preferences
---

[Preferences](/reference#preferences) enable your users to opt-out of the notifications you send using Knock.

## How preferences work

A user has a <a href="/reference#preferences">`PreferenceSet`</a>. A `PreferenceSet` is a JSON object that tells Knock which channels, categories, and/or workflows a user has opted out of receiving.

When Knock runs a workflow for a user, we evaluate their `PreferenceSet`. A message will not send if the user has opted out of receiving it.

A preference set is built using three keys: `categories`, `channel_types`, `workflows`. These keys resolve to boolean values to determine if a user has opted out of receiving a notification.

A few examples:

```json title="Unsubscribe user from admin category notifications"
{
  "categories": { "admin": false }
}
```

<br/>
```json title="Unsubscribe user from email notifications"
{
  "channel_types": { "email": false }
}
```
<br/>
```json title="Unsubscribe user from at-mention notifications"
{
  "workflows": { "mention": false }
}
```

You can combine these keys to create preference grids like the one in the image below:

```json title="A preference grid for categories and channels"
{
  "categories": {
    "collaboration": {
      "channel_types": {
        "email": true,
        "in_app_feed": true
      }
    },
    "project-updates": {
      "channel_types": {
        "email": false,
        "in_app_feed": true
      }
    }
  },
  "workflows": {
    "invoice-issued": {
      "channel_types": {
        "email": true
      }
    }
  }
}
```

The `PreferenceSet` above models this preference grid in your application:

<Image
  src="/images/what-is-knock/preferences.png"
  alt="An image of a preference set"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

<Callout
  mt={4}
  emoji="👩‍💻"
  text={
    <>
      <span className="font-bold">See an example.</span> Check out{" "}
      <a href="https://in-app-demo.knock.app/preferences" target="_blank">
        our interactive example app
      </a>{" "}
      to see how making changes to the preference center UI updates the values
      of a&nbsp;
      <code>PreferenceSet</code>
    </>
  }
/>

## Build your preference center

Before you start setting preferences for your users, you need to build a preference center in your application. A preference center is a place where users can manage their notification preferences.

There are four steps to building a preference center with Knock:

<Steps titleSize="h3">
  <Step title="Create a default PreferenceSet">
    A default preference set is the `PreferenceSet` users default to using when they first sign up for your product. Any users who don't have a preference set will default to using the default preference set. You can create a default preference set in the Knock dashboard under **Developers** > **Preferences**.

    <Image
      src="/images/concepts/preferences/preferences default set environment.png"
      alt="Creating a default preference set in Knock dashboard"
      width={1331}
      height={737}
      className="rounded-md mx-auto border border-gray-200"
    />


    The default preference set is environment-specific for testing purposes. You can copy the default preference set from one environment to another to keep your environments in sync.
    <Callout

    mt={4}
    emoji="💡"
    text={
    <>
    <span className="font-bold">A note on merging preferences</span>
    <p>
    If you create either a environment or tenant default{" "}
    <code>PreferenceSet</code> those preferences will be merged with changes
    a user makes in the UI, with the user-specified changes taking
    precedence.
    </p>
    </>
    }

/>

  </Step>
  {/* TODO: We need to scope and build this with Chris then can add this step. 
  <Step title="Create a PreferenceView">
    
    
    A `PreferenceView` defines the user-facing labels for any workflows or categories in your default preference set. This enables you to introduce new keys into your default preference set and have them update in your preference center, without needing to make changes within your codebase.

    You can create your `PreferenceView` in the Knock dashboard under **Developers** > **Preferences**. Your `PreferenceView` will be environment-specific for testing purposes. You can copy the `PreferenceView` from one environment to another to keep them in sync.

  </Step> */}
  <Step title="Get a user's preferences">
    {/* TODO add once we have pre-built react component for prefs
    You can use our pre-built React component to render your preference center in your application. Here's an example of how you can use the component:

    ```jsx
    TODO: We need this component built and documented.
    ``` */}

    Once you have your default `PreferenceSet` created, you will use the `getPreferences` method to retrieve a user's preferences for rendering in your application. If no preferences are set, this method will return the default preference set you created in the step above.

    <MultiLangCodeBlock
      title="Get preferences for a user"
      snippet="users.getPreferences"
    />

  </Step>
  <Step title="Render your preference center">
    {/* TODO add once we have pre-built react component for prefs
    You can use our pre-built React component to render your preference center in your application. Here's an example of how you can use the component:

    ```jsx
    TODO: We need this component built and documented.
    ``` */}

    Once you have loaded a user's preference, you'll need to render an interface in your application so they can update their notification preferences. Typically you encapsulate all of the getting and setting of preferences in a single component.

    You can see an example of this below, but our [quickstart guide on building preferences UI](/in-app-ui/react/preferences) provides an in-depth walkthrough of how to build a functional `PreferenceCenter` component.

```jsx title="A basic preference center"
<PreferenceCenter />
```

<Image
  src="/images/concepts/preferences/preference-center.png"
  alt="A basic preference center"
  width={1184}
  height={714}
  className="rounded-md mx-auto border border-gray-200"
/>

  </Step>
  <Step title="Set a user's preferences">
    When a user makes changes to their preferences in your application, you will use the `setPreferences` method to save those changes back to Knock.

    <MultiLangCodeBlock
      title="Set preferences for a user"
      snippet="users.setPreferences"
    />

  </Step>
</Steps>
    You can learn more about rendering preferences to users in your application in the [Building In-app UI](/in-app-ui/overview) section of our documentation:
<SdkCardGroup>
  <SdkCard
    title="Quickstart: Preference UIs in React"
    linkUrl="/in-app-ui/react/preferences"
    icon="react"
    languages={["React"]}
    isExternal={false}
  />
  <SdkCard
    title="Javascript SDK preference reference"
    linkUrl="/sdks/javascript/reference#preferences"
    icon="javascript"
    languages={["JavaScript"]}
    isExternal={false}
  />
</SdkCardGroup>

## Merging preferences

When a default `PreferenceSet` exists for an environment or tenant, Knock will merge all applicable preferences for a recipient when evaluating whether or not to send a notification. Any preferences set at the recipient-level will take precedence in the merge.

## Preference evaluation rules

When a workflow is triggered, Knock will evaluate the preferences for each `recipient` of the workflow and send notifications for each channel step in the workflow based on that evaluation. There are some important rules and caveats to consider:

<AccordionGroup>
  <Accordion title="General preference rules">
    - If you do not set a preference for a given channel, workflow, or workflow category, Knock defaults them to `true`.
  </Accordion>
  <Accordion title="Resolving preference conflicts">
    Knock only sends a notification if all preference combinations that exist on the recipient evaluate to `true`.

    - A workflow can belong to multiple `categories`. Only one of those category preferences needs to evaluate to `false` for the notification not to send.
    - If a workflow's `category` is set to `false`, the notification will not send even if a `channel_type` on the workflow is explicitly set to `true`.

  </Accordion>
  <Accordion title="Debugging preferences">
    Our [Preferences API](/reference#preferences) provides endpoints for retrieving all of the preferences that have been set on a recipient.

    You can also use the [workflow debugger](/send-notifications/debugging-workflows) in your dashboard to view the preferences that were evaluated for the recipient on a given workflow run.

    <Image
      src="/images/concepts/preferences/workflow-preferences-evaluation.png"
      alt="An image of a workflow run's evaluated preferences"
      width={500}
      height={381}
      className="mx-auto rounded-md border border-gray-200"
    />

  </Accordion>
</AccordionGroup>
## Bulk set user preferences

You can update the preferences of up to 1000 users in a single batch by using the `users.bulkSetPreferences` method. This executes an asynchronous job which will overwrite any existing preferences for the users provided. You can track the progress of the `BulkOperation` returned via the [bulk operation API](/reference#bulk-operations).

<MultiLangCodeBlock
  title="Bulk set preferences for many users"
  snippet="users.bulkSetPreferences"
/>

<br />

## Advanced concepts

- [Per-tenant preferences.](/preferences/tenant-preferences) In multi-tenant B2B applications, an advanced use case is customer admins who want to set the tenant-level default `PreferenceSet` for new users within their tenant.
- [Object preferences](/preferences/object-preferences). In the guide above, we referred to user preferences. You can also set preferences for objects.
- [Preference conditions](/preferences/preference-conditions). You can build advanced conditions and store them on Knock’s preference model to power use cases such as per-resource muting (example: mute notifications about this task) or threshold alerts (example: only notify me if my account balance is below $5).
- Workflow overrides. If you need to override a recipient's notification preferences to send notifications like a password reset email, you can override the preferences model. To do this, go to your workflow, click "Manage workflow," and enable "Override recipient preferences." You will need to commit this change for it to take effect. When enabled, the workflow will send to all of its channels, regardless of the recipient's preferences.


## Tenant preferences
Learn how to enable your customer admins to set default preferences for users in their tenant.
---
title: Tenant preferences
description: Learn how to enable your customer admins to set default preferences for users in their tenant.
tags:
  [
    "tenant",
    "tenant preferences",
    "per-tenant preferences",
    "per tenant preferences",
    "preferences",
  ]
section: Preferences
---

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Per-tenant
      user preferences and tenant preference defaults are only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

You can use tenant preferences to enable your customers' admins to create a tenant-specific default `PreferencesSet` for users in their tenant.

If you're a B2B application or a multi-tenant SaaS product, you can use tenant preferences to allow your customers to set default preferences for their users. For example, in Slack, your notification preferences are set _per Slack workspace_ (that is, per-tenant), not as global preferences that apply across all of your Slack workspaces.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Terminology callout.</span> This guide assumes
      you know about tenants in Knock and what they do. If you're new to
      tenants, we recommend reading our concept guide on{" "}
      <a href="/concepts/tenants">tenants</a> before continuing.
    </>
  }
/>

## Overview

Here is how tenant preferences work and the steps you'll take to implement them:

1. Enable your tenant admins to create a default `PreferenceSet` for their tenant.
2. Enable your users to override that tenant default `PreferenceSet` with their own preferences.
3. Trigger your workflows with a `tenant` parameter to apply tenant-specific preferences.

## Create a per-tenant default `PreferenceSet`

You set the default `PreferenceSet` for a tenant via the API by calling the `tenants.set` method. The preferences should follow the format of a recipient <a href="/reference#preferences"><code>PreferenceSet</code></a>.

```javascript title="Set the default preferences for a tenant"
import { Knock } from "@knocklabs/node";
const knock = new Knock(process.env.KNOCK_API_KEY);

const preferences = {
  workflows: {
    "new-comment": {
      channel_types: {
        email: false,
        sms: true,
        chat: false,
      },
    },
  },
};

await knock.tenants.set("tenant-id", {
  settings: {
    preference_set: preferences,
  },
});
```

## Set a per-tenant user `PreferenceSet`

A `PreferenceSet` has an `id`. When you [set a given user's preferences](/reference#set-preferences-user) in Knock, you'll use the `default` ID to apply the preferences universally for the user. When using one of our [SDKs](/sdks/overview), the `default` preference set is used if you don't provide an `id`.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Terminology clarification.</span> You'll
      encounter "default" in a few places in the Knock preferences model:
      <br />
      <ol>
        <li>
          At the environment-level when you set your default{" "}
          <code>PreferenceSet</code> for all users.
        </li>
        <li>
          At the tenant-level when you set the default{" "}
          <code>PreferenceSet</code> for all users in a tenant.
        </li>
        <li>
          At the user-level when you set a user's <code>PreferenceSet</code>{" "}
          without providing a tenant ID.
        </li>
      </ol>
    </>
  }
/>

<br />

```javascript title="Set tenant preferences for a user"
import { Knock } from "@knocklabs/node";
const knock = new Knock(process.env.KNOCK_API_KEY);

await knock.users.setPreferences(
  "user-id",
  {
    channel_types: {
      email: true,
      sms: false,
      chat: true,
    },
  },
  {
    preferenceSet: "tenant-id",
  },
);
```

You can also get a user's tenant-specific preferences.

```javascript title="Get tenant preferences for a user"
import { Knock } from "@knocklabs/node";
const knock = new Knock(process.env.KNOCK_API_KEY);

const preferences = await knock.users.getPreferences("user-id", {
  preferenceSet: "tenant-id",
});
```

## Trigger per-tenant workflows

When you trigger a workflow run, you pass a `tenant` parameter to tell Knock which tenant in your application the workflow is executing for.

```javascript title="Trigger a workflow with a tenant"
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

await knock.workflows.trigger("workflow-name", {
  tenant: "spotify",
});
```

The Knock workflow engine uses that `tenant` parameter to evaluate the user's `PreferenceSet`. If the user has a tenant-specific preference set, Knock uses that to determine whether to send the notification. If the user does not have a `tenant`-specific preference set, Knock uses the tenant's default preference set.

## Tenant preference evaluation rules

Here are a few things to keep in mind when using tenant preferences.

- When executing a workflow trigger, passing in a `tenant` will automatically load that tenant's default `PreferencesSet` (if one exists) for all recipients of the workflow. These tenant-level defaults will override a recipient's own `default` preferences.
- If the recipient has any per-tenant preferences set for that `tenant.id`, they will override the tenant-level default preferences.
- If there is no default `PreferenceSet` on the tenant AND the recipient has no per-tenant preferences set, the recipient’s `default` id `PreferenceSet` will be used. As always, the recipient's `default` preferences are [merged](/preferences/overview#preference-evaluation-rules) with the environment-level preference defaults.


## Object preferences
A guide to storing preferences on objects.
---
title: Object preferences
description: A guide to storing preferences on objects.
tags: ["object preferences", "preferences"]
section: Preferences
---

You can set a `PreferenceSet` on an object, just as you would for a user.

<MultiLangCodeBlock
  title="Set preferences for an object"
  snippet="objects.setPreferences"
/>

<br />

<MultiLangCodeBlock
  title="Get preferences for an object"
  snippet="objects.getPreferences"
/>


## Preferences conditions
Power advanced conditional logic in your preferences.
---
title: Preference conditions
description: Power advanced conditional logic in your preferences.
tags: ["preference conditions"]
section: Preferences
---

Preference conditions are [Knock condition models](/concepts/conditions) that are evaluated when computing the current state of your preferences during workflow execution.

## Overview

Typically, a `PreferenceSet` evaluates to boolean values representing whether your recipient has opted in or out of receiving notifications on a given channel, workflow, or category.

With preference conditions you can add additional custom expressions to a `PreferenceSet`, where the notification is only sent if all preferences (including every condition in the preference `conditions` list) evaluate to `true` at runtime.

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">Batch processing limitation.</span> When using
      a <a href="/designing-workflows/batch-function">batch function</a>,
      preference conditions for subsequent channel steps will only be evaluated
      against the first activity in the batch.
    </>
  }
/>

Below is an example of a workflow preference that has conditions applied to determine if the preference is `true` or `false`:

```json title="An example of preferences with conditions"
{
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "conditions": [
        {
          "variable": "recipient.muted_dinos",
          "operator": "not_contains",
          "argument": "data.dino"
        }
      ]
    }
  }
}
```

## Set preference conditions for a user

Here's how to set preference conditions for a user.

<MultiLangCodeBlock
  title="Set preferences with conditions for a user"
  snippet="users.setPreferences.conditions"
/>

<br />

<Callout
  mt={4}
  emoji="👩‍💻"
  text={
    <>
      <span className="font-bold">See an example.</span> Follow this{" "}
      <a
        href="https://github.com/knocklabs/knock-node-example-app/blob/main/db/seeds.ts#L103"
        target="_blank"
      >
        link
      </a>{" "}
      to see an example of how to set preferences with conditions.
    </>
  }
/>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where can I use preference conditions?">
    A condition can be applied at different points in the preference set:

    - Inside `workflows`, `categories`, or `channel_types` preferences
    - Inside an individual `workflows[workflow].channel_types` preference
    - Inside an individual `categories[category].channel_types` preference

  </Accordion>
  <Accordion title="How do I debug preference conditions?">
    Knock will capture conditions evaluation details for all preference conditions resolved while executing your workflows. See the [guide on debugging conditions](/concepts/conditions#debugging-conditions) for more info.
  </Accordion>
  <Accordion title="Can I use multiple conditions on a single preference?">
    Yes. You can use multiple conditions within a single preference `conditions` array. Note that all conditions in the array must evaluate to `true` in order for the notification to be sent; this is a logical `AND` operation.

    ```json title="An example of multiple conditions on a single preference"
    {
      "conditions": [
        {
          "variable": "recipient.muted_dinos",
          "operator": "not_contains",
          "argument": "data.dino"
        },
        {
          "variable": "recipient.id",
          "operator": "not_equal_to",
          "argument": "actor.id"
        }
      ]
    }
    ```

  </Accordion>
  <Accordion title="Can I set OR conditions on a preference?">
    No, this is not currently supported. Each condition in the `conditions` array must evaluate to `true` for a notification to be sent.
  </Accordion>
</AccordionGroup>



# Building in-app UI
Use the Knock in-app experiences APIs and components to build rich notifications experiences inside of your product.

## Overview
Learn more about what in-app UI experiences you can build in Knock with our APIs and SDKs.
---
title: Building in-app UI with Knock
description: Learn more about what in-app UI experiences you can build in Knock with our APIs and SDKs.
section: Building in-app UI
---

<Image
  src="/images/in-app-ui/in-app-message-components.png"
  alt="In-app messaging"
  className="rounded-md mx-auto border border-gray-200"
  width={1828}
  height={793}
/>

In addition to delivering to out-of-app channels such as email, push, SMS, and chat apps like Slack, you can also use Knock to build great in-app notifications experiences too.

You can power any kind of in-app message with Knock, whether it’s transactional messages such as in-app feeds, notification centers, or toasts, or promotional messages such as banners, modals, or tags.

Knock enables you to deliver these in-app messages to your users **in your own native product UI**, while the **content** of those messages is drafted from the Knock dashboard. Knock also provides an orchestration layer to determine **who** receives those messages, **how often** they receive them, and where in your native product UI those messages are rendered.

Knock differs from other customer messaging platforms by separating the **content and presentation** of in-app messages, all while providing the orchestration engine and infrastructure to deliver them.

[See a live demo](https://in-app-demo.knock.app/)

## How Knock powers in-app messages

<Image
  src="/images/in-app-ui/how-knock-powers-in-app.png"
  width={1302}
  height={884}
  className="rounded-md mx-auto"
  alt="How Knock powers in-app messages"
/>

In-app messages in Knock are generated when a workflow runs for a recipient. Those in-app messages are available via our client API, which your application uses to fetch messages and update their state (seen, read, interacted with, archived).

In-app messages encode **content**, which is created using the [Knock template editor](/designing-workflows/template-editor/overview) as part of creating a workflow. You can read more on working with in-app message templates below.

The Knock in-app API also provides filtering capabilities to only return messages with a particular status (unread, read, seen etc) or custom property (sent as the data payload in the workflow trigger). You can also sort responses from the Knock in-app API by priority, for cases where you only want to display one in-app message to a user at a time. This makes it possible to build highly customized in-app experiences within your product

Clients connect to the in-app real-time service, which receives notifications over a websocket when new messages are sent to an in-app channel. This is a managed service provided by Knock.

## Why build in-app experiences on Knock?

- **Real-time ready.** Our in-app API comes ready with websocket support, no infrastructure setup required.
- **No data modeling required.** We handle all of the common cases for you: accurate badge counts, polymorphic notifications, read, seen and archive tracking, and much more.
- **Build holistic experiences.** Use the Knock workflow builder to create cross-channel notification experiences to power cases like "send to the in-app feed, if they don't see the feed message within 5 minutes then fallback to sending an email."
- **Complete APIs that are easy to use.** We take all of the heavy lifting out of building APIs to support common in-app notification experiences, like preferences and feeds.
- **Drop-in components.** We have components ready to help you get started with building in-app notification experiences in React.
- **Fully customizable.** Whether you want to build a feed, toasts, a full-page inbox experience, or notifications that match your style guide, it's easy to customize the experience by overriding styles, or components, or building your own headless UI using our lower-level primitives.

## Client SDKs available

We have the following SDKs available to use to build in-app notification experiences:

- [React (Web)](/in-app-ui/react/overview)
- [JS (Non-React Web)](/in-app-ui/javascript/overview)
- [React Native](/in-app-ui/react-native/overview)
- [Swift (iOS / macOS)](/in-app-ui/ios/overview)
- [Kotlin (Android)](/in-app-ui/android/overview)
- [Flutter (Android/iOS)](/in-app-ui/flutter/overview)

Under each client SDK, you'll find guides and references to help you get started.

## Pre-built UI components

Our client SDKs for React, React Native, iOS, and Android ship with pre-built components to power real-time, in-app notification feeds within your application.

Additionally, our React SDK for the web also ships with prebuilt components to:

- Render `<Banner />`, `<Card />`, and `<Modal />` messaging components.
- Easily integrate Slack authentication and channel selection to power Slack notifications.

## Using Knock in a headless way

In addition to the pre-built components that we ship, it's also possible to [use Knock in a headless way](/in-app-ui/react/custom-notifications-ui) by using our lower-level primitives. Doing so means you get to leverage the full power of Knock's in-app messaging infrastructure while having the flexibility to build your own UI components.

## Going to production

You'll need to follow our checklist on [going to production](/guides/implementation-guide#going-to-production) for any in-app notifications using Knock. Most importantly you'll need to [secure your requests to the Knock API for each user](/in-app-ui/security-and-authentication).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I have multiple in-app channels?">
    Yes, you can. By default, Knock will create a single in-app channel for you,
    but you can easily add additional in-app channels should you need to support
    multiple feeds or different types of in-app message experiences.
  </Accordion>
  <Accordion title='Can I "pin" or "favorite" messages in the in-app feed?'>
    Currently you can't pin messages. The feed will only return messages in
    reverse chronological order with no way to change that order. You can,
    however, create multiple feed instances and use [feed
    filtering](/in-app-ui/api-overview#filtering-in-app-notifications) to build
    a pinned notifications UI.
  </Accordion>
</AccordionGroup>


## API endpoints
Learn more about the capabilities of Knock's in-app APIs and real-time services, and how these can power robust in-app notification experiences with little effort.
---
title: In-app APIs and real-time service
description: Learn more about the capabilities of Knock's in-app APIs and real-time services, and how these can power robust in-app notification experiences with little effort.
section: Building in-app UI
tags:
  [
    "FeedItem",
    "MessageContent",
    "actionable notifications",
    "real-time delivery",
    "in-app notifications",
    "in-app messages",
    "in-app feed",
    "in-app channel",
    "in-app API",
    "in-app SDK",
  ]
---

Knock provides a complete set of APIs to render your in-app notifications with the Knock-powered in-app channel. These APIs cover:

- Fetching a reverse chronological list of in-app feed messages for a user. ([API reference](/reference#get-feed)).
- Retrieving badge count information on the number of seen and unread messages a user has.
- Handling message engagement statuses to mark messages as seen, read, and archived.
- Real-time delivery of in-app messages from Knock to your user.

Our client-side SDKs wrap these APIs and provide a convenient way to interact with the Knock APIs.

## Security model

Knock's in-app APIs are accessible via our client SDKs, which use your public API key to authenticate. In addition, we support an enhanced security mode that signs a request against the current user and provides an additional authorization mechanism. You can read more in [our security documentation](/in-app-ui/security-and-authentication).

## Real-time delivery

Knock provides a real-time web socket connection for your users to subscribe to new messages being produced on an in-app channel. The events we currently send over the web socket are:

| Event         | Description                                                                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `new-message` | Emitted when a new message is produced over an in-app channel. Will not contain the full message contents, but will include metadata about the updated badge counts. Might be throttled. |

## Filtering in-app notifications

It's possible to pass filters to the in-app messages endpoint. This allows you to:

- Only return in-app messages for a particular tenant
- Only return archived or unarchived messages
- Filter messages by the `data` payload used to trigger the notification

You can see the full set of available filters in the [endpoint documentation](/reference#get-feed).

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note:</strong> by default all <code>archived</code> messages are
      excluded from the feed.
    </>
  }
/>

Please note, by default all `archived` messages are not displayed.

## In-app API response

### `FeedMetadata`

<Attributes>
  <Attribute
    name="total_count"
    type="number"
    description="The total number of messages the user has for this in-app channel."
  />
  <Attribute
    name="unread_count"
    type="number"
    description="The total number of unread items the user has on the in-app channel."
  />
  <Attribute
    name="unseen_count"
    type="number"
    description="The total number of unseen items the user has on the in-app channel."
  />
</Attributes>

### `FeedItem`

Requests to the feed endpoint will return an array of `FeedItems`. Each feed item includes:

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the item."
  />
  <Attribute
    name="actors"
    type="Recipient[]"
    description="One or more actors that were attributed to the workflow run."
  />
  <Attribute
    name="total_actors"
    type="number"
    description="The total count of unique actors includes across all workflow runs that generated this message."
  />
  <Attribute
    name="activities"
    type="Activity[]"
    description="One or more activities associated with this in-app message. Will only include multiple activities when the message was generated from a batch."
  />
  <Attribute
    name="total_activities"
    type="number"
    description="The total count of workflow runs that generated this message. Will only be > 1 when used with a batch."
  />
  <Attribute
    name="activities"
    type="Activity[]"
    description="One or more activities associated with this in-app message. Will only include multiple activities when the message was generated from a batch."
  />
  <Attribute
    name="data"
    type="Record<string, any>"
    description="The combined workflow run data associated with this message. See below for more information."
  />
  <Attribute
    name="blocks"
    type="ContentBlock[]"
    description="The rendered contents of each feed item. See below for more information."
  />
  <Attribute
    name="source"
    type="WorkflowSource"
    description="The key, version_id, and categories of the workflow that generated this in-app message."
  />
  <Attribute
    name="tenant"
    type="string"
    description="An optional tenant identifier that was set in the workflow run scope."
  />
  <Attribute
    name="archived_at"
    type="utc_datetime"
    description="An optional tenant identifier that was set in the workflow run scope."
  />
  <Attribute
    name="read_at"
    type="utc_datetime"
    description="When set, indicates the last time the message was marked as read."
  />
  <Attribute
    name="seen_at"
    type="utc_datetime"
    description="When set, indicates the last time the message was marked as seen."
  />
  <Attribute
    name="link_clicked_at"
    type="utc_datetime"
    description="When set, indicates the last time the message was clicked."
  />
  <Attribute
    name="inserted_at"
    type="utc_datetime"
    description="The time the message was generated."
  />
  <Attribute
    name="updated_at"
    type="utc_datetime"
    description="The time the message was last updated."
  />
</Attributes>

### Message content blocks (`ContentBlock`)

Each in-app message will contain the contents of the message template that was used to generate the message, which you can use to display your in-app notifications. You'll find this content under the `blocks` attribute on each `FeedItem` returned. Each block includes:

Each `ContentBlock` is one of: `MarkdownContentBlock`, `TextContentBlock`, `ButtonSetContentBlock` defined by the `type` attribute.

#### `MarkdownContentBlock`

Represents a markdown content block that will have rendered HTML content.

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="A unique key for the block."
  />
  <Attribute
    name="rendered"
    type="string"
    description="The rendered liquid content as HTML."
  />
  <Attribute
    name="content"
    type="string"
    description="The markdown liquid template string."
  />
  <Attribute name="type" type="markdown" description="The type of block." />
</Attributes>

#### `TextContentBlock`

Represents a plaintext content block.

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="A unique key for the block."
  />
  <Attribute
    name="rendered"
    type="string"
    description="The rendered liquid content as plaintext."
  />
  <Attribute
    name="content"
    type="string"
    description="The plaintext liquid template string."
  />
  <Attribute name="type" type="text" description="The type of block." />
</Attributes>

#### `ButtonSetContentBlock`

Represents a set of one or more buttons that can be rendered in the in-app message.

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="A unique key for the block."
  />
  <Attribute
    name="buttons"
    type="ActionButton[]"
    description="A list of buttons to render in the block."
  />
  <Attribute name="type" type="button_set" description="The type of block." />
</Attributes>

Each button set block will contain an array of `ActionButton` objects. Each button includes:

<Attributes>
  <Attribute
    name="name"
    type="string"
    description="One of primary or secondary."
  />
  <Attribute
    name="label"
    type="string"
    description="The label to show on the button."
  />
  <Attribute
    name="action"
    type="string"
    description="The URI for this action."
  />
</Attributes>

### Passing through data

When triggering a workflow that generates an in-app message, all of the `data` in the workflow run scope will be included in the generated in-app message payload. This makes it possible to pass through identifiers from your system to your in-app notifications that you can then use to render custom UI elements.

Here's an example: if you trigger a workflow with `{ "project_id": "proj_123" }` which generates an in-app message, you can expect the `data` in the `FeedItem` to include this `project_id`.

### Customizing in-app API responses

It's also possible to override the response of the in-app API to hide sensitive data using an allow/deny list. You can [read more on doing so here](/integrations/in-app/knock#customizing-api-response-content).

## Message statuses

All messages returned from the in-app channel adhere to our message status and engagement APIs. That means it's possible to programmatically mark the messages as seen, read, interacted with, or archived. You can read more in our [message status documentation](/send-notifications/message-statuses), or read more on how we use these message statuses [on the in-app channel](/integrations/in-app/knock#how-the-knock-in-app-feed-uses-status).

## Working with actionable notifications

In-app notification messages (`FeedItem`) are "actionable" and can be one of three types:

- **Standard**: indicates that the entire cell is potentially actionable (e.g., clicking anywhere on the cell will trigger an action).
- **Single-action**: indicates that the notification cell has a single action button that can be clicked.
- **Multi-action**: indicates that the notification cell has both a primary and secondary set of actions that can be clicked.

Working with actionable notifications is straightforward. If you're using out-of-the-box Knock UI components, we'll handle the rendering of actionable notifications for you.

If you're building a custom feed implementation, you can check the `blocks` attribute for the presence of a `ButtonSetContentBlock` and render the `buttons` contained within the block accordingly.


## Security & authentication
Learn more about how to secure your client-side applications as they integrate with Knock.
---
title: Security & authentication
description: Learn more about how to secure your client-side applications as they integrate with Knock.
section: Building in-app UI
tags:
  [
    "jwt",
    "signing keys",
    "missing_user_token",
    "user token",
    "enhanced security mode",
  ]
---

<Callout
  emoji="👉"
  text={
    <>
      <span className="font-bold">Note:</span> This integration guide references
      examples from our{" "}
      <a href="https://github.com/knocklabs/javascript/tree/main/packages/client">
        client-side JS SDK
      </a>
      . You only need to add the authentication outlined in this guide if you're
      integrating Knock on the client side of your applications to use the Knock
      in-app feed or the Knock preferences model.
    </>
  }
/>

Access to Knock's API is protected using a secret API key for your backend application, and a public API key for your client application.
By default, the public API key can read in-app feeds and manage user preferences for any of your users. While this is convenient for testing and development, this is not suitable for production environments.

Production environments should enable **enhanced security mode**, which requires clients to send both the public API key and a signed user token that identifies the user that is performing the request. Enhanced security mode trades convenience for security, and we recommend that you enable it [when going to production](/guides/implementation-guide#going-to-production).

## API endpoints that can be called with a public API key

Public API keys can make the following calls from your client application:

- Fetching a user's notification feed
- Marking a feed message as read, seen, or archived
- Getting or setting a user's preferences

When enhanced security mode is enabled, calls from your client application will need to include both the public API key as well as a **signed user token**.

## Authentication (without enhanced security)

In a non-production Knock environment, you can use your public key to authenticate
all users. You do not need to implement any other security mechanisms. Knock will
not reject requests that do not include a signed user token.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Note:</span> This approach is convenient for
      development and testing, but should not be used in a production
      environment with real user data.
    </>
  }
/>

**Client SDK example**

```js
import Knock from "@knocklabs/client";

const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);

// Tell Knock to use the users id
knockClient.authenticate(currentUser.id);
```

**React notification feed example**

```jsx
<KnockProvider
  apiKey={process.env.KNOCK_PUBLIC_API_KEY}
  userId={currentUser.id}
>
```

## Authentication (with enhanced security)

When enhanced security mode is enabled, Knock will reject requests from the client using your public API key that **do not include a signed user token**. This token must be generated by your backend application and is used to authenticate a user's requests to Knock using your public API key.

Using our JWT-based authentication approach means using a shared secret to sign a new JWT on your
backend. This means you can generate the authentication token out-of-band without an additional network request.

### 1. Generate the signing key

You can find the signing key in the Knock dashboard under the **Developers** > **API keys** page. Save the private
key shown to you here. Note: you won't be shown this key again, so you'll need to regenerate
it if you lose access.

The Knock dashboard will present the generated private key in two formats:

1. Base-64 encoded PEM format, which fits on a single line (convenient for setting environment variables)
2. PEM encoded format, which may be required by certain libraries or platforms (visible under the "Advanced" disclosure)

By convention, we recommend storing the private key in the environment variable `KNOCK_SIGNING_KEY`. This is where the
Knock SDK will look for the key by default.

### 2. Sign the JWT

Within your backend application, you'll need to sign the JWT and make it available to your front-end
client. Usually, you'll do this by passing it down as a serialized property on the user or passing in a cookie.

Your JWT will need to be signed against your **private signing key** using an **RS256** algorithm. At a minimum, the JWT to be signed must contain:

```json
{
  // The user that you're signing the token for
  "sub": "user_id",
  // When the token was issued
  "iat": 1608600116,
  // Expiry timestamp
  "exp": 1608603716
}
```

To sign your JWT as middleware in a NodeJS express like app:

```js
import { Knock } from "@knocklabs/node";

app.use(async (req, res, next) => {
  if (!req.user) {
    return next();
  }

  // Assuming you have set KNOCK_SIGNING_KEY in your environment

  res.locals({
    // `signUserToken` can take a second argument to set the expiry of the token
    // and/or specify the signing key to use
    knockToken: await Knock.signUserToken(req.user.id),
  });

  next();
});
```

You can see more details on the options for the `signUserToken` method [in the docs](https://github.com/knocklabs/knock-node#signing-jwts).

### 3. Send the JWT to the client

In your client application, you can now use the JWT to authenticate with Knock:

**Client SDK example**

```js
import Knock from "@knocklabs/client";

const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);

// Tell Knock to use the user id and the token
knockClient.authenticate(currentUser.id, currentUser.knockToken);
```

**React notification feed example**

```jsx
<KnockProvider
  apiKey={process.env.KNOCK_PUBLIC_API_KEY}
  userId={currentUser.id}
  userToken={currentUser.knockUserToken}
>
```

## Handling token expiration

Generally, it's advisable to set the token expiration to be equal to your session token expiration. That way you can regenerate both of the tokens together from within your application. There may, however, be cases where this is not possible, in which case it's best practice to opt for a relatively short-lived expiration time for your user tokens and refresh them from your backend before the expiration window.

For convenience, the Knock JavaScript client and React package expose an `onUserTokenExpiring` callback method which will be invoked before the user token expires. This provides an easy hook for your application to refresh the user token from your backend.

At any time your application can call the `authenticate` method again with an updated user token and the connection to the Knock real-time service will be restarted.

## Avoiding authentication

You can avoid authentication altogether by proxying requests to Knock via your backend,
although we don't recommend this approach as it will add more latency for your users.

## Troubleshooting

### Errors using your Knock signing key

If you are getting errors like `secretOrPrivateKey must be an asymmetric key when using RS256`,
try using the base-64 encoded format of your signing key generated in the Knock Dashboard (under **Developers** > **API keys** > **Application Signing Keys**).

```bash
// .env.local
KNOCK_SIGNING_KEY="LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQoK..."
```


## Message types (Beta)
Learn more about working with in-app message types.
---
title: In-app message types
description: Learn more about working with in-app message types.
section: Building in-app UI
---

<Callout
  emoji="🚧"
  text={
    <>
      Message types are currently in beta. If you'd like early access, or this
      is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Message%20types">
        get in touch
      </a>
      .
    </>
  }
/>

Knock’s in-app message template system is built on our concept of Message Types. Within the Knock model, a message type represents a _type_ of message that you map to a UI component/element within your application to show to your users.

Knock comes with the following in-app messages types to use as message templates out-of-the-box, each of which maps to a component you’ll find in `@knocklabs/react`

- Banner (`<Banner />`)
- Modal (`<Modal />` )
- Card (`<Card />`)

Once a template type exists, you can use it in the [Knock in-app template editor](/designing-workflows/template-editor/overview):

<img
  src="/images/in-app-ui/message-types-template-editor.png"
  alt="In-app message types"
  className="rounded-md mx-auto border border-gray-200"
  width={1243}
  height={457}
/>

### Variants

Message types can have one or more _variants_. For example, the `card` template type comes with 3 variants:

- **Default**: content with an action URL to determine where the cell should route to.
- **Single action**: content with a single primary button.
- **Multi-action:** content with two buttons, one primary and one secondary.

When creating an in-app template, your content editors can select from the available variants and customize the message's contents based on the selected variant.

### Schemas

A schema defines _a message type and its variants._ The schema indicates the fields a message type will have in the template editor and forms the structure of the message contents generated when a message is produced from an in-app step.

You can think of the schema as a blueprint for how the content editor will create the message template and what fields they can edit within that experience.

The template type schema in Knock determines its template editing experience which governs the content that will be returned by the Knock API and rendered in your UI components.

<AccordionGroup>
  <Accordion title="A schema example">
    As an example, the `Banner` schema is defined as:

```json
{
  "variants": [
    {
      "key": "default",
      "name": "Default",
      "fields": [
        {
          "type": "text",
          "key": "title",
          "label": "Title",
          "settings": {
            "required": true,
            "description": null,
            "default": "Banner title",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "textarea",
          "key": "body",
          "label": "Body",
          "settings": {
            "required": true,
            "description": null,
            "default": "Copy about a feature or an action that the user should be aware of.",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "boolean",
          "key": "dismissible",
          "label": "Dismissible?",
          "settings": {
            "required": false,
            "description": null,
            "default": true
          }
        }
      ]
    },
    {
      "key": "single-action",
      "name": "Single-action",
      "fields": [
        {
          "type": "text",
          "key": "title",
          "label": "Title",
          "settings": {
            "required": true,
            "description": null,
            "default": "Banner title",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "textarea",
          "key": "body",
          "label": "Body",
          "settings": {
            "required": true,
            "description": null,
            "default": "Copy about a feature or an action that the user should be aware of.",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "boolean",
          "key": "dismissible",
          "label": "Dismissible?",
          "settings": {
            "required": false,
            "description": null,
            "default": true
          }
        },
        {
          "type": "button",
          "key": "primary_button",
          "label": "Primary button",
          "text": {
            "type": "text",
            "key": "text",
            "label": "Button text",
            "settings": {
              "required": true,
              "description": null,
              "default": "Primary",
              "minLength": null,
              "maxLength": null
            }
          },
          "action": {
            "type": "text",
            "key": "action",
            "label": "Button action",
            "settings": {
              "required": true,
              "description": null,
              "default": "action",
              "minLength": null,
              "maxLength": null
            }
          },
          "settings": {
            "required": true,
            "description": null
          }
        }
      ]
    },
    {
      "key": "multi-action",
      "name": "Multi-action",
      "fields": [
        {
          "type": "text",
          "key": "title",
          "label": "Title",
          "settings": {
            "required": true,
            "description": null,
            "default": "Banner title",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "textarea",
          "key": "body",
          "label": "Body",
          "settings": {
            "required": true,
            "description": null,
            "default": "Copy about a feature or an action that the user should be aware of.",
            "minLength": null,
            "maxLength": null
          }
        },
        {
          "type": "boolean",
          "key": "dismissible",
          "label": "Dismissible?",
          "settings": {
            "required": false,
            "description": null,
            "default": true
          }
        },
        {
          "type": "button",
          "key": "primary_button",
          "label": "Primary button",
          "text": {
            "type": "text",
            "key": "text",
            "label": "Button text",
            "settings": {
              "required": true,
              "description": null,
              "default": "Primary",
              "minLength": null,
              "maxLength": null
            }
          },
          "action": {
            "type": "text",
            "key": "action",
            "label": "Button action",
            "settings": {
              "required": true,
              "description": null,
              "default": "action",
              "minLength": null,
              "maxLength": null
            }
          },
          "settings": {
            "required": true,
            "description": null
          }
        },
        {
          "type": "button",
          "key": "secondary_button",
          "label": "Secondary button",
          "text": {
            "type": "text",
            "key": "text",
            "label": "Button text",
            "settings": {
              "required": true,
              "description": null,
              "default": "Secondary",
              "minLength": null,
              "maxLength": null
            }
          },
          "action": {
            "type": "text",
            "key": "action",
            "label": "Button action",
            "settings": {
              "required": true,
              "description": null,
              "default": "action",
              "minLength": null,
              "maxLength": null
            }
          },
          "settings": {
            "required": true,
            "description": null
          }
        }
      ]
    }
  ]
}
```

If the editor creates an in-app message template using the “default” variant for this component, then the structure of a generated message’s content will be:

```json
{
  "content": {
    "body": "<p>Hello this is my message</p>",
    "action_url": "https://knock.app"
  }
}
```

    </Accordion>

</AccordionGroup>

### Customizing message types

Each message type and its variants can be customized or removed entirely. You can also introduce completely new in-app message types to match your product's needs. This can be especially useful if you want to build custom in-app UI elements and power their content generation using Knock.

An in-app message schema has the following structure:

```json
{
  // One or more variants for this message type
  "variants": [
    {
      // A unique key for the variant (required)
      "key": "default",
      // A name for the variant, displayed in the message editor
      "name": "Default",
      // One or more fields for this variant
      "fields": []
    }
  ]
}
```

#### Variants

Your schema must have one or more variants. You can name your variants anything you would like, but the variant key must be unique.

Each variant must have:

- A `key` uniquely identifying the variant for the message type
- A `name` to display in the message template editor to select the variant
- One or more `fields` (see below)

#### Fields

All fields must have:

- `type`: The type of the field to render (see below)
- `key`: A unique key for the field in the variant
- `label`: A label to render

#### Field types

<AccordionGroup>
  <Accordion title="Text">
A plain text, single line text field.

**Settings**

- `required` (boolean): indicates this field is required
- `description` (string): an optional friendly description
- `default` (string): The default value to display
- `minLength` (integer): The minimum length to validate
- `maxLength` (integer): The maximum length to validate against

**Example**

```json
{
  "type": "text",
  "key": "title",
  "label": "Title",
  "settings": {
    "required": true,
    "default": "Card title",
    "minLength": 3,
    "maxLength": 32
  }
}
```

  </Accordion>
  <Accordion title="Markdown">
A markdown editor for creating rich text. Will always be rendered as HTML.

**Settings**

- `required` (boolean): indicates this field is required
- `description` (string): an optional friendly description
- `default` (string): The default value to display

```json
{
  "type": "markdown",
  "key": "body",
  "label": "Body",
  "settings": {
    "default": "**Default markdown**"
  }
}
```

  </Accordion>
  <Accordion title="Textarea">
A multi-line plain text area

**Settings**

- `required` (boolean): indicates this field is required
- `description` (string): an optional friendly description
- `default` (string): The default value to display
- `minLength` (integer): The minimum length to validate
- `maxLength` (integer): The maximum length to validate against

**Example**

```json
{
  "type": "textarea",
  "key": "body",
  "label": "Body",
  "settings": {
    "default": "My body"
  }
}
```

  </Accordion>
  <Accordion title="Boolean">
  A checkbox that returns either true or false (checked or unchecked).

**Settings**

- `required` (boolean): indicates this field is required
- `description` (string): an optional friendly description
- `default` (string): The default value to set

**Example**

```json
{
  "type": "boolean",
  "key": "dismissable",
  "label": "Can be dismissed?",
  "settings": {
    "default": true
  }
}
```

  </Accordion>
  <Accordion title="Select">
  A single select box that defines a static list of options for editors to pick from.

**Settings**

- `options` (object[]): A list of option objects that must include a `label` and a `value`
- `required` (boolean): indicates this field is required

**Example**

```json
{
  "type": "select",
  "key": "icon",
  "label": "Icon",
  "settings": {
    "options": [{ "label": "Skull", "value": "skull" }]
  }
}
```

  </Accordion>
  <Accordion title="Button">
    A button, with text to display and an action to perform when clicked.

    Every button field contains two subfields:

    - `text`: A text field that represents the button's text
    - `action`: A text field that represents the button's action

    **Settings**

    - `required` (boolean): indicates this field is required
    - `description` (string): an optional friendly description

    **Example**

    ```json
    {
      "type": "button",
      "key": "primary_button",
      "label": "Primary button",
      "text": {
        "type": "text",
        "key": "text",
        "label": "Button text",
        "settings": {
          "required": true,
          "default": "Learn more"
        }
      },
      "action": {
        "type": "text",
        "key": "action",
        "label": "Button action",
        "settings": {
          "required": true,
          "default": "https://example.com/"
        }
      },
      "settings": {
        "required": true
      }
    }
    ```

  </Accordion>
  <Accordion title="URL">
    **Settings**

    - `required` (boolean): indicates this field is required
    - `description` (string): an optional friendly description
    - `default` (string): The default URL to display

    **Example**

    ```json
    {
      "type": "url",
      "key": "contact_url",
      "label": "Contact link",
      "settings": {
        "required": true,
        "default": "https://example.com/"
      }
    }
    ```

  </Accordion>
  <Accordion title="Image">
    An image field, used to display an image with alt text and an optional action to perform when clicked.

    Every image field contains three subfields:

    - `url`: A URL field that represents the source of the image to be displayed
    - `alt`: A text field that represents the image's alt text
    - `action`: An optional text field that represents an action to perform when the image is clicked

    **Settings**

    - `required` (boolean): indicates this field is required
    - `description` (string): an optional friendly description

    **Example**

    ```json
    {
      "type": "image",
      "key": "hero_image",
      "label": "Hero image",
      "url": {
        "type": "url",
        "key": "url",
        "label": "Image URL",
        "settings": {
          "required": true,
          "default": "https://example.com/image.png"
        }
      },
      "alt": {
        "type": "text",
        "key": "alt",
        "label": "Image alt text",
        "settings": {
          "required": true,
          "default": "Lorem ipsum"
        }
      },
      "action": {
        "type": "text",
        "key": "action",
        "label": "Image action",
        "settings": {
          "required": true,
          "default": "https://example.com/"
        }
      },
      "settings": {
        "required": true
      }
    }
    ```

  </Accordion>
</AccordionGroup>

### Creating an in-app message template in Knock

To create an in-app message in Knock:

1. Add an in-app channel step to your workflow.
2. Select which message type to use for the in-app message (and its variant, if applicable).
3. Customize the contents of the in-app message in the template editor.

### Versioning in-app message types

Message types are versioned using Knock’s commit model, meaning changes to a message type schema are committed into the current environment. Workflows use the latest committed version of a message type.

### Triggering in-app messages

In-app messages are just another channel step within the Knock workflow builder, meaning that it’s possible to trigger an in-app message in the same way that you can trigger a workflow today:

- via the API
- via a source event being ingested
- via a recurring or one-off Schedule
- via a subscription to an object
- via being added to an audience

For more information, see the documentation for [triggering workflows](https://docs.knock.app/send-notifications/triggering-workflows).


## React

## Overview
Learn more about the in-app notifications experiences you can build in React with Knock. Easily power notification feeds, toasts, and inbox experiences.
---
title: "Building in-app UI in React"
description: Learn more about the in-app notifications experiences you can build in React with Knock. Easily power notification feeds, toasts, and inbox experiences.
section: Building in-app UI
---

Our [`@knocklabs/react`](https://github.com/knocklabs/javascript/tree/main/packages/react) library lets you create notification experiences using Knock's APIs. It comes with pre-built UI components that you can use to easily get up and running with a fully functional notification feed experience in your product.

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">New Knock React components.</span> If you're
      currently using <code>@knocklabs/react-notification-feed</code>, check out
      our{" "}
      <a href="/in-app-ui/react/migrating-from-react-notification-feed">
        migration guide
      </a>{" "}
      to learn how to use our new React library.
    </>
  }
/>

## Pre-built components

The Knock React SDK ships the following pre-built UI elements:

### In-app notifications

- `NotificationFeedPopover`: a managed popover for displaying a list of notifications.
- `NotificationFeed`: a full-page list of notifications.
- `NotificationIconButton`: for adding a bell icon to your application that shows the current count of unread or unseen notifications.

### SlackKit

- `SlackChannelCombobox`: for picking one or more Slack channels to route notifications to.
- `SlackAuthButton`: for managing the OAuth process between your Slack application and your customer's Slack workspace.

### TeamsKit

- `MsTeamsChannelCombobox`: for picking one or more Microsoft Teams channels to route notifications to.
- `MsTeamsAuthButton`: for managing the OAuth process between your Microsoft Teams bot and your customer's Microsoft Entra tenant.

## Hooks for headless UI

If you don't want to use the pre-built UI components, you can also use this library in a headless way and bring your own UI. The Knock React SDK includes a complete set of React hooks that you can use to build your own UI on top of.

## Guides

- [Integrating the `NotificationFeedPopover`](/in-app-ui/react/feed)
- [Real-time notification toasts](/in-app-ui/react/toasts)
- [Notification inbox](/in-app-ui/react/inbox)
- [Building custom notification UI using hooks](/in-app-ui/react/custom-notifications-ui)
- [Building a notification preferences page](/in-app-ui/react/preferences)

## Links

- [`@knocklabs/react` on npm](https://www.npmjs.com/package/@knocklabs/react)
- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Package on GitHub](https://github.com/knocklabs/javascript/tree/main/packages/react)
- [React SDK reference](/sdks/react/reference)
- [JS SDK reference](/sdks/javascript/reference)


## Notification feed
How to build an in-app notification feed using the drop-in React powered UI element.
---
title: "Building notification feeds with React"
description: How to build an in-app notification feed using the drop-in React powered UI element.
tags: ["inbox", "feeds", "toasts", "action_url"]
section: Building in-app UI
---

Our `@knocklabs/react` library comes pre-built with a real-time feed component that you can drop into your application. In this guide, you'll find common recipes to help you work with the pre-built Knock feed UI element.

[See a live demo of our pre-built in-app feed UI element ->](https://in-app-demo.knock.app/)

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Find your channel ID.</span> To find the
      channel ID for your in-app channel(s), go to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard,
      navigate to the channel page of your in-app channel, and copy the channel
      ID.
    </>
  }
/>

## Installing dependencies

```bash title="Installing dependencies"
npm install @knocklabs/react
```

## Rendering a notification feed (prebuilt UI element)

To add a real-time notifications feed to your product, you can use the out-of-the-box components that the `@knocklabs/react` library offers.

<Callout emoji="🔐"
  text={
    <>
      <span className="font-bold">Secure your feed: </span> By default, Knock
      feeds are accessible to anyone who has the feed ID. This makes it
      easy to get started in development. To secure your feed for production,
      enable enhanced security mode in your Knock dashboard and pass a signed
      {" "}<code>userToken</code> as a prop to the <code>KnockFeedProvider</code> component.

      For more information, visit <a href="/in-app-ui/security-and-authentication">the security & authentication guide</a>
      for client-side applications.
    </>

}
/>

```jsx
import { useState, useRef } from "react";
import {
  KnockProvider,
  KnockFeedProvider,
  NotificationIconButton,
  NotificationFeedPopover,
} from "@knocklabs/react";

// Required CSS import, unless you're overriding the styling
import "@knocklabs/react/dist/index.css";

const YourAppLayout = () => {
  const [isVisible, setIsVisible] = useState(false);
  const notifButtonRef = useRef(null);

  return (
    <KnockProvider
      apiKey={process.env.KNOCK_PUBLIC_API_KEY}
      userId={currentUser.id}
    >
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
        <>
          <NotificationIconButton
            ref={notifButtonRef}
            onClick={(e) => setIsVisible(!isVisible)}
          />
          <NotificationFeedPopover
            buttonRef={notifButtonRef}
            isVisible={isVisible}
            onClose={() => setIsVisible(false)}
          />
        </>
      </KnockFeedProvider>
    </KnockProvider>
  );
};
```

## Common recipes

### Building custom UI

You can build headless notifications UI on top of our hooks. [Learn more](/in-app-ui/react/custom-notifications-ui).

### Setting an `action_url` on the notification cell

You can pass a value in the Action URL field of your notification template and the `KnockFeedProvider` will attach a redirect handler if `action_url` is not empty.

### Adding an `onClick` handler to the notification cell

You can customize the click handler for the notification cell as follows:

```jsx
import { NotificationFeed } from "@knocklabs/react";

<NotificationFeed onNotificationClick={(item) => onClose()} />;
```

Both the `NotificationFeed` and the `NotificationFeedPopover` take a `onNotificationClick` prop.

### Add an `onButtonClick` handler to the notification cell

You can add a button click handler to respond to clicks on the buttons in the notification cell. The `onNotificationButtonClick` prop is available on the `NotificationFeed` component:

```jsx
import { NotificationFeed } from "@knocklabs/react";

<NotificationFeed
  onNotificationButtonClick={(item, button) => doSomething()}
/>;
```

### Rendering a different notification cell in the feed

You can customize the rendering of a notification cell in the feed by overriding the `renderItem` prop.

```jsx
import { NotificationFeed } from "@knocklabs/react";

const MyNotificationCell = ({ item, onItemClick }) => <Outer>...</Outer>;

<NotificationFeed renderItem={(props) => <MyNotificationCell {...props} />} />;
```

### Overriding the avatar

You can customize the `Avatar` component rendered within the `NotificationCell` by passing a different `avatar` component into the `NotificationCell` in the `renderItem` function passed to the feed:

```jsx
import { NotificationFeed, NotificationCell, Avatar } from "@knocklabs/react";

<NotificationFeed
  renderItem={({ item, ...props }) => (
    <NotificationCell
      {...props}
      item={item}
      // You can use any properties available on the `actor` for the name and avatar
      avatar={<Avatar name={item.actors[0].name} src={item.actors[0].avatar} />}
    />
  )}
/>;
```

### Using `read` instead of `seen` for the badge count

```jsx
import { NotificationIconButton } from "@knocklabs/react";

<NotificationIconButton onClick={...} badgeCountType="unread" />;
```

### Marking messages as read on the popover opening

```jsx
import { NotificationFeedPopover } from "@knocklabs/react";

const onOpen = ({ store, feedClient }) => {
  const unreadItems = store.items.filter((item) => !item.read_at);

  if (unreadItems.length > 0) {
    feedClient.markAsRead(unreadItems);
  }
};

<NotificationFeedPopover
  onOpen={onOpen}
  {...}
/>;
```

### Using dark mode

The feed supports an optional `colorMode` prop, that defaults to `light` but can be set as `dark` for dark mode support.

```jsx
import { KnockFeedProvider } from "@knocklabs/react";

<KnockFeedProvider colorMode="dark" />;
```

### Rendering custom components in a notification cell

For more advanced use cases, you may need to render custom components as part of the notification cell, but don't need to override the cell entirely. For this use case, you can use the `children` prop to render custom components inside the notification cell.

```jsx
import { NotificationFeed, NotificationCell } from "@knocklabs/react";

<NotificationFeed
  renderItem={({ item, ...props }) => (
    <NotificationCell {...props} item={item}>
      <MyCustomComponent />
    </NotificationCell>
  )}
/>;
```

### Handling cross-browser feed synchronization

The `Feed` optionally supports an `__experimentalCrossBrowserUpdates` option under the `defaultFeedOptions` which will opt into using a [BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) to keep multiple browser viewing contexts (windows, tabs) in sync for the same user feed.

You can see a demo of this behavior here:

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.loom.com/embed/2f6bcdd4f4e14f99b92e51a404be2563"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>

### Automatically disconnecting sockets from inactive tabs

Optionally, you can configure the `Feed` to disconnect socket connections with inactive tabs after a brief delay. If the tab becomes active again, the socket will reconnect to continue receiving real-time updates.

```jsx title="Automatically manage socket connections"
import { KnockFeedProvider } from "@knocklabs/react";

<KnockFeedProvider
  defaultFeedOptions={{
    // Turn on the automatic connection manager
    auto_manage_socket_connection: true,
    // Optionally, customize the delay amount in milliseconds. Defaults to 2000ms or 2s
    auto_manage_socket_connection_delay: 2500,
  }}
/>;
```

### Customizing the feed styling

The complete theme that controls the look and feel of the feed components can be customized for theme in a few different ways:

1. **Customizing the CSS variables**. The feed is written using CSS variables, which you can override to better match the look and feel of your product. The best way to see the possible CSS variables in use is to look at the [theme.css source code](https://github.com/knocklabs/javascript/blob/main/packages/react/src/theme.css).

2. **Bringing your own CSS**. It's possible to override the Knock CSS entirely to customize the look and feel of the feed. All of the feed classes are unique and start with `rnf-`. You can see the classes in use by looking at the [source code of the components](https://github.com/knocklabs/javascript/tree/main/packages/react/src).

### Setting custom translations

You can set custom translations for the components inside the feed by passing the `i18n` property to the `KnockProvider` component. You can provide a partial or full set of translations to be used [following the expected `I18nContent` type](/sdks/react/reference#i18ncontent).

**Note**: the default locale used in the components will be `en`. No other translations are provided out-of-the-box.

```jsx
import { KnockProvider } from "@knocklabs/react";

const YourAppLayout = () => {
  return (
    <KnockProvider
      apiKey={process.env.KNOCK_PUBLIC_API_KEY}
      userId={currentUser.id}
      i18n={{
        translations: {
          notifications: "Notifs",
          markAllAsRead: "Mark all as read!",
        },
        locale: "en",
      }}
    />
  );
};
```

### Filtering/scoping a feed

A feed can be scoped by any of the parameters that are accepted on the [feed endpoint](/reference#get-feed) via the `FeedClientOptions` set in the `defaultFeedOptions` for the `KnockFeedProvider` component, or via the `useNotifications` hook.

#### Status filtering

The NotificationFeed component provides built-in support for filtering notifications by status (e.g., All, Unread). You can set the initial filter status using the `initialFilterStatus` prop:

```jsx
import { NotificationFeed, FilterStatus } from "@knocklabs/react";

<NotificationFeed initialFilterStatus={FilterStatus.Unread} />;
```

The component manages its filter state internally and provides a default header with status filtering controls. If you need to customize the status filtering behavior, you can provide a custom header using the `renderHeader` prop.

You can read more in this [guide on feed filtering](/in-app-ui/react/filtering-in-app-feeds).

## Related links

- [`@knocklabs/react` library reference](/sdks/react/reference)
- [`@knocklabs/client` library reference](/sdks/javascript/reference)


## Messaging components (Beta)
How to build in-app messaging experiences like banners, cards, modals and more, powered by Knock and React.
---
title: "In-app messaging UI in React"
description: How to build in-app messaging experiences like banners, cards, modals and more, powered by Knock and React.
section: Building in-app UI
---

<Callout
  emoji="🚧"
  text={
    <>
      In-app messaging and message types are currently in beta. If you'd like
      early access, or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Message%20types">
        get in touch
      </a>
      .
    </>
  }
/>

<Image
  src="/images/in-app-ui/in-app-message-components.png"
  width={1828}
  height={793}
  className="rounded-md mx-auto border border-gray-200"
  alt="In-app messaging"
/>

Using our React SDK, it's possible to create in-app messaging experiences either using our pre-built components, or by building your own custom components on top of custom [in-app message types](/in-app-ui/message-types).

Note: this guide assumes that already have a Knock account with a configured in-app channel. If you haven't yet signed up for Knock, you can do so [here](https://dashboard.knock.app/signup).

## Using our pre-built components

The React library (`@knocklabs/react`) provides pre-built components that map to our out-of-the-box message types for `banner`, `card`, and `modal`.

You can use these components by dropping them into your application where ever you’d like them to display.

<Steps>
  <Step title="Setup the KnockProvider and KnockInAppMessagesChannelProvider">
    The `KnockProvider` is a React context provider that makes the Knock client SDK available to your application. The `KnockInAppMessagesChannelProvider` is a React context provider that makes the Knock in-app messages client in to your application.

```tsx
import { KnockProvider, KnockInAppMessagesChannelProvider } from "@knocklabs/react";

const MyApp = () => {
  return (
    <KnockProvider publicKey={process.env.KNOCK_PUBLIC_KEY} userId={currentUser.id}>
      <KnockInAppMessagesChannelProvider channelId={process.env.KNOCK_IAM_CHANNEL_ID}>
        <MyAppLayout>
      </KnockInAppMessagesChannelProvider>
    </KnockProvider>
  );
}
```

  </Step>
  <Step title="Mount one or more pre-built components">
    Mount one or more of the pre-built components (`<Banner />`, `<Card />`, `<Modal />`) under the `KnockInAppMessagesChannelProvider` in your application tree.

```tsx
import { Banner, KnockProvider, KnockInAppMessagesChannelProvider } from "@knocklabs/react";

const MyApp = () => {
  return (
    <KnockProvider publicKey={process.env.KNOCK_PUBLIC_KEY} userId={currentUser.id}>
      <KnockInAppMessagesChannelProvider>
        <MyAppLayout>
        <Banner />
      </KnockInAppMessagesChannelProvider>
    </KnockProvider>
  );
}
```

  </Step>
</Steps>

## Building custom components

In addition to the pre-built components, you can also write custom messaging components on top of our hooks and data layer. This makes it possible for you to create custom message types, and build custom messaging UI experiences, all powered by Knock's infrastructure.

<Steps>
  <Step title="Create a custom message type (optional)">
    If you'd like to create a custom message type, you can do so by following the guide on [creating custom message types](/in-app-ui/message-types).

    Otherwise, you can create a custom component on top of the out-of-the-box message types that Knock provides.

  </Step>
  <Step title="Setup the KnockProvider and KnockInAppMessagesChannelProvider">
    The `KnockProvider` is a React context provider that makes the Knock client SDK available to your application. The `KnockInAppMessagesChannelProvider` is a React context provider that makes the Knock in-app messages client in to your application.

```tsx
const MyApp = () => {
  return (
    <KnockProvider publicKey={process.env.KNOCK_PUBLIC_KEY} userId={currentUser.id}>
      <KnockInAppMessagesChannelProvider channelId={process.env.KNOCK_IAM_CHANNEL_ID}>
        <MyAppLayout>
      </KnockInAppMessagesChannelProvider>
    </KnockProvider>
  );
}
```

  </Step>
  <Step title="Create a custom messaging component">
    Create a custom messaging component that uses the `useInAppMessage` or `useInAppMessages` hook to render one or more in-app messages.

```tsx
import { useInAppMessage } from "@knocklabs/react";

const MyBanner = () => {
  const { message, inAppMessagesClient } = useInAppMessage("my-custom-banner");

  if (!message) return null;

  const onBannerClick = async () => {
    await inAppMessagesClient.markAsInteracted(message);
    router.push(actionUrl);
  };

  return (
    <div onClick={onBannerClick} role="button" className="my-banner">
      {message.content.body}
    </div>
  );
};
```

  </Step>
  <Step title="Mount your component">
    Mount your component under the `KnockInAppMessagesChannelProvider` in your application tree. You can mount your component anywhere in the tree, but it must be a descendant of the `KnockInAppMessagesChannelProvider`.

```tsx
const MyApp = () => {
  return (
    <KnockProvider publicKey={process.env.KNOCK_PUBLIC_KEY} userId={currentUser.id}>
      <KnockInAppMessagesChannelProvider>
        <MyAppLayout>
        <MyBanner />
      </KnockInAppMessagesChannelProvider>
    </KnockProvider>
  );
}
```

  </Step>
</Steps>


## Toasts
How to build notification toasts powered by Knock and React.
---
title: "Building notification toasts with React"
description: How to build notification toasts powered by Knock and React.
section: Building in-app UI
---

While there are no out-of-the-box toast components in the `@knocklabs/react` library, it's easy to build toasts on top of the primitives exposed. In this guide, we'll show you just how to do that using the `react-hot-toasts` library as our "toaster."

[See a live demo](https://in-app-demo.knock.app/)

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Find your channel ID.</span> To find the
      channel ID for your in-app channel(s), go to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard,
      navigate to the channel page of your in-app channel, and copy the channel
      ID.
    </>
  }
/>

## Installing dependencies

```bash title="Installing dependencies"
npm install @knocklabs/react react-hot-toast
```

## Adding the Knock providers

We'll need to wrap our toast producing component in a `KnockProvider` and `KnockFeedProvider` to set up a connection to Knock and connect to the authenticated user's feed. You can read more about the available props for the providers in [the reference](/sdks/react/reference#knockprovider).

```jsx
import { KnockProvider, KnockFeedProvider } from "@knocklabs/react";

// We'll write this next
import NotificationToaster from "./NotificationToaster";

const NotificationToastProducer = () => {
  // An example of fetching the current authenticated user
  const { user } = useCurrentUser();

  return (
    <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={user.id}>
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
        <NotificationToaster />
      </KnockFeedProvider>
    </KnockProvider>
  );
};
```

## Rendering toasts when new notifications come in

Our `KnockFeedProvider` exposes a `useKnockFeed` hook, which will return a `feedClient` we can use to bind to and receive real-time notifications being received on our feed.

```jsx
import toast, { Toaster } from "react-hot-toast";
import { useEffect } from "react";
import { useKnockFeed } from "@knocklabs/react";

const NotificationToaster = () => {
  const { feedClient } = useKnockFeed();

  const onNotificationsReceived = ({ items }) => {
    // Whenever we receive a new notification from our real-time stream, show a toast
    // (note here that we can receive > 1 items in a batch)
    items.forEach((notification) => {
      //Use toast.custom to render the HTML content of the notification
      toast.custom(
        <div
          dangerouslySetInnerHTML={{ __html: notification.blocks[0].rendered }}
        ></div>,
        { id: notification.id },
      );
    });

    // Optionally, you may want to mark them as "seen" as well
    feedClient.markAsSeen(items);
  };

  useEffect(() => {
    // Receive all real-time notifications on our feed
    feedClient.on("items.received.realtime", onNotificationsReceived);

    // Cleanup
    return () =>
      feedClient.off("items.received.realtime", onNotificationsReceived);
  }, [feedClient]);

  return <Toaster />;
};

export default NotificationToaster;
```

## Wrapping up

We can then test our workflow using the built-in test runner in Knock to produce messages, which will be received and displayed as a toast in your application.


## Notification inbox
How to build notification inboxes powered by Knock and React.
---
title: "Building notification inboxes with React"
description: How to build notification inboxes powered by Knock and React.
section: Building in-app UI
---

Our `@knocklabs/react` library can be used to build full-page inbox experiences, too. In this guide we'll show you how to have a basic inbox ready for your users in a few minutes.

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Find your channel ID.</span> To find the
      channel ID for your in-app channel(s), go to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard,
      navigate to the channel page of your in-app channel, and copy the channel
      ID.
    </>
  }
/>

## Installing dependencies

```bash title="Installing dependencies"
npm install @knocklabs/react
```

## Rendering the notification inbox

Here we're using the `KnockProvider` to authenticate our current user and get access to the Knock JavaScript client. Then we use the `KnockFeedProvider` to connect them to a Knock In-app Feed Channel. We then render the `NotificationFeed` component to give us a simple, complete notification inbox page.

```jsx
import { KnockFeedProvider, NotificationFeed } from "@knocklabs/react";

const NotificationInbox = () => {
  // An example of fetching the current authenticated user
  const { user } = useCurrentUser();

  return (
    <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={user.id}>
      {/* Optionally, use the KnockFeedProvider to connect an in-app feed */}
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_ID}>
        <NotificationFeed />
      </KnockFeedProvider>
    </KnockProvider>
  );
};
```

## Next steps

- [Common recipes for customizing the feed](/in-app-ui/react/feed#common-recipes)
- [Using custom UI for a notification page](/in-app-ui/react/custom-notifications-ui)
- [Complete reference for the React library](/sdks/react/reference)


## Custom feed UI (headless)
How to build custom notification feed UI using the hooks from the Knock React SDK.
---
title: "Building custom notification feed UI with hooks (headless)"
description: How to build custom notification feed UI using the hooks from the Knock React SDK.
section: Building in-app UI
tags: ["hooks", "headless", "useNotifications", "useAuthenticatedKnockClient"]
---

Using our `@knocklabs/react` and `@knocklabs/client` libraries, you can create fully custom notification UIs that are backed by the Knock Feed API and real-time service.

In this guide, we'll take a look at creating a completely custom notifications UI in our application in a headless way using the Knock hooks.

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Find your channel ID.</span> To find the
      channel ID for your in-app channel(s), go to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard,
      navigate to the channel page of your in-app channel, and copy the channel
      ID.
    </>
  }
/>

## Installing dependencies

```bash title="Installing dependencies"
npm install @knocklabs/react
```

## Implement `KnockProvider`

First, we'll need to implement the `KnockProvider` component somewhere in your component tree and authenticate against the Knock API using a user id and API key.

```jsx title="Implement KnockProvider in your app"
import { KnockProvider } from "@knocklabs/react";

const App = ({ user }) => (
  <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={user.id}>
    <NotificationFeed />
  </KnockProvider>
);
```

## Setup the Knock client

Next, we'll need to access the instance of the Knock client created by the `KnockProvider` using the `useKnockClient` hook.

```jsx title="Access the configured knockClient using useKnockClient"
import { useKnockClient } from "@knocklabs/react";

const NotificationFeed = ({ user }) => {
  const knockClient = useKnockClient();

  return null;
};
```

## Setup the Knock feed instance

Next, we'll want to set up an instance of a Knock Feed, which will handle the state management and provide a way for us to interact with the messages on the feed.

```jsx title="Create a feed store with Zustand"
import {
  useKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/react";
import { useEffect } from "react";

const NotificationFeed = ({ user }) => {
  const knockClient = useKnockClient();
  const feedClient = useNotifications(
    knockClient,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { items, metadata } = useNotificationStore(feedClient);

  useEffect(() => {
    feedClient.fetch();
  }, [feedClient]);

  return null;
};
```

## Creating a custom notifications UI

The last step is to render our notifications UI using the data that's exposed via the state store (`items` and `metadata`).

```jsx title="Render items and metadata in the feed"
import {
  useKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/react";
import { useEffect } from "react";

const NotificationFeed = ({ user }) => {
  const knockClient = useKnockClient();
  const feedClient = useNotifications(
    knockClient,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { items, metadata } = useNotificationStore(feedClient);

  useEffect(() => {
    feedClient.fetch();
  }, [feedClient]);

  return (
    <div className="notifications">
      <span>You have {metadata.unread_count} unread items</span>

      {items.map((item) => (
        <div key={item.id}>
          <div dangerouslySetInnerHTML={{ __html: item.blocks[0].rendered }} />
        </div>
      ))}
    </div>
  );
};
```

## Wrapping up

There's a lot more we can do with our notifications UI, but we'll leave that as an exercise to the reader. Here are some examples:

- Adding mark as read, and archiving behavior to the notification cell
- Displaying a count of the total number of notifications


## Preferences
How to build a complete notification preference center, powered by Knock and React.
---
title: "Building preference UIs in React"
description: How to build a complete notification preference center, powered by Knock and React.
section: Building in-app UI
---

In this guide we'll build a `PreferenceCenter` React component with Knock's preference APIs. This component should be flexible enough to handle most of your needs and can easily be customized or extended for more specific use cases. If you want to reference a TypeScript example, you can find one in the [Notion feed example](https://github.com/knocklabs/notion-feed-example/blob/main/components/PreferenceCenter.tsx).

<SdkCard
  title="Video walkthrough"
  linkUrl="https://www.youtube.com/watch?v=FCQGquTJlL0"
  icon="youtube"
  languages={["Explore Knock's preferences API", "17 min. watch time"]}
  isExternal={true}
/>
## Getting started

Before beginning this tutorial, we'd recommend reading the [preferences overview docs](/preferences/overview) and creating a [default `PreferenceSet`](/preferences/overview#create-a-default-preferenceset) for your environment. The [API reference for preferences](/reference#preferences) can also be helpful, but is not required for this tutorial.

<Callout
  mt={4}
  emoji="💡"
  text={
    <>
      <span className="font-bold">A note on merging preferences</span>
      <p>
        Remember that if you have either a environment or tenant default{" "}
        <code>PreferenceSet</code> those preferences will be merged with changes
        a user makes in the UI, with the user-specified changes taking
        precedence.
      </p>
    </>
  }
/>

### What you'll need

To use this example, you'll need [an account on Knock](https://dashboard.knock.app) and you'll need to have [identified a user](/concepts/users). You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)

### Installing dependencies

```bash title="Installing dependencies"
npm install @knocklabs/client
```

## Modeling our preferences

In this example we'll assume the user has a default `PreferenceSet` that contains workflows and workflow categories, each with it's own channel type settings. We'll expose this to our users as a "cross-hatch" so that they can set a preference for each channel type.

```json title="Preference object"
{
  "id": "default",
  "categories": {
    "collaboration": {
      "channel_types": {
        "email": true,
        "in_app_feed": true
      }
    },
    "new-asset": {
      "channel_types": {
        "email": false,
        "in_app_feed": true
      }
    }
  },
  "workflows": {
    "new-comment": {
      "channel_types": {
        "email": true
      }
    }
  },
  "channel_types": {}
}
```

## Creating our preference center

The next step here is to create our preference center component. Create a `PreferenceCenter.jsx` file in your project and add the following import statements to the top of the file. After that, you'll need to create a new instance of the `Knock` client and authenticate it against a user:

```jsx title="Import Knock client & React hooks"
import Knock from "@knocklabs/client";
import { useEffect, useState } from "react";
const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knockClient.authenticate(currentUser.id);
```

<Steps titleSize="h3">
  <Step title="Create a preferences view config">
    Next we'll create an configuration object that will help us drive the view of our preference center. In some cases, you may want to store values in a `PreferenceSet` that you don't directly expose to users or want to provide more descriptive titles, labels, and descriptions.
```jsx title="Power the preference center view"
const PreferenceViewConfig = {
  RowSettings: {
    "new-asset": {
      title: "New Asset",
      description: "New file uploads in workspaces you're a part of",
    },
    "new-comment": {
      title: "Comments & mentions",
      description: "New comments and replies to threads.",
    },
    collaboration: {
      title: "In-app messages",
      description: "Messages from other users on the platform",
    },
  },
  ChannelTypeLabels: {
    in_app_feed: "In-app Feed",
    email: "Email",
    push: "Push",
  },
};
```
In this example, the `RowSettings` object contains entries that map directly to keys in the `PreferenceSet` we modeled in the previous step. Each entry here will surface those settings to the user and provide additional human readable details with `title` and `description`. If you want to modify this for your own project, you can swap the keys inside of `RowSettings` with a key from your default `PreferenceSet` and update the `title` and `description` properties.

The `ChannelTypeLabels` object is similar in that its contents determine which channel type settings will be surfaced for each row. Adding additional entries to this object will present more checkboxes for the user, and you can modify the label value by updating the value of a particular key.

Copy and paste this `PreferenceViewConfig` object in your component file and make any updates to correspond with the shape of your default `PreferenceSet` and channels.

</Step>

<Step title="Display a preference setting row">
Next, we'll create a `PreferenceSettingsRow` component that will display the `title`, `description`, and checkbox toggles for each `SettingsRow` entry:
```jsx title="Display a row for each desired preference setting"
function PreferenceSettingsRow({
preferenceType,
preferenceKey,
channelTypeSettings,
onChange,
}) {
return (
  <div
    style={{
      display: "flex",
      flexDirection: "row",
      justifyContent: "space-between",
      padding: ".75rem .25rem",
      gap: "1rem",
    }}
  >
    <div>
      <h2>
        {PreferenceViewConfig.RowSettings[preferenceKey].title}
      </h2>
      <p>
        {PreferenceViewConfig.RowSettings[preferenceKey].description}
      </p>
    </div>
    <div>
      {Object.keys(PreferenceViewConfig.ChannelTypeLabels).map(
        (channelType) => {
          return (
            <div
              key={`${preferenceKey}_${channelType}`}
              style={{ display: "flex", justifyContent: "space-between" }}
            >
              <label htmlFor={`${preferenceKey}_${channelType}`}>
                {PreferenceViewConfig.ChannelTypeLabels[channelType]}
              </label>
              <input
                id={`${preferenceKey}_${channelType}`}
                type="checkbox"
                checked={channelTypeSettings[channelType]}
                disabled={
                  typeof channelTypeSettings[channelType] === "undefined"
                }
                onChange={(e) => {
                  onChange({
                    preferenceKey,
                    preferenceType,
                    channelTypeSettings: {
                      ...channelTypeSettings,
                      [channelType]: e.target.checked,
                    },
                  });
                }}
              />
            </div>
          );
        }
      )}
    </div>
  </div>
);
}
```

This component has a lot of functionality built in, so let's unpack what it does.

Using the `preferenceKey` parameter, this component renders a section of UI that displays the `title` and `description` properties stored in the `PreferenceViewConfig` under the matching key:

```jsx title="Displaying preference details"
<div>
  <h2>{PreferenceViewConfig.RowSettings[preferenceKey].title}</h2>
  <p>{PreferenceViewConfig.RowSettings[preferenceKey].description}</p>
</div>
```

Next, we'll generate an `input` element tied to each channel type setting for that preference. We do that by looping through the keys of `PreferenceViewConfig.ChannelTypeLabels` to generate a UI element tied to a particular channel and preference setting:

```jsx
<div>
  {Object.keys(PreferenceViewConfig.ChannelTypeLabels).map((channelType) => {
    return (
      <div
        key={`${preferenceKey}_${channelType}`}
        style={{ display: "flex", justifyContent: "space-between" }}
      >
        <label htmlFor={`${preferenceKey}_${channelType}`}>
          {PreferenceViewConfig.ChannelTypeLabels[channelType]}
        </label>
        <input
          id={`${preferenceKey}_${channelType}`}
          type="checkbox"
          checked={channelTypeSettings[channelType]}
          disabled={typeof channelTypeSettings[channelType] === "undefined"}
          onChange={(e) => {
            onChange({
              preferenceKey,
              preferenceType,
              channelTypeSettings: {
                ...channelTypeSettings,
                [channelType]: e.target.checked,
              },
            });
          }}
        />
      </div>
    );
  })}
</div>
```

This section of UI uses the `channelTypeSettings` passed into the function to drive the `disabled` and `checked` states of the `input` element. These `channelTypeSettings` are the user's existing preferences pulled directly from Knock. By disabling the checkbox if those channel type settings are `undefined` we remove the user's ability to modify that value if it doesn't appear in the default preference set.

As the user toggles the state of this `input` it fires an `onChange` event handler that calls a function also passed as a parameter. This function is ultimately what updates the user's preferences in Knock, so we pass a modified value of `channelTypeSettings` that includes the current value of the event target's `checked` property:

```javascript title="Updating preferences onChange"
onChange={(e) => {
  onChange({
    preferenceKey,
    preferenceType,
    channelTypeSettings: {
      ...channelTypeSettings,
      [channelType]: e.target.checked,
    },
  });
}}
```

  </Step>
  <Step title="Render your preference center">
    Now that we have a `PreferencesViewConfig` object to help us drive the shape of our UI and a `PreferenceSettingsRow` to render a row's details an the necessary `inputs`, it's time to compose those elements into an actual `PreferenceCenter` component. This `PreferenceCenter` function should be exported:

```jsx title="Compose a preference center"
export default function PreferenceCenter() {
  //Create some local state to store the user's preferences
  const [localPreferences, setLocalPreferences] = useState({
    id: "default",
    categories: {
      collaboration: {
        channel_types: {
          email: true,
          in_app_feed: true,
        },
      },
      "new-asset": {
        channel_types: {
          email: false,
          in_app_feed: true,
        },
      },
    },
    workflows: {
      "new-comment": {
        channel_types: {
          email: true,
        },
      },
    },
    channel_types: {},
  });

  //We load the current user's preferences from Knock, and set them to local preferences

  useEffect(() => {
    async function fetchPreferences() {
      const preferences = await knockClient.user.getPreferences();
      setLocalPreferences(preferences);
    }
    fetchPreferences();
  }, [knockClient]);

  //When a preference setting is changed, we create a new PreferenceSet that
  //includes the change, update the preferences in Knock, and then update local state
  const onPreferenceChange = async ({
    preferenceKey,
    preferenceType,
    channelTypeSettings,
  }) => {
    //create a new preference set with local preferences as starting point
    const preferenceUpdate = {
      ...localPreferences,
    };

    // Here we'll make updates to the preference set based on the preferenceType
    // and override existing channelTypeSettings
    // since Workflow and Category preferences can also be a Boolean,
    // we'll check if the preferenceKey contains a channel_types object
    if (
      preferenceType === "category" &&
      typeof preferenceUpdate.categories[preferenceKey] === "object"
    ) {
      preferenceUpdate.categories[preferenceKey].channel_types =
        channelTypeSettings;
    }
    if (
      preferenceType === "workflow" &&
      typeof preferenceUpdate.workflows[preferenceKey] === "object"
    ) {
      preferenceUpdate.workflows[preferenceKey].channel_types =
        channelTypeSettings;
    }
    //Next, we upload the new PreferenceSet to Knock for that user
    const preferences = await knockClient.user.setPreferences(preferenceUpdate);
    // Set the updated preferences in local state
    setLocalPreferences(preferences);
  };
  //If we haven't loaded preferences yet, maybe show a spinner
  if (!localPreferences) {
    return null;
  }
  return (
    <div className="preferences">
      {Object.keys(localPreferences?.categories).map((category) => {
        return (
          <PreferenceSettingsRow
            key={category}
            preferenceType="category"
            preferenceKey={category}
            channelTypeSettings={
              typeof localPreferences.categories[category] === "object"
                ? localPreferences?.categories[category]?.channel_types
                : {}
            }
            onChange={onPreferenceChange}
          ></PreferenceSettingsRow>
        );
      })}
      {Object.keys(localPreferences?.workflows).map((workflow) => {
        return (
          <PreferenceSettingsRow
            key={workflow}
            preferenceType="workflow"
            preferenceKey={workflow}
            channelTypeSettings={
              typeof localPreferences.workflows[workflow] === "object"
                ? localPreferences?.workflows[workflow]?.channel_types
                : {}
            }
            onChange={onPreferenceChange}
          ></PreferenceSettingsRow>
        );
      })}
    </div>
  );
}
```

Let's examine the code in the `PreferenceCenter` component step-by-step to explain what's happening.

First, we need to load the current user's preferences from Knock and store them in local state so we can operate on them. We can call the `getPreferences` method on `knockClient.user` to load a user's preferences:

```jsx title="Store current preferences in local state"
//Create some local state to store the user's preferences
const [localPreferences, setLocalPreferences] = useState();

//We load the current user's preferences from Knock, and set them to local preferences

useEffect(() => {
  async function fetchPreferences() {
    const preferences = await knockClient.user.getPreferences();
    setLocalPreferences(preferences);
  }
  fetchPreferences();
}, [knockClient]);
```

Next, we create a function called `onPreferenceChange` that will get passed as the `onChange` parameter to our `PreferenceSettingsRow` component from the previous step. The `onPreferenceChange` function takes a `preferenceKey` argument and an updated `channelTypeSettings` argument:

```jsx title="Update preferences in Knock"
//When a preference setting is changed, we create a new PreferenceSet that
//includes the change, update the preferences in Knock, and then update local state
const onPreferenceChange = async ({
  preferenceKey,
  preferenceType,
  channelTypeSettings,
}) => {
  //create a new preference set with local preferences as starting point
  const preferenceUpdate = {
    ...localPreferences,
  };

  // Here we'll make updates to the preference set based on the preferenceType
  // and override existing channelTypeSettings
  // since Workflow and Category preferences can also be a Boolean,
  // we'll check if the preferenceKey contains an channel_types object
  if (
    preferenceType === "category" &&
    typeof preferenceUpdate.categories[preferenceKey] === "object"
  ) {
    preferenceUpdate.categories[preferenceKey].channel_types =
      channelTypeSettings;
  }
  if (
    preferenceType === "workflow" &&
    typeof preferenceUpdate.workflows[preferenceKey] === "object"
  ) {
    preferenceUpdate.workflows[preferenceKey].channel_types =
      channelTypeSettings;
  }
  //Next, we upload the new PreferenceSet to Knock for that user
  const preferences = await knockClient.user.setPreferences(preferenceUpdate);
  // Set the updated preferences in local state
  setLocalPreferences(preferences);
};
```

Based on the `preferenceType` of the update, we'll overwrite any existing preferences stored under that key and use the `setPreferences` method of `knockClient.user` to update those preferences in Knock. We then set the updated preferences back to local state using `setLocalPreferences` to keep our UI in sync with what is stored in Knock.

Lastly, we actually render our `PreferenceSettingsRow` components:

```jsx
<div className="preferences">
  {Object.keys(localPreferences?.categories).map((category) => {
    return (
      <PreferenceSettingsRow
        key={category}
        preferenceType="category"
        preferenceKey={category}
        channelTypeSettings={
          typeof localPreferences.categories[category] === "object"
            ? localPreferences?.categories[category]?.channel_types
            : {}
        }
        onChange={onPreferenceChange}
      ></PreferenceSettingsRow>
    );
  })}
  {Object.keys(localPreferences?.workflows).map((workflow) => {
    return (
      <PreferenceSettingsRow
        key={workflow}
        preferenceType="workflow"
        preferenceKey={workflow}
        channelTypeSettings={
          typeof localPreferences?.workflows[workflow] === "object"
            ? localPreferences?.workflows[workflow]?.channel_types
            : {}
        }
        onChange={onPreferenceChange}
      ></PreferenceSettingsRow>
    );
  })}
</div>
```

Here we loop through each workflow or category key stored in a user's preferences and pass in the existing `channelTypeSettings` which will power the state of that row's checkbox `inputs` and the `onPreferenceChange` callback to update a user's preferences in Knock.

You should now have a working preference center 🎉

<Image
  src="/images/concepts/preferences/preference-center.png"
  alt="A basic preference center"
  width={1184}
  height={714}
  className="rounded-md mx-auto border border-gray-200"
/>

</Step>
</Steps>

## Completed preference center

Knock's preference model is very flexible, but you should find that the component below will satisfy most of your preference center needs and can easily be used as a starting point for your own preference center.

```jsx title="Completed preference center"
import Knock from "@knocklabs/client";
import { useEffect, useState } from "react";
const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knockClient.authenticate(currentUser.id);

// Here we create a view config object, this helps us customize the interface
// and choose which preference options we want to display to the user
const PreferenceViewConfig: Record<string, any> = {
  RowSettings: {
    "new-asset": {
      title: "New Asset",
      description: "New file uploads in workspaces you're a part of",
    },
    "new-comment": {
      title: "Comments & mentions",
      description: "New comments and replies to threads.",
    },
    collaboration: {
      title: "In-app messages",
      description: "Messages from other users on the platform",
    },
  },
  ChannelTypeLabels: {
    in_app_feed: "In-app Feed",
    email: "Email",
    push: "Push",
  },
};
// The PreferenceSettingsRow component is what actually displays the UI to manipulate
function PreferenceSettingsRow({
  preferenceType,
  preferenceKey,
  channelTypeSettings,
  onChange,
}) {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "row",
        justifyContent: "space-between",
        padding: ".75rem .25rem",
        gap: "1rem",
      }}
    >
      <div>
        <h2>{PreferenceViewConfig.RowSettings[preferenceKey].title}</h2>
        <p>{PreferenceViewConfig.RowSettings[preferenceKey].description}</p>
      </div>
      <div>
        {Object.keys(PreferenceViewConfig.ChannelTypeLabels).map(
          (channelType) => {
            return (
              <div
                key={`${preferenceKey}_${channelType}`}
                style={{ display: "flex", justifyContent: "space-between" }}
              >
                <label htmlFor={`${preferenceKey}_${channelType}`}>
                  {PreferenceViewConfig.ChannelTypeLabels[channelType]}
                </label>
                <input
                  id={`${preferenceKey}_${channelType}`}
                  type="checkbox"
                  checked={channelTypeSettings[channelType]}
                  disabled={
                    typeof channelTypeSettings[channelType] === "undefined"
                  }
                  onChange={(e) => {
                    onChange({
                      preferenceKey,
                      preferenceType,
                      channelTypeSettings: {
                        ...channelTypeSettings,
                        [channelType]: e.target.checked,
                      },
                    });
                  }}
                />
              </div>
            );
          },
        )}
      </div>
    </div>
  );
}

export default function PreferenceCenter() {
  //Create some local state to store the user's preferences
  const [localPreferences, setLocalPreferences] = useState({
    id: "default",
    categories: {
      collaboration: {
        channel_types: {
          email: true,
          in_app_feed: true,
        },
      },
      "new-asset": {
        channel_types: {
          email: false,
          in_app_feed: true,
        },
      },
    },
    workflows: {
      "new-comment": {
        channel_types: {
          email: true,
        },
      },
    },
    channel_types: {},
  });

  //We load the current user's preferences from Knock, and set them to local preferences

  useEffect(() => {
    async function fetchPreferences() {
      const preferences = await knockClient.user.getPreferences();
      setLocalPreferences(preferences);
    }
    fetchPreferences();
  }, [knockClient]);

  //When a preference setting is changed, we create a new PreferenceSet that
  //includes the change, update the preferences in Knock, and then update local state
  const onPreferenceChange = async ({
    preferenceKey,
    preferenceType,
    channelTypeSettings,
  }) => {
    //create a new preference set with local preferences as starting point
    const preferenceUpdate = {
      ...localPreferences,
    };

    // Here we'll make updates to the preference set based on the preferenceType
    // and override existing channelTypeSettings
    // since Workflow and Category preferences can also be a Boolean,
    // we'll check if the preferenceKey contains an channel_types object
    if (
      preferenceType === "category" &&
      typeof preferenceUpdate.categories[preferenceKey] === "object"
    ) {
      preferenceUpdate.categories[preferenceKey].channel_types =
        channelTypeSettings;
    }
    if (
      preferenceType === "workflow" &&
      typeof preferenceUpdate.workflows[preferenceKey] === "object"
    ) {
      preferenceUpdate.workflows[preferenceKey].channel_types =
        channelTypeSettings;
    }
    //Next, we upload the new PreferenceSet to Knock for that user
    const preferences = await knockClient.user.setPreferences(preferenceUpdate);
    // Set the updated preferences in local state
    setLocalPreferences(preferences);
  };
  if (!localPreferences) {
    return null;
  }
  return (
    <div className="preferences">
      {Object.keys(localPreferences?.categories).map((category) => {
        return (
          <PreferenceSettingsRow
            key={category}
            preferenceType="category"
            preferenceKey={category}
            channelTypeSettings={
              typeof localPreferences.categories[category] === "object"
                ? localPreferences?.categories[category]?.channel_types
                : {}
            }
            onChange={onPreferenceChange}
          ></PreferenceSettingsRow>
        );
      })}
      {Object.keys(localPreferences?.workflows).map((workflow) => {
        return (
          <PreferenceSettingsRow
            key={workflow}
            preferenceType="workflow"
            preferenceKey={workflow}
            channelTypeSettings={
              typeof localPreferences?.workflows[workflow] === "object"
                ? localPreferences?.workflows[workflow]?.channel_types
                : {}
            }
            onChange={onPreferenceChange}
          ></PreferenceSettingsRow>
        );
      })}
    </div>
  );
}
```


## SlackKit
How to let users authorize and select Slack channels in your app with Knock's SlackKit.
---
title: "Building a Slack integration in React"
description: How to let users authorize and select Slack channels in your app with Knock's SlackKit.
section: SlackKit
---

Our `@knocklabs/react` library comes with pre-built components for allowing your users to connect their Slack workspace to Knock and select the channels they want to be notified on. SlackKit manages your OAuth connection and tokens, helps your customers select which channels they want to receive notifications in, and integrates seamlessly with the rest of Knock.

## Getting started

To get started you'll need a [Knock account](https://dashboard.knock.app), a [Slack channel connected to a Slack app](/in-app-ui/react/slack-kit), and a workflow with a Slack channel step.

Depending on your use case, you can follow one of these guides for step-by-step instructions on how to set up your Slack integration:

- [Sending messages to public and private](/integrations/chat/slack/sending-a-message-to-channels) channels in your customer's Slack workspace
- [Sending direct messages](/integrations/chat/slack/sending-a-direct-message) to users in your customer's Slack workspace

## Using SlackKit components

Once you've provided access to the necessary data, you can drop Knock's pre-built components into your React application to immediately set up Slack authorization and channel selection for your users. [See the reference](/sdks/react/reference#slack-components) for full documentation of these components.

### Add the providers

In order to give your components the data they need, they must be wrapped in the `KnockSlackProvider`. We recommend putting this high in your component tree so that any Slack components that you use will be rendered within it. The Slack provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockSlackProvider
        knockSlackChannelId="Knock Slack channel ID"
        tenant="Tenant ID"
    >
        {child components}
    </KnockSlackProvider>
</KnockProvider>
```

The `KnockSlackProvider` gives your components access to the status of the connection to your Slack app, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Add the components

#### SlackAuthButton & Container

<figure>
  <Image
    src="/images/integrations/chat/slack/slackauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The SlackAuthButton component with SlackAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>The SlackAuthButton component with SlackAuthContainer</figcaption>
</figure>

Your users will give your Slack app access to their own Slack workspaces via the `SlackAuthButton`. This button can be used on its own, or nested in the `SlackAuthContainer` for a bigger visual footprint. Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with SlackAuthButton"
// Without container
<SlackAuthButton
    slackClientId="Slack app client ID"
    redirectUrl="The URL of your application to return to once Slack authorization is complete"
/>

// With container
<SlackAuthContainer
    actionButton={
        <SlackAuthButton
            slackClientId="Slack app client ID"
            redirectUrl="The URL of your application to return to once Slack authorization is complete"
        />
    }
/>
```

The `SlackAuthButton` maps a tenant in your product to a customer's Slack workspace. This means in most cases you'll just need a single instance of the `SlackAuthButton`.

Remember to consider which roles in your application can access the `SlackAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button/container in the settings area of your product.

#### SlackChannelCombobox

<figure>
  <Image
    src="/images/integrations/chat/slack/slackchannelcombobox.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The SlackChannelCombobox component showing connected channels"
    width={1880}
    height={701}
  />
  <figcaption>
    The SlackChannelCombobox component showing connected channels
  </figcaption>
</figure>

This combobox contains the list of channels in the connected Slack workspace. Users will use this combobox to search and select a channel (or more than one channel) to be notified when an event in your application occurs, for example a comment on a video. They can also use this combobox to deselect a connected channel.

The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well.

Add your combobox to your application where you'd like the user to select channels to notify:

```javascript title="The SlackChannelCombobox connects an object to one or more channels"
<SlackChannelCombobox
  slackChannelsRecipientObject={{
    objectId: "object id",
    collection: "object collection",
  }}
/>
```

<br />
<Callout
  emoji="💡"
  text={
    <>
      <strong>Limitations</strong>
      <ul>
        <li>
          The combobox will only show channels for Slack workspaces with fewer
          than 1000 channels (public and private; not including archived). If
          there are more, the combobox will turn into a text input that accepts
          a channel ID to connect.
        </li>
        <li>
          The combobox will only show private channels from your users' Slack
          workspaces if your Slack app has been invited to those channels.
        </li>
        <li>
          The combobox does not show individual users for Slack direct messages.
        </li>
      </ul>
    </>
  }
/>

### Complete sample code

Here's an example of these components in a React application.

```javascript title="Store Knock and Slack credentials as .env vars"
// .env

KNOCK_PUBLIC_API_KEY = "pk_test_12345";
KNOCK_SLACK_CHANNEL_ID = "2e0e37c3-751b-4be5-a684-8296009e960e";

SLACK_APP_CLIENT_ID = "1354596639525.6166309709204";
```

<br />

```javascript title="Providers wrap your UI components"
<KnockProvider
  apiKey={process.env.KNOCK_PUBLIC_API_KEY}
  userId={currentUser.id}
  userToken={localStorage.getItem("knock-user-token")}
>
  <KnockSlackProvider
    knockSlackChannelId={process.env.KNOCK_SLACK_CHANNEL_ID}
    tenant={currentAccount.id}
  >
    <NotificationSettings />
    <VideoProjectsIndex />
  </KnockSlackProvider>
</KnockProvider>
```

<br />

```javascript title="Render your SlackAuthButton inside of KnockSlackProvider"
const NotificationSettings = () => {
  return (
    <SlackAuthContainer
      actionButton={
        <SlackAuthButton
          slackClientId={process.env.SLACK_APP_CLIENT_ID}
          redirectUrl={"www.my-example-app.com/notification-settings"}
        />
      }
    />
  );
};
```

<br />

```javascript title="Render a SlackChannelCombobox for each object"

const VideoProjectsPage = ({videos}) => {
    return (
        videos.map(video => {
            return <VideoPage {video} />
        })
    )
}

const VideoPage = ({video}) => {
  return (
    <div>
      <div>{video.name}</div>
      <div>{video.content}</div>
      <div>{video.comments}</div>
      <SlackChannelCombobox
        slackChannelsRecipientObject={{
          id: video.id,
          collection: "videos",
        }}
      />
    </div>
  )
}

```

<br />

## Using SlackKit headless

If you need custom designs or want to display additional information around your Slack integration, you don't need to use Knock's pre-built components to take advantage of SlackKit.

SlackKit exposes three levels of support: React hooks, client functions, and API endpoints.

### Hooks

You can use the [Slack React hooks](/sdks/react/reference#slack-hooks) under the hood to access and set Slack integration data with your own components. All of them are available from the `@knocklabs/react-core` package. All of them must still be nested under the `KnockSlackProvider` to work.

To use a hook in your component, all you need to to is import it and pass it the necessary params, and then you can use the data and functions returned in each to pass to your own component UI.

For example, you may want to provide your users a list of the connected channels outside of the `SlackChannelCombobox`. Let's look at how you can combine two hooks to accomplish that.

#### Building a list of connected channels

First, make sure your component that you're using the hooks in is nested somewhere under the `KnockSlackProvider`. Then, import both the `useSlackChannels` and `useConnectedSlackChannels` hooks, as we'll be combining data from each to build our list.

We'll combine our data to create a list of channels that has a name and an `isPrivate` attribute so we can conditionally show a lock icon if the channel is marked private.

Here's some sample code for our final list:

```javascript title="Fetch Slack channels without the SlackChannelCombobox"
import {
  useConnectedSlackChannels,
  useSlackChannels,
} from "@knocklabs/react-core";

const ConnectedChannelsList = ({ slackChannelsRecipientObject }) => {
  const { data: slackChannels } = useSlackChannels();
  const { data: connectedChannels } = useConnectedSlackChannels({
    slackChannelsRecipientObject,
  });

  const slackChannelsMap = new Map(
    slackChannels.map((channel) => [channel.id, channel]),
  );

  const hydratedConnectedChannels = connectedChannels.map(
    (connectedChannel) => {
      const channel_id = connectedChannel.channel_id;
      return {
        id: channel_id,
        name: slackChannelsMap[channel_id].name,
        isPrivate: slackChannelsMap[channel_id].is_private,
      };
    },
  );

  return (
    <ul>
      {hydratedConnectedChannels.map((channel) => {
        return (
          <li key={channel.id}>
            {channel.name} {channel.isPrivate && <LockIcon />}
          </li>
        );
      })}
    </ul>
  );
};
```

### Client functions

If you want more fine grain control of your data, you can skip the hooks and simply use the functions Knock exposes in the [`@knocklabs/client` library](https://github.com/knocklabs/javascript/tree/main/packages/client) as long as you wrap the component you're calling it in inside of `KnockProvider`. You can accomplish anything we provide with hooks or the components with the following functions:

- `knock.slack.authCheck`: Get the status of Slack authorization
- `knock.slack.getChannels`: Get a list of Slack channels for the given tenant
- `knock.slack.revokeAccessToken`: Disables an access token with Slack and removes it from the tenant
- `knock.objects.getChannelData`: Use this to get the connected channels stored as channel data on the recipient object
- `knock.objects.setChannelData`: Use this to set the connected channels for a recipient object or an access token for a tenant

### API endpoints

Lastly, you can interact directly with the API endpoints for all of the above functionality. Here are the endpoints used in SlackKit that you would need to support an implementation of the managed UI:

- [Slack auth check](/reference#slack-auth-check): status of Slack authorization
- [Slack channels](/reference#slack-channels): list of Slack channels for the given workspace
- [Slack revoke token](/reference#slack-revoke-access): revoke Slack app token access and remove from tenant
- [Get channel data](/reference#get-object-channel-data): get channel data for your recipient object, which gives you access to the connected slack channels
- [Set channel data](/reference#set-object-channel-data): set channel data for your recipient object, which allows you to set connected slack channels

## Resources access grants

The only access you'll need to manage when using SlackKit are grants for your users to interact with their [Tenants](/concepts/tenants) and [Objects](/concepts/objects) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

### With the Node SDK

You'll need to generate a token for your user that includes access to the tenant storing the Slack access token as well as any recipient objects storing Slack channel data described in [SlackKit ](/in-app-ui/react/slack-kit#channel-data-requirements). If you need to enable access to multiple recipient objects, you can include multiple grants in the user token.

Example:

- Tenant ID: `jurassic-park`
- Recipient object collection: `videos`
- Recipient object ID: `dinosaurs-loose`

Using the above example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "jurassic-park" }, [
      Grants.SlackChannelsRead,
    ]),
    Knock.buildUserTokenGrant(
      { type: "object", id: "dinosaurs-loose", collection: "videos" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
    Knock.buildUserTokenGrant(
      { type: "object", id: "raptor-feeding-guide", collection: "videos" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockSlackProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Other languages

If you're not using the Node SDK, you can still generate a user token using a JWT signing library in your preferred language. Here's an [example of using Joken for the Elixir library](https://github.com/knocklabs/knock-elixir?tab=readme-ov-file#signing-jwts). You'll include the `grants` key in the root of the payload and put your resource grants in there. We'll go into detail about how they work below, but if you want to skip that and just get started, here's what that will look like in a given JWT payload for the example above:

```json
{
  "sub": "user123",
  "grants": {
    "https://api.knock.app/v1/objects/$tenants/jurassic-park": {
      "slack/channels_read": [{}]
    },
    "https://api.knock.app/v1/objects/videos/dinosaurs-loose": {
      "channel_data/read": [{}],
      "channel_data/write": [{}]
    }
  }
}
```

Continue reading for a deeper dive on access and how these grants are structured.

### Grants in the user token

You may already be familiar with generating a user token to be used with your public API key when making client side calls if you've used [authentication with enhanced security](/in-app-ui/security-and-authentication#authentication-with-enhanced-security). You'll use the same process to generate the user token as described here, including signing it with an RS256 algorithm using your private signing key, but you'll also be sending a list of grants that the user needs to work with SlackKit.

The two resources you'll be granting access to are:

- **The tenant**: the user needs access to this because this is where Knock stores the access token to Slack that will be used when communicating with the Slack API
- **The recipient object**: the user needs access to this because this is where Knock is storing the connected Slack channels as channel data on the object

These resources need different permissions. Here are the permissions needed for each:

- **Tenant**: reading slack channels
- **Recipient Object**: reading channel data; writing channel data

### How the grants are structured

Resource access grants in Knock are structured according to the [UCAN spec](https://github.com/ucan-wg/spec). They consist of an array of maps, with each map representing a resource.

How to read a resource grant:

```json
{
  "Knock endpoint of the resource": {
    "Name of access type being granted/Specific permission being granted": [
      "List of exceptions"
    ]
  }
}
```

So to grant access for a user to read the channel data of object `dinosaurs-loose` in the `videos` collection, your grant would look like this:

```json
{
  "https://api.knock.app/v1/objects/videos/dinosaurs-loose": {
    "channel_data/read": [{}]
  }
}
```

### Availability of resource access grants

Currently these grants are only implemented for use by SlackKit as described in this doc, and since exceptions are not used for these they will not be respected.


## TeamsKit
How to let users connect to your Microsoft Teams integration with Knock's TeamsKit.
---
title: "Building a Microsoft Teams integration in React"
description: How to let users connect to your Microsoft Teams integration with Knock's TeamsKit.
section: TeamsKit
---

Our `@knocklabs/react` library comes with pre-built components for allowing your users to connect their Microsoft Teams instances to Knock and select the channels they want to be notified on. TeamsKit manages your OAuth connection and tokens, helps your customers select which channels they want to receive notifications in, and integrates seamlessly with the rest of Knock.

## Getting started

To get started you'll need a [Knock account](https://dashboard.knock.app), a [Microsoft Teams channel connected to a Microsoft Teams bot](/integrations/chat/microsoft-teams/overview), and a workflow with a Microsoft Teams channel step.

Depending on your use case, you can follow one of these guides for step-by-step instructions on how to set up your Microsoft Teams integration:

- [Sending messages to public channels](/integrations/chat/microsoft-teams/sending-a-message-to-channels) in your customers' Microsoft Teams instances
- [Sending direct messages](/integrations/chat/microsoft-teams/sending-a-direct-message) to users in your customers' Microsoft Teams instances

## Using TeamsKit components

Once you've provided access to the necessary data, you can drop Knock's pre-built components into your React application to immediately set up Microsoft Teams authorization and channel selection for your users. [See the reference](/sdks/react/reference#microsoft-teams-components) for full documentation of these components.

### Add the providers

In order to give your components the data they need, they must be wrapped in the `KnockMsTeamsProvider`. We recommend putting this high in your component tree so that any TeamsKit components that you use will be rendered within it. The Microsoft Teams provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockMsTeamsProvider
        knockMsTeamsChannelId="Knock Microsoft Teams channel ID"
        tenantId="Knock tenant ID"
    >
        {child components}
    </KnockMsTeamsProvider>
</KnockProvider>
```

The `KnockMsTeamsProvider` gives your components access to the status of the connection to your Microsoft Teams bot, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Add the components

#### MsTeamsAuthButton & Container

<figure>
  <Image
    src="/images/integrations/chat/microsoft-teams/msteamsauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The MsTeamsAuthButton component with MsTeamsAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>
    The MsTeamsAuthButton component with MsTeamsAuthContainer
  </figcaption>
</figure>

Your users will give your Microsoft Teams bot access to their own Microsoft Entra tenants via the `MsTeamsAuthButton`. This button can be used on its own, or nested in the `MsTeamsAuthContainer` for a bigger visual footprint. Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with MsTeamsAuthButton"
// Without container
<MsTeamsAuthButton
    msTeamsBotId="Microsoft Teams bot ID"
    redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
/>

// With container
<MsTeamsAuthContainer
    actionButton={
        <MsTeamsAuthButton
            msTeamsBotId="Microsoft Teams bot ID"
            redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
        />
    }
/>
```

The `MsTeamsAuthButton` maps a tenant in your product to a customer's Microsoft Entra tenant. This means in most cases you'll just need a single instance of the `MsTeamsAuthButton`.

Remember to consider which roles in your application can access the `MsTeamsAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button/container in the settings area of your product.

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note:</strong> The <code>MsTeamsAuthButton</code> component does
      not automatically install your Microsoft Teams bot into a team or users'
      personal scope. Your users will need to{" "}
      <a
        href="https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77"
        target="_blank"
      >
        manually install your bot
      </a>{" "}
      before you can send messages to users and channels. Alternatively, provide
      instructions to your app's admins to{" "}
      <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps"
        target="_blank"
      >
        preinstall your bot for all Microsoft Teams users in their organization
      </a>
      , <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps#install-apps-in-an-existing-team"
        target="_blank"
      >
        install your bot into existing teams
      </a>, and <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps#preinstall-apps-in-a-new-team-using-team-creation-template"
        target="_blank"
      >
        preinstall your bot when new teams are created
      </a>.
    </>
  }
/>

#### MsTeamsChannelCombobox

<figure>
  <Image
    src="/images/integrations/chat/microsoft-teams/msteamschannelcombobox.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The MsTeamsChannelCombobox component showing connected channels"
    width={1088}
    height={584}
  />
  <figcaption>
    The MsTeamsChannelCombobox component showing connected channels
  </figcaption>
</figure>

This combobox contains the list of teams and channels belonging to the connected Microsoft Entra tenant. Users will use this combobox to search and select a channel (or more than one channel) to be notified when your application triggers a workflow with a Teams channel step. They can also use this combobox to deselect a connected channel.

The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well.

Add your combobox to your application where you'd like the user to select channels to notify:

```javascript title="The MsTeamsChannelCombobox connects an object to one or more channels"
<MsTeamsChannelCombobox
  msTeamsChannelsRecipientObject={{
    objectId: "object id",
    collection: "object collection",
  }}
/>
```

<br />
<Callout
  emoji="💡"
  text={
    <>
      <strong>Limitations</strong>
      <ul>
        <li>
          The combobox will only show public channels. Microsoft Teams bots do
          not support sending messages to private channels.
        </li>
        <li>
          The combobox does not show individual users for Microsoft Teams direct
          messages.
        </li>
      </ul>
    </>
  }
/>

### Complete sample code

Here's an example of these components in a React application.

```javascript title="Store Knock and Microsoft Teams credentials as .env vars"
// .env

KNOCK_PUBLIC_API_KEY = "pk_test_12345";
KNOCK_MS_TEAMS_CHANNEL_ID = "2e0e37c3-751b-4be5-a684-8296009e960e";

MS_TEAMS_BOT_ID = "f1b85cf4-58e1-4cef-8d3f-ce6ccf60734d";
```

<br />

```javascript title="Providers wrap your UI components"
<KnockProvider
  apiKey={process.env.KNOCK_PUBLIC_API_KEY}
  userId={currentUser.id}
  userToken={localStorage.getItem("knock-user-token")}
>
  <KnockMsTeamsProvider
    knockMsTeamsChannelId={process.env.KNOCK_MS_TEAMS_CHANNEL_ID}
    tenantId={currentAccount.id}
  >
    <NotificationSettings />
    <VideoProjectsIndex />
  </KnockMsTeamsProvider>
</KnockProvider>
```

<br />

```javascript title="Render your MsTeamsAuthButton inside of KnockMsTeamsProvider"
const NotificationSettings = () => {
  return (
    <MsTeamsAuthContainer
      actionButton={
        <MsTeamsAuthButton
          msTeamsBotId={process.env.MS_TEAMS_BOT_ID}
          redirectUrl={"www.my-example-app.com/notification-settings"}
        />
      }
    />
  );
};
```

<br />

```javascript title="Render an MsTeamsChannelCombobox for each object"

const VideoProjectsPage = ({videos}) => {
    return (
        videos.map(video => {
            return <VideoPage {video} />
        })
    )
}

const VideoPage = ({video}) => {
  return (
    <div>
      <div>{video.name}</div>
      <div>{video.content}</div>
      <div>{video.comments}</div>
      <MsTeamsChannelCombobox
        msTeamsChannelsRecipientObject={{
          id: video.id,
          collection: "videos",
        }}
      />
    </div>
  )
}

```

<br />

## Using TeamsKit headless

If you need custom designs or want to display additional information around your Microsoft Teams integration, you don't need to use Knock's pre-built components to take advantage of TeamsKit.

TeamsKit exposes three levels of support: React hooks, client functions, and API endpoints.

### Hooks

You can use the [Microsoft Teams React hooks](/sdks/react/reference#microsoft-teams-hooks) under the hood to access and set Microsoft Teams integration data with your own components. All of them are available from the `@knocklabs/react-core` package. All of them must still be nested under the `KnockMsTeamsProvider` to work.

To use a hook in your component, all you need to to is import it and pass it the necessary params, and then you can use the data and functions returned in each to pass to your own component UI.

### Client functions

If you want more fine grain control of your data, you can skip the hooks and simply use the functions Knock exposes in the [`@knocklabs/client` library](https://github.com/knocklabs/javascript/tree/main/packages/client) as long as you wrap the component you're calling it in inside of `KnockProvider`. You can accomplish anything we provide with hooks or the components with the following functions:

- `knock.msTeams.authCheck`: Get the status of Microsoft Teams authorization
- `knock.msTeams.getTeams`: Get a list of teams in the connected Microsoft Entra tenant
- `knock.msTeams.getChannels`: Get a list of Microsoft Teams channels within a single team
- `knock.msTeams.revokeAccessToken`: Removes the Microsoft Entra tenant ID from the tenant
- `knock.objects.getChannelData`: Use this to get the connected channels stored as channel data on the recipient object
- `knock.objects.setChannelData`: Use this to set the connected channels for a recipient object or an access token for a tenant

### API endpoints

Lastly, you can interact directly with the API endpoints for all of the above functionality. Here are the endpoints used in TeamsKit that you would need to support an implementation of the managed UI:

- [Microsoft Teams auth check](/reference#ms-teams-auth-check): status of Microsoft Teams authorization
- [Microsoft Teams teams](/reference#ms-teams-teams): list of teams in the connected Microsoft Entra tenant
- [Microsoft Teams channels](/reference#ms-teams-channels): list of Microsoft Teams channels within a single team
- [Microsoft Teams revoke access](/reference#ms-teams-revoke-access): remove a Microsoft Entra tenant ID from a Knock tenant
- [Get channel data](/reference#get-object-channel-data): get channel data for your recipient object, which gives you access to the connected Microsoft Teams channels
- [Set channel data](/reference#set-object-channel-data): set channel data for your recipient object, which allows you to set connected Microsoft Teams channels

## Resource access grants

The only access you'll need to manage when using TeamsKit are grants for your users to interact with their [Tenants](/concepts/tenants) and [Objects](/concepts/objects) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

### With the Node SDK

You'll need to generate a token for your user that includes access to the tenant storing the Microsoft Entra tenant ID as well as any recipient objects storing Teams channel data as described in [Microsoft Teams notifications with Knock](/integrations/chat/microsoft-teams/overview#channel-data-requirements). If you need to enable access to multiple recipient objects, you can include multiple grants in the user token.

Example:

- Tenant ID: `jurassic-park`
- Recipient object collection: `videos`
- Recipient object ID: `dinosaurs-loose`

Using the above example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "jurassic-park" }, [
      Grants.MsTeamsChannelsRead,
    ]),
    Knock.buildUserTokenGrant(
      { type: "object", id: "dinosaurs-loose", collection: "videos" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
    Knock.buildUserTokenGrant(
      { type: "object", id: "raptor-feeding-guide", collection: "videos" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockMsTeamsProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Other languages

If you're not using the Node SDK, you can still generate a user token using a JWT signing library in your preferred language. Here's an [example of using Joken for the Elixir library](https://github.com/knocklabs/knock-elixir?tab=readme-ov-file#signing-jwts). You'll include the `grants` key in the root of the payload and put your resource grants in there. We'll go into detail about how they work below, but if you want to skip that and just get started, here's what that will look like in a given JWT payload for the example above:

```json
{
  "sub": "user123",
  "grants": {
    "https://api.knock.app/v1/objects/$tenants/jurassic-park": {
      "ms_teams/channels_read": [{}]
    },
    "https://api.knock.app/v1/objects/videos/dinosaurs-loose": {
      "channel_data/read": [{}],
      "channel_data/write": [{}]
    }
  }
}
```

Continue reading for a deeper dive on access and how these grants are structured.

### Grants in the user token

You may already be familiar with generating a user token to be used with your public API key when making client side calls if you've used [authentication with enhanced security](/in-app-ui/security-and-authentication#authentication-with-enhanced-security). You'll use the same process to generate the user token as described here, including signing it with an RS256 algorithm using your private signing key, but you'll also be sending a list of grants that the user needs to work with TeamsKit.

The two resources you'll be granting access to are:

- **The tenant**: the user needs access to this because this is where Knock stores the Microsoft Entra tenant ID (`ms_teams_tenant_id`) that will be used to send a notification as your Microsoft Teams bot
- **The recipient object**: the user needs access to this because this is where Knock is storing the connected Microsoft Teams channels as channel data on the object

These resources need different permissions. Here are the permissions needed for each:

- **Tenant**: reading Microsoft Teams channels
- **Recipient Object**: reading channel data; writing channel data

### How the grants are structured

Resource access grants in Knock are structured according to the [UCAN spec](https://github.com/ucan-wg/spec). They consist of an array of maps, with each map representing a resource.

How to read a resource grant:

```json
{
  "Knock endpoint of the resource": {
    "Name of access type being granted/Specific permission being granted": [
      "List of exceptions"
    ]
  }
}
```

So to grant access for a user to read the channel data of object `dinosaurs-loose` in the `videos` collection, your grant would look like this:

```json
{
  "https://api.knock.app/v1/objects/videos/dinosaurs-loose": {
    "channel_data/read": [{}]
  }
}
```

### Availability of resource access grants

Currently these grants are only implemented for use by TeamsKit as described in this doc, and since exceptions are not used for these they will not be respected.


## Filtering feeds
Learn how to use Knock's feed filtering to scope in-app feeds to display information relevant to a particular tenant, resource, or individual workflow.
---
title: Filtering in-app feeds
description: Learn how to use Knock's feed filtering to scope in-app feeds to display information relevant to a particular tenant, resource, or individual workflow.
section: Guides
---

When building an in-app notifications UI, you may wish to filter the notifications a user has received to increase the relevancy of the notifications displayed. This can be useful to power per-tenant notifications in a multi-tenant SaaS application or per-resource notifications to show contextual notifications inside your product.

In this guide, we walk through how to do this by filtering the feed API using the `defaultFeedOptions` which will filter all of the results returned, including the real-time updates sent to the in-app feed and the badge count for unseen or unread notifications.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> the feed client accepts default
      options, which will be applied in the initial feed fetch and to scope
      real-time updates. This guide shows examples of setting those defaults.
      Default values can also be overridden when calling the <code>fetch</code>{" "}
      function as well.
    </>
  }
/>

## Filtering by tenant

In a multi-tenant SaaS application, individual users might belong to one or more tenants, meaning the notifications they see should be scoped to the tenant they are currently viewing.

For example, imagine we have a user `jane` in a document editing app. Jane's user profile is connected to multiple workspaces; `acme-inc` and `superior-products`. When Jane is active in the `acme-inc` workspace, she should only see notifications that are relevant for that workspace.

We include this concept in Knock as [Tenancy](/concepts/tenants), where workflow triggers can be “tagged” with a particular tenant identifier, which can be used to apply tenant overrides and to scope in-app notifications by the tenant. Let's see how this works in practice.

```js title="Triggering our workflow with a tenant"
await knock.workflows.trigger("new-comment", {
  recipients: ["jane"],
  data: {
    pageId: page.id,
    commentId: comment.id,
  },
  tenant: workspace.id,
});
```

Now when we render our in-app feed we can scope the feed by the tenant that our user is currently active in:

```javascript title="Rendering our feed with the tenant filter"
// Passed to our component
<KnockFeedProvider
  feedId={process.env.KNOCK_FEED_CHANNEL_ID}
  defaultFeedOptions={{ tenant: "acme-inc" }}
/>;

// Passed to the `useNotifications` hook as `FeedClientOptions`
useNotifications(knockClient, process.env.KNOCK_FEED_CHANNEL_ID, {
  tenant: "acme-inc",
});
```

By default, filtering by a tenant will include all notifications on the feed that include that tenant or any notifications sent without a tenant identifier. If you need different behavior here, you can pass `has_tenant: true` which, when combined with the `tenant` filter, will return only notifications for that tenant.

## Filtering by workflow

Sometimes you might want to only show an individual workflow's notifications within an in-app feed for a user. You can use the `source` filter to achieve this. Let's look at an example.

In our document collaboration application, we only want to return all notifications produced by the `new-comment` workflow. To do so, we can set the `defaultFeedOptions` source to be `new-comment`:

```js title="Filtering our in-app feed by source"
// Passed to our component
<KnockFeedProvider
  feedId={process.env.KNOCK_FEED_CHANNEL_ID}
  defaultFeedOptions={{ source: "new-comment" }}
/>;

// Passed to the `useNotifications` hook as `FeedClientOptions`
useNotifications(knockClient, process.env.KNOCK_FEED_CHANNEL_ID, {
  source: "new-comment",
});
```

It's important to note here that at this time, we don't support filtering by multiple sources.

## Filtering by `data`

You can filter the feed by properties in the `data` payload to your trigger step. This is a powerful and flexible way to query the feed data you can use to match against entities in your system. Let's look at an example.

Imagine that we want to show all of the comment notifications the current user has received for a given `page` in our document editing app. In our workflow trigger, we might send the internal identifier from our system as `pageId` in the `data` payload:

```js title="Triggering a workflow with data"
await knock.workflows.trigger("new-comment", {
  recipients: recipientIds,
  data: {
    pageId: page.id,
    commentId: comment.id,
  },
});
```

Now when we're filtering the feed to be rendered in our application, we can pass the `trigger_data` filter to `defaultFeedOptions`.

```js title="Filtering our in-app feed by trigger data"
// Passed to our component
<KnockFeedProvider
  feedId={process.env.KNOCK_FEED_CHANNEL_ID}
  defaultFeedOptions={{ trigger_data: { pageId } }}
/>;

// Passed to the `useNotifications` hook as `FeedClientOptions`
useNotifications(knockClient, process.env.KNOCK_FEED_CHANNEL_ID, {
  trigger_data: { pageId },
});
```

This approach also has some caveats you should be aware of:

- You can only filter by top-level keys and values in your data payload, meaning it's not possible to query `data.foo.bar` but is possible to query `data.foo`
- You can only match absolute values for the keys (e.g. no partial matches or other comparison operators are supported)

## Learn more about feed filtering

You can see all of the filtering options that the feed takes in the [API reference](/reference#get-feed). These are exposed directly to the feed via the `FeedClientOptions` type that's supported in the constructor for the feed to apply defaults, or in each individual fetch function if you need to override the defaults on an individual fetch basis.


## Customizing feed components
Learn how to override the default styles of the pre-built React in-app feed components that Knock provides.
---
title: Customizing the in-app feed components
description: Learn how to override the default styles of the pre-built React in-app feed components that Knock provides.
tags:
  ["feed styles", "feed css", "react css", "react styles", "override styles"]
section: Guides
---

As a refresher, our [in-app feed components](/in-app-ui/react/overview) let you drop in a ready-to-use in-app notification feed into your product, powered by Knock's in-app feed and real-time service.

In some applications, you may want to override the styles provided in the React components, or even replace those styles completely. In this guide, we'll look at the options you have for customizing the styles provided with the Knock React components.

## Customizing the CSS variables

If you're importing the CSS styles associated with the components, then it's possible to use [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) to override the majority of the properties used within the stylesheet, such as colors, font sizes, ad more.

The CSS variables that are used within the components are all prefixed with `--rnf-`. The complete set of overrides is here, for reference, or available in the [theme.css file](https://raw.githubusercontent.com/knocklabs/javascript/main/packages/react/src/theme.css).

```css
:root {
  /* Font sizes */
  --rnf-font-size-xs: 0.75rem;
  --rnf-font-size-sm: 0.875rem;
  --rnf-font-size-md: 1rem;
  --rnf-font-size-lg: 1.125rem;
  --rnf-font-size-xl: 1.266rem;
  --rnf-font-size-2xl: 1.5rem;
  --rnf-font-size-3xl: 1.75rem;

  /* Spacing */
  --rnf-spacing-0: 0;
  --rnf-spacing-1: 4px;
  --rnf-spacing-2: 8px;
  --rnf-spacing-3: 12px;
  --rnf-spacing-4: 16px;
  --rnf-spacing-5: 20px;
  --rnf-spacing-6: 24px;
  --rnf-spacing-7: 32px;
  --rnf-spacing-8: 42px;

  /* Font weights */
  --rnf-font-weight-normal: 400;
  --rnf-font-weight-medium: 500;
  --rnf-font-weight-semibold: 600;
  --rnf-font-weight-bold: 700;

  /* Font family */
  --rnf-font-family-sanserif: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI",
    Roboto, Ubuntu, "Helvetica Neue", sans-serif;

  /* Border radius */
  --rnf-border-radius-sm: 2px;
  --rnf-border-radius-md: 4px;
  --rnf-border-radius-lg: 8px;

  /* Shadows */
  --rnf-shadow-sm: 0px 5px 10px rgba(0, 0, 0, 0.12);
  --rnf-shadow-md: 0px 8px 30px rgba(0, 0, 0, 0.24);

  /* Colors */
  --rnf-color-white: #fff;
  --rnf-color-white-a-75: rgba(255, 255, 255, 0.75);
  --rnf-color-black: #000;
  --rnf-color-gray-900: #1a1f36;
  --rnf-color-gray-800: #3c4257;
  --rnf-color-gray-700: #3c4257;
  --rnf-color-gray-600: #515669;
  --rnf-color-gray-500: #697386;
  --rnf-color-gray-400: #9ea0aa;
  --rnf-color-gray-300: #a5acb8;
  --rnf-color-gray-200: #dddee1;
  --rnf-color-gray-100: #e4e8ee;
  --rnf-color-brand-500: #e95744;
  --rnf-color-brand-700: #e4321b;
  --rnf-color-brand-900: #891e10;

  /* Component specific colors */
  --rnf-unread-badge-bg-color: #dd514c;
  --rnf-avatar-bg-color: #ef8476;
  --rnf-message-cell-unread-dot-bg-color: #f4ada4;
  --rnf-message-cell-hover-bg-color: #f1f6fc;
}
```

Within your own application, you can add overrides by targeting the same properties and ensuring your styles are loaded **after** the CSS of the component. For example, to override the unread badge color:

```css title="feed-overrides.css"
:root {
  --rnf-unread-badge-bg-color: #cccccc;
}
```

Then we'd import like:

```javascript
// Default styles
import "@knocklabs/react/dist/index.css";

// Overrides
import "~/styles/feed-overrides.css";
```

## Overriding the component CSS

If you need more fine-grained control over the CSS provided by the components, it's also possible to override the CSS that's provided by the components, entirely or partially.

All of the notification feed components have classes prefixed with `rnf-`. You can see the existing CSS styles here, which are written using CSS modules to be isolated per component.

- [NotificationFeed](https://github.com/knocklabs/javascript/blob/main/packages/react/src/modules/feed/components/NotificationFeed/styles.css)
- [NotificationFeedPopover](https://github.com/knocklabs/javascript/blob/main/packages/react/src/modules/feed/components/NotificationFeedPopover/styles.css)
- [NotificationCell](https://github.com/knocklabs/javascript/blob/main/packages/react/src/modules/feed/components/NotificationCell/styles.css)
- [EmptyFeed](https://github.com/knocklabs/javascript/blob/main/packages/react/src/modules/feed/components/EmptyFeed/styles.css)

### Partially overriding the feed CSS

To partially override the CSS of the feed, we can rely on the cascading nature of CSS to ensure that any overrides we define take precedence over the base styles.

**Note**: depending on how you have your CSS imports defined in your application, you may have to use `!important` declarations to override the styles that the library defines.

Let's look at an example where we override the color of the unread dot:

```css title="feed-overrides.css"
.rnf-notification-cell__unread-dot {
  background-color: #cccccc;
}
```

And when we import those styles, we'll want to ensure our overrides are imported after we import the base CSS styles for the feed.

```javascript
// Default styles
import "@knocklabs/react/dist/index.css";

// Overrides
import "~/styles/feed-overrides.css";
```

### Fully overriding the feed CSS

To override all of the CSS provided by the components you should **not** import the base CSS that the components exports. This will mean that you then need to provide CSS for each of the components that the feed renders yourself.

Please refer to the CSS class names that the components use for the classes that you'll need to add.

## Rendering custom feed cells

If you need to control the style or behavior of each item rendered in the feed, you can use the `renderItem` callback prop within the `NotificationFeed` or `NotificationFeedPopover` to render custom feed cells.

The `renderItem` prop receives a set of props, including the `FeedItem` and is called for every item being rendered in the feed. From here, you can render your own feed cell, complete with any custom styles or interactions you might need.

Here's an example:

```jsx title="Custom feed cell"
const CustomNotificationCell = ({ item, onItemClick }) => (
  <Container>
    {item.actor && <Avatar name={item.actor.name} src={item.actor.avatar} />}
    <Inner>
      <div dangerouslySetInnerHTML={{ __html: item.blocks[0].rendered }} />
    </Inner>
  </Container>
);
```

And to render the custom cell in your `NotificationFeedPopover` or `NotificationFeed` component:

```jsx title="Custom cell rendering"
<NotificationFeedPopover
  renderItem={(props) => <CustomNotificationCell {...props} />}
/>
```

## Rendering custom UI

If you need even more control over the components rendered in the feed, it's also possible to bring your own set of components and use either the provided hooks or `KnockFeedProvider` component to run Knock in a "headless" manner. Using this option gives you the most control over the style and interaction with the components, with the trade-off that you have to provide the components yourself.

### Using hooks to render custom UI

The React component library ships with hooks that you can use to set up and manage your Knock client and feed connection. You can then use these hooks to provide the data for your own custom feed components. Let's take a look at what that looks like.

First of all, we need to use the `useAuthenticatedKnockClient` hook to create a Knock client instance, authenticated for the user that's provided.

```jsx title="Setting up a Knock client"
import { useAuthenticatedKnockClient } from "@knocklabs/react";

const NotificationFeed = ({ user }) => {
  const knockClient = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
  );

  return null;
};
```

Next up, we then set up our feed instance using the `useNotifications` hook. This hook expects to receive a Knock client instance, as well as information about the feed that we wish to connect to.

```jsx title="Using our notifications hook"
import {
  useAuthenticatedKnockClient,
  useNotifications,
} from "@knocklabs/react";

const NotificationFeed = ({ user }) => {
  const knockClient = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
  );
  const feed = useNotifications(knockClient, process.env.KNOCK_FEED_CHANNEL_ID);

  return null;
};
```

Now we have our Feed instance, then we need to have a way to access the state of that feed and initiate the fetch when the component mounts. Here we're using Zustand, which is the state management library that sits behind the feed instance.

```jsx title="Using the feed instance"
import {
  useAuthenticatedKnockClient,
  useNotifications,
} from "@knocklabs/react";
import create from "zustand";
import { useEffect } from "react";

const NotificationFeed = ({ user }) => {
  const knockClient = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
  );
  const feed = useNotifications(knockClient, process.env.KNOCK_FEED_CHANNEL_ID);

  const useNotificationStore = create(feed.store);
  const { items, metadata } = useNotificationStore();

  useEffect(() => feed.fetch(), [feed]);

  return null;
};
```

With our component set up, we have all the building blocks we need to build our in-app feed. The items that we're returning give us the list of items fetched and available in the feed, while the metadata gives us information about the total number of items in the feed as well as the unread and unseen counts, which we can use to render badges.

### Using the `KnockFeedProvider` to render custom UI

The `KnockFeedProvider` can also be used to set up the feed instance and build custom UI, which is what the pre-built components use under the hood.

The first step is to set up a wrapper component that will render your Feed with the `KnockProvider` and `KnockFeedProvider`:

```jsx title="Setting up our feed provider"
import { KnockProvider, KnockFeedProvider } from "@knocklabs/react";

const NotificationFeed = ({ user }) => (
  <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={user.id}>
    <KnockFeedProvider
      feedId={process.env.KNOCK_FEED_CHANNEL_ID}
    ></KnockFeedProvider>
  </KnockProvider>
);
```

Now that our provider is set up, we're going to split out a subcomponent that will be used to render the actual contents of the feed. The reason we have this as a separate component is so we can access the context that the `KnockFeedProvider` exposes.

```jsx title="Implementing our feed component"
import { useKnockFeed } from "@knocklabs/react";

const Feed = () => {
  const { useFeedStore } = useKnockFeed();
  const { items, metadata } = useFeedStore();

  // Render your feed components here
  return null;
};
```

Note here we're using the `useFeedStore` hook that the `useKnockFeed` hook returns. This is a wrapper around the `create` function that Zustand exposes to make it easy to work with the state store in the feed instance.

And finally, to put it all together:

```jsx title="Our working custom feed"
import { KnockFeedProvider } from "@knocklabs/react";
import Feed from "~/components/Feed";

const NotificationFeed = ({ user }) => (
  <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={user.id}>
    <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
      <Feed />
    </KnockFeedProvider>
  </KnockProvider>
);
```


## Javascript

## Overview
Learn more about the in-app notification UI you can build in your web application with Knock.
---
title: "Building in-app UI in Javascript (Web)"
description: Learn more about the in-app notification UI you can build in your web application with Knock.
section: Building in-app UI
---

<Callout
  emoji="💡"
  text={
    <>
      If you're looking to use pre-built in-app UI elements for a web
      application, you can look at{" "}
      <a href="/in-app-ui/react/overview">React components</a>.
    </>
  }
/>

The Knock Javascript client SDK is a low-level set of methods for interacting with the Knock APIs from client-side Javascript web applications. The SDK is designed to help you easily integrate Knock into your application and build in-app notification experiences powered by Knock.

## Features

- API methods for interacting with the [Knock in-app API](/in-app-ui/api-overview).
- Managed websocket connections to the Knock real-time service.
- State management for powering in-app feeds, with optimistic client-side updates.

## Getting started

```bash title="Installing the package"
npm install @knocklabs/client
```

## Links

- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Package on GitHub](https://github.com/knocklabs/javascript/tree/main/packages/client)
- [Javascript SDK reference](/sdks/javascript/reference)
- [Javascript SDK quick start](/sdks/javascript/quick-start)


## Angular

## Overview
Learn more about the in-app notifications experiences you can build in Angular with Knock.
---
title: "Building in-app UI in Angular"
description: Learn more about the in-app notifications experiences you can build in Angular with Knock.
section: Building in-app UI
---

Today we do not have Knock-built, out-of-the-box Angular components for in-app notifications UI.

Our Knock community built this [Angular in-app feed example](https://github.com/knocklabs/angular-in-app-feed-example) you can use to get started with an Angular in-app feed in your own application.

If you have any questions, or if you have an in-app use case that is blocking your adoption of Knock, please [contact our sales team](https://knock.app/contact-sales).


## React Native

## Overview
Learn more about the in-app notification UI you can build in your React Native application with Knock.
---
title: "Building in-app UI in React Native"
description: Learn more about the in-app notification UI you can build in your React Native application with Knock.
section: Building in-app UI
---

The Knock React Native SDK provides pre-built UI components that you can use to easily get up and running with a fully functional notification feed experience in your product. You can also use a set of React hooks and API bindings for you to build custom UI on top of to power in-app notification experiences in your React Native applications.

## Features

- API methods for interacting with the [Knock in-app API](/in-app-ui/api-overview).
- Managed websocket connections to the Knock real-time service.
- State management for powering in-app feeds, with optimistic client-side updates.

## Getting started

Please reference our [React Native SDK documentation](/sdks/react-native/quick-start) to set up the library.

```bash title="Install the Knock React Native SDK"
npm install @knocklabs/react-native
```

When using React Native with Expo, install [our Expo SDK](/sdks/expo/overview) instead:

```bash title="Install the Knock Expo SDK"
npm install @knocklabs/expo
```

### In-app notifications

- `NotificationFeed`: A full-page list of notifications.
- `NotificationIconButton`: A button with a badge count for notifications, often used to open the `NotificationFeed`.

## Guides

- [**Notification feed**](/in-app-ui/react-native/notification-feeds): Learn how to build an in-app feed powered by Knock in your React Native application.

## Links

- [React Native SDK reference](/sdks/react-native/reference)
- [Expo SDK reference](/sdks/expo/reference)
- [Javascript SDK reference](/sdks/javascript/reference)
- [`@knocklabs/react-native` on npm](https://www.npmjs.com/package/@knocklabs/react-native)
- [`@knocklabs/expo` on npm](https://www.npmjs.com/package/@knocklabs/expo)


## Components
How to use Knock's UI components in your React Native application.
---
title: "React Native SDK pre-built components"
description: "How to use Knock's UI components in your React Native application."
section: Building in-app UI
---

<Callout
  emoji="ℹ️"
  text={
    <>
      <strong>Migration note.</strong> The{" "}
      <code>NotificationFeedContainer</code> component is deprecated and has
      been replaced with <code>NotificationFeed</code>. The container component
      will be removed in a future release.
    </>
  }
/>

## NotificationFeed

### Overview

`NotificationFeed` is a React component that renders a list of notifications using data from Knock. It provides a customizable and interactive user interface for displaying notifications within your React Native application.

### Properties

<Attributes>
  <Attribute
    name="initialFilterStatus"
    type="FilterStatus"
    description="The initial filter applied to the notification feed. Defaults to 'All'."
  />
  <Attribute
    name="notificationRowStyle"
    type="NotificationFeedCellStyle"
    description="Customizes the style of the notification rows in the feed."
  />
  <Attribute
    name="headerConfig"
    type="NotificationFeedHeaderConfig"
    description="Configures the header of the notification feed."
  />
  <Attribute
    name="emptyFeedStyle"
    type="EmptyNotificationFeedStyle"
    description="Customizes the appearance of the empty state when there are no notifications."
  />
  <Attribute
    name="onCellActionButtonTap"
    type="(params: { button: ActionButton, item: FeedItem }) => void"
    description="Callback triggered when an action button in a notification row is tapped."
  />
  <Attribute
    name="onRowTap"
    type="(item: FeedItem) => void"
    description="Callback triggered when a notification row is tapped."
  />
</Attributes>

### Examples

```tsx
import {
  KnockFeedProvider,
  KnockProvider,
  NotificationIconButton,
} from "@knocklabs/react-native";
import React, { useCallback, useState } from "react";
import { StyleSheet, View, StatusBar } from "react-native";

// Your custom notification container component; see code example below
import NotificationContainer from "./NotificationContainer";

const App: React.FC = () => {
  const [isNotificationFeedOpen, setIsNotificationFeedOpen] = useState(false);
  const onTopActionButtonTap = useCallback(() => {
    setIsNotificationFeedOpen(!isNotificationFeedOpen);
  }, [isNotificationFeedOpen]);

  return (
    <KnockProvider
      apiKey={process.env.KNOCK_PUBLIC_API_KEY}
      host={process.env.KNOCK_HOST}
      userId={process.env.KNOCK_USER_ID}
      logLevel="debug"
    >
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
        <View style={styles.container}>
          <StatusBar />
          {!isNotificationFeedOpen && (
            <NotificationIconButton
              onClick={onTopActionButtonTap}
              badgeCountType={"unread"}
            />
          )}
          {isNotificationFeedOpen && (
            <NotificationContainer
              handleClose={() =>
                setIsNotificationFeedOpen(!isNotificationFeedOpen)
              }
            />
          )}
        </View>
      </KnockFeedProvider>
    </KnockProvider>
  );
};

export default App;
import { NotificationFeed, FilterStatus } from "@knocklabs/react-native";

const MyNotificationFeed = () => {
  return (
    <NotificationFeed
      initialFilterStatus={FilterStatus.Unread}
      onCellActionButtonTap={({ button, item }) => {
        console.log("Action button tapped", button, item);
      }}
      onRowTap={(item) => {
        console.log("Row tapped", item);
      }}
    />
  );
};
```

<br />

```tsx
import { ActionButton, FeedItem } from "@knocklabs/client";
import { NotificationFeed } from "@knocklabs/react-native";
import React, { useCallback } from "react";
import { StyleSheet, Text, TouchableOpacity, View } from "react-native";

export interface NotificationContainerProps {
  handleClose: () => void;
}

const NotificationContainer: React.FC<NotificationContainerProps> = ({
  handleClose,
}) => {
  const onCellActionButtonTap = useCallback(
    (params: { button: ActionButton; item: FeedItem }) => {
      // handle button tap
    },
    [],
  );

  const onRowTap = useCallback((item: FeedItem) => {
    // handle row tap
  }, []);

  return (
    <View style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.title}>Notifications</Text>
        <TouchableOpacity onPress={handleClose} style={styles.closeButton}>
          <Text style={styles.closeButtonText}>X</Text>
        </TouchableOpacity>
      </View>
      <NotificationFeed
        onCellActionButtonTap={onCellActionButtonTap}
        onRowTap={onRowTap}
      />
    </View>
  );
};

export default NotificationContainer;
```

## NotificationIconButton

### Overview

`NotificationIconButton` is a React component that renders a button with a badge showing the count of unread or unseen notifications. This can be used to open the `NotificationFeed` when tapped.

### Properties

<Attributes>
  <Attribute
    name="onClick"
    type="() => void"
    description="Callback triggered when the button is pressed."
  />
  <Attribute
    name="badgeCountType"
    type="BadgeCountType"
    description="Specifies whether to display the count of 'unread', 'unseen', or 'all' notifications."
  />
  <Attribute
    name="styleOverride"
    type="ViewStyle"
    description="Customizes the overall style of the button."
  />
</Attributes>

### Example

```tsx
import { NotificationIconButton } from "@knocklabs/react-native";

const MyApp = () => {
  return (
    <NotificationIconButton
      onClick={() => {
        console.log("Notification icon button clicked");
      }}
      badgeCountType="unread"
    />
  );
};
```


## Customization
How to customize the UI of our pre-built components for React Native.
---
title: "Customizing Knock UI components in React Native"
description: "How to customize the UI of our pre-built components for React Native."
section: Building in-app UI
---

## NotificationFeedCellStyle

### Overview

`NotificationFeedCellStyle` allows for UI customization of the rows in the `NotificationFeed`.

### Properties

<Attributes>
  <Attribute
    name="unreadNotificationCircleColor"
    type="string"
    description="Color of the unread circle indicator in the top left of the row."
  />
  <Attribute
    name="showAvatarView"
    type="boolean"
    description="Determines whether to show the avatar/initials view in the upper left corner of the row."
  />
  <Attribute
    name="avatarViewStyle"
    type="AvatarViewStyle"
    description="Customizes the styling of the avatar view."
  />
  <Attribute
    name="primaryActionButtonStyle"
    type="ActionButtonStyle"
    description="Customizes the styling of primary action buttons."
  />
  <Attribute
    name="secondaryActionButtonStyle"
    type="ActionButtonStyle"
    description="Customizes the styling of secondary action buttons."
  />
  <Attribute
    name="tertiaryActionButtonStyle"
    type="ActionButtonStyle"
    description="Customizes the styling of tertiary action buttons."
  />
  <Attribute
    name="sentAtDateFormatter"
    type="Intl.DateTimeFormat"
    description="Formatter for the sent timestamp at the bottom of the row."
  />
  <Attribute
    name="sentAtDateTextStyle"
    type="TextStyle"
    description="Text style for the sent timestamp."
  />
  <Attribute
    name="htmlStyles"
    type="Record<string, TextStyle | ViewStyle | ImageStyle>"
    description="Customizes the CSS styles of the HTML content in the notification body."
  />
</Attributes>

## EmptyNotificationFeedStyle

### Overview

`EmptyNotificationFeedStyle` allows for UI customization of the empty state view when there are no notifications in the `NotificationFeed`.

### Properties

<Attributes>
  <Attribute
    name="titleString"
    type="string"
    description="The title text displayed when the feed is empty."
  />
  <Attribute
    name="subtitleString"
    type="string"
    description="The subtitle text displayed when the feed is empty."
  />
  <Attribute
    name="titleStyle"
    type="TextStyle"
    description="Customizes the style of the title text."
  />
  <Attribute
    name="subtitleStyle"
    type="TextStyle"
    description="Customizes the style of the subtitle text."
  />
  <Attribute
    name="iconStyle"
    type="ImageStyle"
    description="Customizes the style of the icon displayed in the empty state view."
  />
  <Attribute
    name="icon"
    type="string"
    description="The URL or local path to the icon image displayed in the empty state view."
  />
</Attributes>

## ActionButtonStyle

### Overview

`ActionButtonStyle` allows for UI customization of the action buttons in the `NotificationFeed`.

### Properties

<Attributes>
  <Attribute
    name="buttonContainerStyle"
    type="ViewStyle"
    description="Customizes the container style of the action button."
  />
  <Attribute
    name="buttonTextStyle"
    type="TextStyle"
    description="Customizes the text style of the action button."
  />
  <Attribute
    name="buttonIconStyle"
    type="ImageStyle"
    description="Customizes the icon style of the action button."
  />
</Attributes>

## AvatarViewStyle

### Overview

`AvatarViewStyle` allows for UI customization of the avatar view in the `NotificationFeed`.

### Properties

<Attributes>
  <Attribute
    name="container"
    type="ViewStyle"
    description="Customizes the overall container style of the avatar view."
  />
  <Attribute
    name="image"
    type="ImageStyle"
    description="Customizes the image style of the avatar view."
  />
  <Attribute
    name="text"
    type="TextStyle"
    description="Customizes the text style for initials when no avatar image is available."
  />
</Attributes>


## Custom notifications UI (headless)
How to build custom notifications UI using the hooks from the Knock React Native SDK.
---
title: "Building custom notifications UI with hooks (headless)"
description: How to build custom notifications UI using the hooks from the Knock React Native SDK.
section: Building in-app UI
tags: ["hooks", "headless", "useNotifications", "useAuthenticatedKnockClient"]
---

Using our `@knocklabs/react-native` library, you can create fully custom notification UIs that are backed by the Knock Feed API and real-time service.

In this guide, you'll find common recipes to help you build in-app feed experiences within your React Native applications in a headless way using the Knock hooks. The SDK handles all aspects of managing the data surrounding notifications on your behalf, including managing unread badge counts.

**Quick links**:

- [`@knocklabs/react-native` library reference](/sdks/react-native/reference)
- [`@knocklabs/client` library reference](/sdks/javascript/reference)

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

## Installing dependencies

```bash title="Install the Knock React Native SDK"
npm install @knocklabs/react-native
```

When using React Native with Expo, install [our Expo SDK](/sdks/expo/overview) instead:

```bash title="Install the Knock Expo SDK"
npm install @knocklabs/expo
```

## Rendering a notification feed

<Callout emoji="🔐"
  text={
    <>
      <strong>Secure your feed. </strong> By default, Knock
      feeds are accessible to anyone who has the feed ID. This makes it
      easy to get started in development. To secure your feed for production,
      enable enhanced security mode in your Knock dashboard and pass a signed
      {" "}<code>userToken</code> as a prop to the <code>KnockFeedProvider</code> component.

      For more information, visit <a href="/in-app-ui/security-and-authentication">the security & authentication guide</a> for client-side applications.
    </>

}
/>

### Using the `KnockProvider` and `KnockFeedProvider`

```jsx
import { useEffect } from "react";
import { KnockProvider, KnockFeedProvider, useKnockFeed } from "@knocklabs/react-native";

const YourApp = () => {
  const currentUser = useCurrentUser();

  return (
    <KnockProvider
      apiKey={process.env.KNOCK_PUBLIC_API_KEY}
      userId={currentUser.id}
      // In production, you must pass a signed userToken
      // and enable enhanced security mode in your Knock dashboard
      // userToken={currentUser.knockUserToken}
    >
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
        <NotificationFeed />
      </KnockFeedProvider>
    </KnockProvider>
  );
};

const NotificationFeed = () => {
  const { useFeedStore, feedClient } = useKnockFeed();
  const { items, metadata } = useFeedStore();

  // Fetch the feed
  useEffect(() => feedClient.fetch(), [feedClient]);

  return (
    <View>
      <Text>Total unread: {metadata.unread_count}</Text>
      {items.map(item => (
        <View key={item.id}>
          {/* Notification cell goes here */}
        </View>
      )}
    </View>
  )
};
```

### Using the `useNotifications` hook

```jsx
import {
  useAuthenticatedKnockClient,
  useNotifications,
  useNotificationStore
} from "@knocklabs/react-native";

const MyNotificationsFeed = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  const notificationFeed = useNotifications(
    knock,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { metadata, items } = useNotificationStore(notificationFeed);

  // Fetch the feed contents
  useEffect(() => {
    notificationFeed.fetch();
  }, [notificationFeed]);

  return (
    <View>
      <Text>Total unread: {metadata.unread_count}</Text>
      {items.map(item => (
        <View key={item.id}>
          {/* Notification cell goes here */}
        </View>
      )}
    </View>
  );
};
```

## Common feed recipes

### Filtering/scoping a feed

A feed can be scoped by any of the parameters that are accepted on the [feed endpoint](/reference#get-feed) via the `FeedClientOptions` set in the `defaultFeedOptions` for the `KnockFeedProvider` component, or via the `useNotifications` hook.

You can read more in this [guide on feed filtering](/in-app-ui/react/filtering-in-app-feeds).


## iOS (Swift)

## Overview
Learn more about the in-app notifications experiences you can build for iOS and macOS applications with Knock.
---
title: "Building in-app UI for iOS and macOS"
description: Learn more about the in-app notifications experiences you can build for iOS and macOS applications with Knock.
section: Building in-app UI
---

Our Swift SDK library lets you create notification experiences using Knock's APIs. It comes with pre-built UI components that you can use to easily get up and running with a fully functional notification feed experience in your product.

## Getting started

Please reference our iOS SDK [documentation](/sdks/ios/quick-start) to set up the library.

## Pre-built components

The Knock iOS SDK ships the following pre-built UI elements:

### In-app notifications

- [`InAppFeedView`](/in-app-ui/ios/components#knockinappfeedview): A full-page list of notifications.
- [`InAppFeedViewController`](/in-app-ui/ios/components#knockinappfeedview): A wrapper for InAppFeedView to be used with UIKit.
- [`InAppFeedViewModel`](/in-app-ui/ios/components#knockinappfeedviewmodel): All of the logic needed to support your in-app feed. Can be used independently from `InAppFeedView` if you want to build your own UI.
- [`InAppFeedNotificationIconButton`](/in-app-ui/ios/components#inappfeednotificationiconbutton): For adding a bell icon to your application that shows the current count of unread or unseen notifications.

## Links

- [iOS SDK on GitHub](https://github.com/knocklabs/knock-swift)
- [SDK reference](/sdks/ios/reference)


## Components
How to use Knock's UI components in your iOS application.
---
title: "Swift SDK pre-built components"
description: "How to use Knock's UI components in your iOS application."
section: Building in-app UI
---

## KnockInAppFeedView

### Overview

<Image
  src="/images/ios-in-app-feed.png"
  alt="Component UI Example"
  width={1300}
  height={798}
  className="rounded-md mx-auto border border-gray-200"
/>

`KnockInAppFeedView` is a SwiftUI view that renders the in-app notifications feed using data from `KnockInAppFeedViewModel`. It provides a customizable and interactive user interface for displaying notifications.

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">Initializing the Feed.</span> Please remember
      that you will still need to initialize the <code>feedManager</code>{" "}
      manually before displaying this component. Check out our{" "}
      <a href="/sdks/ios/reference#feedmanager">
        FeedManager documentation for more information.
      </a>{" "}
      See below for an example of how to initialize the <code>feedManager</code>{" "}
      .
    </>
  }
/>

### Properties

<Attributes>
  <Attribute
    name="theme"
    type="InAppFeedTheme"
    description="Defines the appearance of the feed view and its components."
  />
</Attributes>

### Customization

You can customize almost every aspect of the UI of the `KnockInAppFeedView` using our customizable themes.

### Using UIKit

If you are using UIKit, use `InAppFeedViewController`.

See below for an example of how to use this component.

### Examples

#### SwiftUI

```swift
@EnvironmentObject var viewModel: Knock.InAppFeedViewModel = .init()

init() {
   Task {
        if Knock.shared.feedManager == nil {
            Knock.shared.feedManager = try? await Knock.FeedManager(feedId: "ad06b085-54e2-4fb0-b6e7-050338851868")
            await viewModel.connectFeedAndObserveNewMessages()
        }
    }
}

KnockInAppFeedView(theme: KnockInAppFeedTheme(titleString: "Notifications"))
    .environmentObject(viewModel)
    .onReceive(viewModel.didTapFeedItemButtonPublisher) { actionString in
        print("Button with action \(actionString) was tapped.")
    }
    .onReceive(viewModel.didTapFeedItemRowPublisher) { item in
        print("Row item was tapped")
    }
```

#### UIKit

```swift
class MyViewController: InAppFeedViewController {
    init() {
        self.viewModel = Knock.InAppFeedViewModel()
        self.theme: Knock.InAppFeedTheme = .init()
    }

    override func viewDidLoad() {
        Task {
            if Knock.shared.feedManager == nil {
                Knock.shared.feedManager = try? await Knock.FeedManager(feedId: "ad06b085-54e2-4fb0-b6e7-050338851868")
                await viewModel.connectFeedAndObserveNewMessages()
            }
        }
        super.viewDidLoad()
    }
}
```

## InAppFeedNotificationIconButton

### Overview

`InAppFeedNotificationIconButton` is a SwiftUI view that renders a bell icon button to your application that shows the current count of unread or unseen notifications. This can be used to open your NotificationFeed.

### Properties

<Attributes>
  <Attribute
    name="theme"
    type="InAppFeedNotificationIconButtonTheme"
    description="Defines the appearance of the feed view and its components."
  />
  <Attribute
    name="action"
    type="() -> Void"
    description="A callback to alert you when user taps on the button."
  />
</Attributes>

### Examples

```swift
    TestParentView()
        .sheet(isPresented: $showingSheet) {
            Knock.InAppFeedView()
                .environmentObject(feedViewModel)
        }
        .toolbar {
            Knock.InAppFeedNotificationIconButton() {
                showingSheet.toggle()
            }
            .environmentObject(feedViewModel)
        }
```


## Customization
How to customize Knock's iOS UI components.
---
title: "Customizing Knock UI components in iOS"
description: "How to customize Knock's iOS UI components."
section: Building in-app UI
---

## InAppFeedTheme

### Overview

`InAppFeedTheme` allows for UI customization of the `KnockInAppFeedView`.

### Properties

<Attributes>
  <Attribute
    name="rowTheme"
    type="FeedNotificationRowTheme"
    description="Defines the UI customization of the row items."
  />
  <Attribute
    name="titleString"
    type="String?"
    description="Sets the title of the view. If set to nil, then the title view will be hidden entirely. This is useful if you want to have a completely custom title view."
  />
  <Attribute
    name="titleFont"
    type="Font?"
    description="Sets the font of the title view."
  />
  <Attribute
    name="titleColor"
    type="Color?"
    description="Sets the color of the title view."
  />
  <Attribute
    name="upperBackgroundColor"
    type="Color?"
    description="Sets the background color of the top portion of the view (title view, filter view, and top action buttons view)."
  />
  <Attribute
    name="lowerBackgroundColor"
    type="Color?"
    description="Sets the background color of the bottom portion of the view (the list)."
  />
</Attributes>

## FeedNotificationRowTheme

### Overview

`FeedNotificationRowTheme` allows for UI customization of the row items in the `KnockInAppFeedView`.

### Properties

<Attributes>
  <Attribute
    name="showAvatarView"
    type="Bool"
    description="Show or hide the avatar/initials view in the upper left corner of the row."
  />
  <Attribute
    name="avatarViewTheme"
    type="AvatarViewTheme"
    description="Customize styling of avatarview."
  />
  <Attribute
    name="notificationContentCSS"
    type="String?"
    description="Customize the css of the markdown html of the notification body."
  />
  <Attribute
    name="backgroundColor"
    type="Color"
    description="Background color of the FeedNotificationRow."
  />
  <Attribute
    name="markAsReadSwipeConfig"
    type="SwipeButtonConfig?"
    description="This is the config to set the mark as read/unread swipe actions. Set to null to remove the action entirely."
  />
  <Attribute
    name="archiveSwipeConfig"
    type="SwipeButtonConfig?"
    description="This is the config to set the archive/unarchive swipe actions. Set to null to remove the action entirely."
  />
  <Attribute
    name="unreadNotificationCircleColor"
    type="Color"
    description="Color of the unread circle indicator in the top left of the row."
  />
  <Attribute
    name="sentAtDateFormatter"
    type="DateFormatter"
    description="DateFormatter for the sent timestamp at the bottom of the row."
  />
  <Attribute
    name="sentAtDateFont"
    type="Font"
    description="Font for sent timestamp."
  />
  <Attribute
    name="sentAtDateTextColor"
    type="Color"
    description="Color for sent timestamp."
  />
  <Attribute
    name="primaryActionButtonConfig"
    type="ActionButtonConfig"
    description="Styling for primary action buttons."
  />
  <Attribute
    name="secondaryActionButtonConfig"
    type="ActionButtonConfig"
    description="Styling for secondary action buttons."
  />
  <Attribute
    name="tertiaryActionButtonConfig"
    type="ActionButtonConfig"
    description="Styling for tertiary action buttons."
  />
</Attributes>

## AvatarViewTheme

### Overview

`AvatarViewTheme` allows for UI customization of the user avatar view in the row item.

### Properties

<Attributes>
  <Attribute
    name="avatarViewBackgroundColor"
    type="Color"
    description="Background color of the view. This is more apparent when the view is showing initials instead of an image."
  />
  <Attribute
    name="avatarViewInitialsFont"
    type="Font"
    description="Font for the initials view."
  />
  <Attribute
    name="avatarViewInitialsColor"
    type="Color"
    description="Text color for the initials view."
  />
  <Attribute
    name="avatarViewSize"
    type="CGFloat"
    description="Overall size of the avatar view."
  />
</Attributes>


## Android (Kotlin)

## Overview
Learn more about the in-app notifications experiences you can build for Android applications with Knock.
---
title: "Building in-app UI for Android"
description: Learn more about the in-app notifications experiences you can build for Android applications with Knock.
section: Building in-app UI
---

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note</span> in the current version of the
      Android SDK there are no pre-built UI elements.
    </>
  }
/>

The Knock Android SDK is a low-level set of methods for interacting with the Knock APIs from Android applications. The SDK is designed to help you easily integrate Knock into your application and build in-app notification experiences powered by Knock.

## Features

- API methods for interacting with the [Knock in-app API](/in-app-ui/api-overview).
- Managed websocket connections to the Knock real-time service.

## Getting started

### 1. Add Jitpack repository support in your `settings.gradle` file

```gradle
pluginManagement {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

dependencyResolutionManagement {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
```

### 2. Add the implementation to your app `build.gradle` file

```gradle 

dependencies {
    implementation 'com.github.knocklabs:knock-android:<VERSION>'
}
```

[Read more in the quick start guide ->](/sdks/android/quick-start)

## Links

- [Android SDK on GitHub](https://github.com/knocklabs/knock-android)
- [Android SDK reference](/sdks/android/reference)


## Components
How to use Knock's UI components in your Android application.
---
title: "Kotlin SDK pre-built components"
description: "How to use Knock's UI components in your Android application."
section: Building in-app UI
---

## InAppFeedView

### Overview

<Image
  src="/images/ios-in-app-feed.png"
  alt="Component UI Example"
  width={1300}
  height={798}
  className="rounded-md mx-auto border border-gray-200"
/>

`InAppFeedView` is a Kotlin Compose view that renders the in-app notifications feed using data from `InAppFeedViewModel`. It provides a customizable and interactive user interface for displaying notifications.

### Properties

<Attributes>
  <Attribute
    name="viewModel"
    type="InAppFeedViewModel"
    description="The ViewModel containing the logic for the InAppFeedView."
  />
  <Attribute
    name="theme"
    type="InAppFeedTheme"
    description="Defines the appearance of the feed view and its components."
  />
</Attributes>

### Customization

You can customize almost every aspect of the UI of the `InAppFeedView` using our customizable themes.

### Examples

```swift
val feedViewModel: InAppFeedViewModel = viewModel(factory = InAppFeedViewModelFactory(LocalContext.current))
val theme = InAppFeedViewTheme(context = LocalContext.current)

InAppFeedView(feedViewModel, theme = theme)

LaunchedEffect(key1 = Unit) {
    if (Knock.shared.feedManager == null) {
        Knock.shared.feedManager = FeedManager(feedId = Utils.inAppChannelId)
        feedViewModel.connectFeedAndObserveNewMessages()
    }

    feedViewModel.didTapFeedItemRowPublisher
        .onEach { feedItem ->
            // Handle the feed item row tap event
        }
        .launchIn(this)

    feedViewModel.didTapFeedItemButtonPublisher
        .onEach { feedItemButtonEvent ->
            // Handle the feed item button block tap event
        }
        .launchIn(this)
}
```


## Customization
How to customize Knock's Android UI components.
---
title: "Customizing Knock UI components in Android"
description: "How to customize Knock's Android UI components."
section: Building in-app UI
---

## InAppFeedTheme

### Overview

`InAppFeedTheme` allows for UI customization of the `InAppFeedView`.

### Properties

<Attributes>
  <Attribute
    name="rowTheme"
    type="FeedNotificationRowTheme"
    description="Defines the UI customization of the row items."
  />
  <Attribute
    name="filterTabTheme"
    type="FilterTabTheme"
    description="Defines the UI customization of the top filter tabs."
  />
  <Attribute
    name="titleString"
    type="String?"
    description="Sets the title of the view. If set to nil, then the title view will be hidden entirely. This is useful if you want to have a completely custom title view."
  />
  <Attribute
    name="textStyle"
    type="TextStyle?"
    description="Sets the textStyle for the title of the view."
  />
  <Attribute
    name="upperBackgroundColor"
    type="Color?"
    description="Sets the background color of the top portion of the view (title view, filter view, and top action buttons view)."
  />
  <Attribute
    name="lowerBackgroundColor"
    type="Color?"
    description="Sets the background color of the bottom portion of the view (the list)."
  />
</Attributes>

## FeedNotificationRowTheme

### Overview

`FeedNotificationRowTheme` allows for UI customization of the row items in the `KnockInAppFeedView`.

### Properties

<Attributes>
  <Attribute
    name="backgroundColor"
    type="Color"
    description="Background color of the FeedNotificationRow."
  />
  <Attribute
    name="bodyTextStyle"
    type="TextStyle?"
    description="Set the textStyle of the body of the message."
  />
  <Attribute
    name="unreadNotificationCircleColor"
    type="Color"
    description="Color of the unread circle indicator in the top left of the row."
  />
  <Attribute
    name="showAvatarView"
    type="Bool"
    description="Show or hide the avatar/initials view in the upper left corner of the row."
  />
  <Attribute
    name="avatarViewTheme"
    type="AvatarViewTheme"
    description="Customize styling of avatarview."
  />
  <Attribute
    name="primaryActionButtonConfig"
    type="ActionButtonConfig"
    description="Styling for primary action buttons."
  />
  <Attribute
    name="secondaryActionButtonConfig"
    type="ActionButtonConfig"
    description="Styling for secondary action buttons."
  />
  <Attribute
    name="sentAtDateFormatter"
    type="DateTimeFormatter"
    description="DateTimeFormatter for the sent timestamp at the bottom of the row."
  />
  <Attribute
    name="sentAtDateTextStyle"
    type="TextStyle"
    description="TextStyle for sent timestamp."
  />
  <Attribute
    name="markAsReadSwipeConfig"
    type="SwipeConfig?"
    description="This is the config to set the mark as read/unread swipe actions. Set to null to remove the action entirely."
  />
  <Attribute
    name="archiveSwipeConfig"
    type="SwipeConfig?"
    description="This is the config to set the archive/unarchive swipe actions. Set to null to remove the action entirely."
  />
</Attributes>

## AvatarViewTheme

### Overview

`AvatarViewTheme` allows for UI customization of the user avatar view in the row item.

### Properties

<Attributes>
  <Attribute
    name="avatarViewBackgroundColor"
    type="Color?"
    description="Background color of the view. This is more apparent when the view is showing initials instead of an image."
  />
  <Attribute
    name="avatarViewInitialsTextStyle"
    type="TextStyle?"
    description="TextStyle for the initials view."
  />
  <Attribute
    name="avatarViewSize"
    type="CGFloat"
    description="Overall size of the avatar view."
  />
</Attributes>

## FilterTabTheme

### Overview

`FilterTabTheme` allows for UI customization of the filter tab bar at the top of the view.

### Properties

<Attributes>
  <Attribute
    name="selectedColor"
    type="Color?"
    description="The color the tab will be in the selected state"
  />
  <Attribute
    name="unselectedColor"
    type="Color?"
    description="The color the tab will be in the unselected state."
  />
  <Attribute
    name="textStyle"
    type="TextStyle"
    description="The TextStyle of the filter tab text."
  />
</Attributes>

## EmptyFeedViewTheme

### Overview

`EmptyFeedViewTheme` allows for UI customization of the EmptyFeedView for each filter.

### Properties

<Attributes>
  <Attribute
    name="backgroundColor"
    type="Color?"
    description="The background color of the view."
  />
  <Attribute
    name="title"
    type="String?"
    description="The title of the EmptyFeedView."
  />
  <Attribute
    name="titleTextStyle"
    type="TextStyle"
    description="The TextStyle of the title."
  />
  <Attribute
    name="subtitle"
    type="TextStyle"
    description="The subtitle of the EmptyFeedView."
  />
  <Attribute
    name="subtitleTextStyle"
    type="TextStyle"
    description="The TextStyle of the subtitle."
  />
  <Attribute
    name="icon"
    type="ImageVector?"
    description="The TextStyle of the filter tab text."
  />
  <Attribute
    name="iconResId"
    type="Int?"
    description="The TextStyle of the filter tab text."
  />
  <Attribute
    name="iconSize"
    type="Int?"
    description="The TextStyle of the filter tab text."
  />
  <Attribute
    name="iconColor"
    type="Color?"
    description="The TextStyle of the filter tab text."
  />
</Attributes>

## FilterTabTheme

### Overview

`FilterTabTheme` allows for UI customization of the filter tab bar at the top of the view.

### Properties

<Attributes>
  <Attribute
    name="selectedColor"
    type="Color?"
    description="The color the tab will be in the selected state"
  />
  <Attribute
    name="unselectedColor"
    type="Color?"
    description="The color the tab will be in the unselected state."
  />
  <Attribute
    name="textStyle"
    type="TextStyle"
    description="The TextStyle of the filter tab text."
  />
</Attributes>

## SwipeConfig

### Overview

`SwipeConfig` allows for UI customization of the left and right swipe actions of the FeedNotificationRow.

### Properties

<Attributes>
  <Attribute
    name="action"
    type="FeedNotificationRowSwipeAction?"
    description="The action you want taken on the swipe"
  />
  <Attribute
    name="title"
    type="String?"
    description="The title of the swipe action (e.g. `Read`)."
  />
  <Attribute
    name="inverseTitle"
    type="String?"
    description="The inverse title of the swipe action (e.g. `Unread`)."
  />
  <Attribute
    name="titleStyle"
    type="TextStyle?"
    description="The textStyle of the title."
  />
  <Attribute name="imageId" type="Int?" description="The image resource." />
  <Attribute
    name="inverseImageId"
    type="Int?"
    description="The inverse image resource."
  />
  <Attribute
    name="imageSize"
    type="Int?"
    description="The size of the image."
  />
  <Attribute
    name="imageColor"
    type="Color?"
    description="The color of the image."
  />
  <Attribute
    name="swipeColor"
    type="Color?"
    description="The background color of the swipe action."
  />
</Attributes>


## Flutter

## Overview
Learn more about the in-app notifications experiences you can build for Flutter applications with Knock.
---
title: "Building in-app UI for Flutter"
description: Learn more about the in-app notifications experiences you can build for Flutter applications with Knock.
section: Building in-app UI
---

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note</span> in the current version of the
      Flutter SDK there are no pre-built UI elements.
    </>
  }
/>

The Knock Flutter SDK is a low-level set of methods for interacting with the Knock APIs from Flutter applications. The SDK is designed to help you easily integrate Knock into your application and build in-app notification experiences powered by Knock.

## Features

- API methods for interacting with the [Knock in-app API](/in-app-ui/api-overview).
- Managed websocket connections to the Knock real-time service.
- State management for powering in-app feeds, with optimistic client-side updates.

## Getting started

```bash
flutter pub add knock_flutter
```

[Read more in the quick start guide ->](/sdks/flutter/quick-start)

## Links

- [`knock_flutter` on pub.dev](https://pub.dev/packages/knock_flutter)
- [Example application using the Flutter SDK](https://github.com/knocklabs/knock-flutter/tree/main/example)
- [Full SDK reference](/sdks/flutter/reference)
- [GitHub repository](https://github.com/knocklabs/knock-flutter)



# Developer tools
Use our powerful developer tools in order to integrate Knock seamlessly into your development workflow.

## API keys
Learn more about API keys in Knock and what they're used for.
---
title: API keys
description: Learn more about API keys in Knock and what they're used for.
section: Developer tools
---

In Knock, all requests to the [Knock API](/reference) are issued using a API key. Your API keys are [environment](/concepts/environments) specific and allow Knock to tie a request on the API back to an isolated Knock environment.

## Finding your API keys

You can find your **environment-specific API keys** under **Developers** > **API keys** in the left-hand side bar. Remember: each environment has its own unique set of API keys.

## Secret vs public API keys

Each Knock environment will be generated with two API keys: a secret key and a public key. You can uniquely identify these keys as they start with `sk_` for a secret key, vs `pk_` for a public key.

- Public keys are only meant to identify your account with Knock. They aren't secret, and can safely be made public in any of your client-side code.

- Secret keys can perform any API request to Knock, they should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I revoke an API key once generated?">
    Yes. If you need to revoke and rotate your API keys in a given environment,
    navigate to **Developers** > **API keys** in your dashboard, select the
    "..." menu next to the key you want to rotate, and click "Roll API key."
    This will prompt you to confirm the operation, which will immediately issue
    a new key and invalidate the previous key. This action cannot be undone.
  </Accordion>
  <Accordion title="Can I further scope API key access?">
    Currently, it's not possible to reduce the scope of an API key and limit it
    to a particular set of resources. Please contact our [support team if you
    need this feature](mailto:support@knock.app).
  </Accordion>
</AccordionGroup>


## Service tokens
Learn more about service tokens on your Knock account and how they are used to authenticate against the Knock management API.
---
title: Service tokens
description: Learn more about service tokens on your Knock account and how they are used to authenticate against the Knock management API.
section: Developer tools
---

A Knock account service token allows for secure access against the Knock [Management API](/developer-tools/management-api) and [CLI](/developer-tools/knock-cli). It acts as an authentication mechanism for resources under your Knock account.

Service tokens always start with `knock_st_` and are different from your Knock API keys as they authenticate requests to the Knock management API **only**.

<Callout
  emoji="🚨"
  text={
    <>
      Note: <strong>only account owners or admins</strong> have the privilege to
      generate (or revoke) service tokens. Service tokens will inherit the
      privilege of the owner or the admin that creates the service token, and
      therefore have full access to the management API.
    </>
  }
/>

## Generating a new service token

To use the management API or CLI, you will first need to generate a service token and use it as a means of authentication when sending requests.

To generate a service token, from the dashboard go to "Settings," select the "Service tokens" tab, and click the "+ New token" button. Then, provide a name for the token and click "generate" to view and save your newly generated service token.

<Callout
  emoji="🚨"
  text={
    <>
      Note: once generated,{" "}
      <strong>
        you cannot see a service token again from the Knock dashboard,
      </strong>{" "}
      so be sure to copy it to a secure location.
    </>
  }
/>

## Revoking a service token

Service tokens can be revoked under the three-dot menu and by clicking on "Delete token." Deleting a token will **immediately** revoke its ability to be used against the Knock management API and CLI.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use a Knock service token against the Knock API?">
    No, a service token can only be used against the Knock Management API and
    not the Knock API.
  </Accordion>
  <Accordion title="How can I know which changes were made by a specific service token?">
    Changes made via the Management API will appear as audit logs, similar to
    changes made manually in the dashboard, but attributing the service token
    used to make the change as the author. In addition, internally we audit
    requests and tie them back to a corresponding service token. If you need
    further help understanding which request originated from a service token,
    please [contact our support team](mailto:support@knock.app).
  </Accordion>
</AccordionGroup>


## Knock CLI
Learn how to use the Knock CLI to build, test, and manage your Knock notification system from the terminal.
---
title: Knock CLI
description: Learn how to use the Knock CLI to build, test, and manage your Knock notification system from the terminal.
section: Developer tools
---

The Knock CLI helps you build, test, and manage your Knock notification system, right from the terminal. You can use the CLI to:

- Pull Knock workflows down to your local machine and work with your notification logic and templates in your code editor.
- [Integrate Knock into your CI/CD pipeline](/developer-tools/integrating-into-cicd) and automatically promote changes between Knock environments on release.
- Map your translation files into Knock to localize your notifications.

## Installing the CLI

You can install the Knock CLI using `npm`, a node package manager, with the following command:

```bash title="Installing the Knock CLI"
npm install -g @knocklabs/cli
```

Once the CLI is installed, you can call it by using the `knock` command in your terminal. The CLI is also available via homebrew for macOS, see the installation guide [here](/cli#installation).

## Authenticating the CLI

The Knock CLI relies on [service tokens](/developer-tools/service-tokens) in order to authenticate against your Knock account.

Once you have generated a service token, you can verify it works by running `knock whoami --service-token=YOUR_SERVICE_TOKEN`. If your token is valid and configured properly, you'll receive a 200 response that shows the account name and the service token name.

## CLI reference

You can find a complete reference for all of the commands and flags available on the [CLI in our comprehensive reference](/cli).


## Management API
Learn more about the Knock management API for programmatically interacting with your Knock dashboard resources.
---
title: Management API
description: Learn more about the Knock management API for programmatically interacting with your Knock dashboard resources.
section: Developer tools
---

The Knock management API provides you with a programmatic way to interact with the resources you create and manage in your Knock dashboard, including workflows, templates, and translations. It's separate from the [Knock API](/reference) and only provides access to a limited subset of resources.

You can use the Knock management API to:

- Create, update, and manage your Knock workflows and the notification templates within those workflows.
- Create, update and manage your [email layouts](/integrations/email/layouts).
- Create and manage the [translations](/concepts/translations) used by your notification templates.
- Create, update, and manage your [partials](/designing-workflows/partials).
- Commit and promote changes between your Knock environments.

[View management API reference](/mapi)

## Interacting with the management API

Currently, we do not ship SDKs that wrap the management API but we do ship a [CLI](/developer-tools/knock-cli) for easily interacting with the resources in your Knock account.

## Use cases

### Previewing templates

Using the management API, you can generate previews of the templates within your workflows. One example use case is providing a way for your users to customize the content of notifications sent through Knock.

To preview a template, you [use the preview template endpoint exposed by the management API](/mapi#workflows-preview-template). This API endpoint accepts a workflow key, and a [step reference](/mapi#workflowstep-definition) (`ref`) for the step that contains the template you want to preview.

Using the endpoint, you pass through details about the `recipient`, `actor`, `tenant`, and any other data variables that are used within the template. The endpoint will return a JSON object with fully rendered template generated using the data you provided. It will be the same as previewing the template in the Knock dashboard.

```bash title="An example request to preview a template"
curl -X POST https://control.knock.com/v1/workflows/my-workflow/steps/my-step/preview_template \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "chris", "data": {"project_name": "My Project"}}'
```

<br />

```json title="An example response from the preview template endpoint"
{
  "result": "success",
  "content_type": "email",
  "template": {
    "html_content": "<html><body><p>Hello world!</p></body></html>",
    "text_content": "Hello world!",
    "subject": "Hello, world!"
  }
}
```


## API logs
Learn more about viewing and debugging API request logs in Knock.
---
title: API Logs
description: Learn more about viewing and debugging API request logs in Knock.
section: Developer tools
---

Knock automatically captures and stores all of the API requests you make to the Knock API, and makes these requests accessible under the **Developers** > **Logs** section of the Knock dashboard.

<Callout
  emoji="👀"
  text={
    <>
      <strong>Note:</strong> Knock does not store response bodies for the{" "}
      <code>/feeds</code> endpoint in our logs.
    </>
  }
/>

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Data subject to retention policy enforcement.
      </span>{" "}
      See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

## Filtering API logs

You can filter API logs in your Knock account using the following filters:

- **Request ID**: filter for a particular log returned by the `X-Request-ID` header.
- **Status**: filter for failed and succeeded requests.
- **Endpoint type**: filter for requests to particular sets of endpoints.

## Log truncation

Knock truncates logs with long binaries, lists, maps, and strings to prevent the logs from becoming too large. The truncation occurs at the top level of the JSON object and is noted by the presence of either the `__knock_truncated__` key in the JSON object (indicating that some of the keys were dropped) or as a `[TRUNCATED]` value under a given key.

```json title="Example of a truncated log"
// Original JSON object with many keys
{
  "foo": "bar",
  "biz": "this is a very long string value",
  "baz": null,
  ...
}

// Truncated JSON object
{
  // indicates that some of the key-value pairs were dropped
  "__knock_truncated__": true,
  "foo": "bar",
  "biz": "[TRUNCATED]"
}
```

## Frequently asked questions

<AccordionGroup>
  <Accordion
    title="How many days' worth of API logs can I view?"
    defaultOpen={true}
  >
    Knock will only keep 30 days of API logs available to be queried and
    displayed at any time.
  </Accordion>
</AccordionGroup>

---


## Knock and Postman

## Security
Learn about our security policies.
---
title: Security at Knock
description: Learn about our security policies.
section: Getting started
tags: ["compliance", "gdpr", "soc2", "soc 2", "hipaa", "hippa", "baa", "ccpa"]
---

Knock was built with security and privacy in mind from day one.

Below you can learn more about our security credentials, our internal security practices, and how to disclose security issues to our team. If you're looking to learn more about how we think about data privacy at Knock, you can read our [privacy policy](https://knock.app/legal/privacy-policy).

## Our security posture

Knock is SOC 2 Type 2 compliant, GDPR certified, CCPA, and HIPAA compliant. We perform regular penetration tests. If you'd like copies of our SOC 2 report or penetration test report, please let us know at [security@knock.app](mailto:security@knock.app). You can learn more about our GDPR certification in our [privacy policy](https://knock.app/legal/privacy-policy).

<div className="flex flex-row items-center justify-center space-x-4">
  <div>
    <Image
      src={"/images/21972-312_SOC_NonCPA.png"}
      alt="SOC2 Service Organization Logo"
      width={120}
      height={120}
    />
  </div>
  <div>
    <Image
      src={"/images/gdpr-badge-2.png"}
      alt="GDPR badge"
      width={120}
      height={120}
      className="self-center ml-2"
    />
  </div>
  <div>
    <Image
      src={"/images/hipaa-badge.png"}
      alt="HIPAA badge"
      width={120}
      height={120}
      className="self-center"
    />
  </div>
</div>

Here's a little more about our security practices at Knock:

- We implement best practices around least privilege, with limited access to production data for our employees.
- Access to all systems is enforced by 2FA for our employees.
- All of our code changes are signed off by at least one other person, and tested in a staging environment before being deployed.
- We retain server logs for a maximum of 1 year, after which time they are permanently deleted.
- We have regular third party penetration tests and infrastructure audits.
- All data is encrypted at rest, and we use TLS 1.2 for all cross-service communication.

## More information and responsible disclosure

We're always improving the security of our product. If you'd like to learn more about our data protection processes, you can email us at [security@knock.app](mailto:security@knock.app).

If you are a security researcher and would like to disclose an issue, contact [security@knock.app](mailto:security@knock.app). We are strong advocates for responsible disclosure by independent security researchers. We believe the best way to protect current and future customers is to encourage researchers to come forward with issues and reply promptly.

Our promise to you is:

- We will read and respond to all reported vulnerabilities.
- We will not take any harmful action (including legal action) against researchers who act ethically and in good faith.
- We will highlight the contributions of security researchers who make significant reports.

In return we ask:

- That you do not attempt to access, modify, or delete data belonging to Knock customers.
- That you report issues promptly once discovered.
- That you do not attempt denial of service against the Knock service.

<br />


## Integrating into CI/CD
Learn how to add Knock to your deployment pipeline with our command line interface.
---
title: Adding Knock to your CI/CD pipeline
description: Learn how to add Knock to your deployment pipeline with our command line interface.
tags:
  [
    "CI/CD",
    "cicd",
    "integration",
    "deployment",
    "automation",
    "testing",
    "commit",
    "staging",
  ]
section: Developer Tools
---

With the [Knock CLI](/developer-tools/knock-cli), you can add Knock directly into your existing CI/CD pipeline in order to automate the promotion of changes to Workflows, Layouts, and Translations between [environments](/concepts/environments) during testing and deployment.

This guide assumes that you have [created](/concepts/environments#create-additional-environments) a “Staging” environment in Knock in addition to the Development and Production environments that are provided by default. It also assumes that you have [installed the Knock CLI](/cli#installation) on your local machine.

## Local development

With the Knock CLI, you can pull resources from the Knock dashboard and develop them locally using the [`knock workflow pull --all`](/cli#workflow-pull), [`knock layout pull --all`](/cli#email-layout-pull), and [`knock translation pull --all`](/cli#translation-pull) commands. You can also work with specific resources by providing a `key` rather than using the `--all` flag.

Once you’re ready to send your updates back to Knock’s Development environment, you can push ([`knock workflow push --all`](/cli#workflow-push)) and commit ([`knock commit`](/cli#commit-all)) changes directly from the command line in the same way that you would save and commit them in your dashboard. You can also perform both of these actions at once by using the `--commit` flag on any `push` command.

<Callout
  emoji="🛑"
  text={
    <>
      <span className="font-bold">Note:</span> As with working directly in your
      dashboard, any uncommitted changes that are made to a Knock resource and
      pushed to Knock can be overwritten by another user who is working on the
      same resource. It’s important to <code>commit</code> any changes that you
      want to persist while working in the Development environment.
    </>
  }
/>

## Pushing to your remote repository and deploying to staging

When you’re ready to commit your locally-developed feature (including any updates to your Knock resources) to a remote git repository and kick off a test build in your staging environment, you can use the Knock CLI to automate the promotion of changes to your Knock resources across Knock environments. An example implementation might be done with a GitHub Action that promotes all of your committed updates from the Knock Development environment to your Staging environment, so that your application’s staging deployment will have access to all of your notifications changes.

<Callout
  emoji="👀"
  text={
    <>
      When using the <code>knock commit promote</code>{" "}
      <a href="/cli#commit-promote">command</a> with the <code>--to</code> flag,
      the CLI will automatically locate any promotion-eligible changes that
      exist in the environment one "level" lower in your list of Knock
      environments in order to promote them to the designated environment. To
      view the current order of all your configured environments, navigate to{" "}
      <span className="font-bold">Settings &gt; Environments</span> in your
      Knock dashboard.
    </>
  }
/>

This sample GitHub Action `.yaml` file shows how you might promote all committed changes from your Development environment to your Staging environment:

```yaml
name: Knock Workflow Promotion to Staging

on:
  push:
    branches-ignore:
      - main

jobs:
  promote_workflow:
    runs-on: ubuntu-latest

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

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "20.9.0" # Set Node.js version to ^16.14.0

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

      - name: Promote Workflow to Staging
        env:
          KNOCK_SERVICE_TOKEN: ${{ secrets.KNOCK_SERVICE_TOKEN }} # Ensure you've set KNOCK_SERVICE_TOKEN in your GitHub secrets
        run: knock commit promote --to=staging --service-token=$KNOCK_SERVICE_TOKEN
```

<br />

## Deploying to production

Once a pull request has been approved and is ready to be merged into your `main` branch, you can once again include the Knock CLI in your CI/CD pipeline to promote your relevant Knock resources to your Production environment.

This sample GitHub Action `.yaml` file shows how you might promote all changes from your Staging environment to your Production environment:

```yaml
name: Knock Workflow Promotion to Production

on:
  push:
    branches:
      - main

jobs:
  promote_workflow:
    runs-on: ubuntu-latest

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

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "20.9.0" # Set Node.js version to ^16.14.0

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

      - name: Promote Workflow to Production
        env:
          KNOCK_SERVICE_TOKEN: ${{ secrets.KNOCK_SERVICE_TOKEN }} # Ensure you've set KNOCK_SERVICE_TOKEN in your GitHub secrets
        run: knock commit promote --to=production --service-token=$KNOCK_SERVICE_TOKEN
```


## Outbound webhooks

## Overview
Learn how to use outbound webhooks to get the data you need from Knock into your product.
---
title: Outbound Webhooks
description: Learn how to use outbound webhooks to get the data you need from Knock into your product.
section: Developer tools
tags: ["events", "data", "analytics", "webhook configuration"]
---

Use outbound webhooks to be notified of events happening within your Knock environment, and respond to those events in realtime in your product.

## An overview of webhooks

Knock can send a JSON payload to your backend with data about events that occur within Knock, like a message's status changing from `sent` to `delivered`. You can configure an endpoint and select which events you'd like it to listen to. When that event happens you'll get a POST request to the endpoint you've provided and then can use that data to trigger side-effects in your app.

You can learn more about the types of events that [Knock sends webhooks for here](/developer-tools/outbound-webhooks/event-types).

## Quickstart

1. [Create an endpoint in your app to receive webhook requests](#1-create-an-endpoint-to-receive-the-webhook-payload) and respond to requests with a `200` or `204` status code
2. [Create a webhook in the Knock dashboard](#2-create-the-knock-webhook) pointing to your endpoint
3. Start receiving webhook events!

## Payload & headers

A webhook payload will always take the following base shape, where the `type` and its associated `data` schema will be determined by the supported [webhook event types](/developer-tools/outbound-webhooks/event-types). The `data` field will include the entity that the event references.

```json title="A sample event payload"
{
  "__typename": "Event",
  // The type of event that triggered the webhook
  "type": "message.sent",
  "created_at": "2022-05-31T17:12:59.958652Z",
  "data": {
    // Information about the entity, as determined by the webhook event type.
  },
  // (Optional) additional metadata related to the event
  "event_data": {
    "__typename": "EventData",
    "foo": "bar"
  }
}
```

The request header will also contain the following:

- `x-knock-event`: the field and the value found in the `"type"` key of the payload
- `x-knock-environment-id`: the environment the webhook belongs to
- `x-knock-signature`: the encoded result of a timestamp, payload, and shared secret key so you can verify that the contents of the webhook are from Knock and not a result of a [Man in the middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). Learn more about [verifying signatures below](/developer-tools/outbound-webhooks/overview#verifying-the-signature).

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Webhooks are single-environment.</span> When
      you create a webhook, it will be for the environment you're currently in.
      If you'd like to add that webhook to another environment, you'll have to
      create it again there. What this means is that when you create a webhook
      in a development environment, it will only be triggered by notifications
      from workflows in development.
    </>
  }
/>

## How to create a webhook

### 1. Create an endpoint to receive the webhook payload

In your app, create an endpoint specifically to receive incoming requests from a webhook you'll set up in Knock. This must be an HTTP or HTTPS endpoint on your server with a URL. This is where Knock will send a request with data about events you'll select in the next step. Keep in mind that you can use one webhook endpoint per event type, or you can send multiple types of events to the same endpoint.

#### Retries

Knock webhooks have built-in retries for `3xx`, `4xx`, and `5xx` responses from your endpoint. Make sure to send a `2xx` (i.e. `200`) response from your endpoint once you've received the webhook request before operating on the data to avoid a timeout, which will result in the webhook being retried. **It will attempt to send the webhook 8 times before it discards the message.** You can track the webhooks sent in the webhook delivery logs, as detailed in the [managing webhooks](#reading-webhook-delivery-logs) section below.

### 2. Create the Knock webhook

You can create a new webhook by navigating to `Webhooks` in the Knock dashboard. You can find this in the sidebar under `Developers`.

When you click "Create webhook" you'll be prompted to add the endpoint from the previous step, an optional description, and then select the events you want to be notified of from the list.

Once you create the webhook, it will be activated and you will begin receiving requests to your endpoint. To stop receiving requests, you can [delete the webhook](#deleting-a-webhook).

## Receiving a webhook payload

### IP addresses for firewall whitelisting

If your infrastructure uses a firewall that restricts incoming traffic by IP address, you can whitelist the following Knock IP addresses to ensure webhook deliveries:

- `3.138.92.104`
- `18.116.161.231`
- `3.19.195.170`

### Verifying the signature

We recommend that upon receiving the webhook request you verify the signature before using the contents of the payload. We follow the Stripe specification to add a layer of security to our webhook requests.

The signature is generated with a HMAC using the SHA256 algorithm and, prior to being encoded, is comprised of the timestamp and the stringified JSON payload of the request. We encode `"timestamp in numerical form"."stringified payload"` as the signature of the request.

The `x-knock-signature` header is a string comprised of the timestamp used in the encoding and the encoded value above. It will look like this: `t=timestamp,s=encoded-signature`

To test that the payload sent has not been compromised, you can recreate the signature using the shared secret key found on the Webhook page and compare to the one sent in the header.

1. Split the `x-knock-signature` on the comma (",") and extract the values of timestamp and signature.
2. Construct the value of the signature by concatenating:

   - The timestamp (as a string)
   - The character `.`
   - The stringified JSON payload

3. Generate the signature with an HMAC and SHA256 algorithm using the secret key from your webhook's dashboard
4. Compare your generated signature with the one extracted in step one; they should match exactly. If the timestamp is more than five minutes old compared to the current time, you may decide you want to reject the payload for additional security.

Here's an example to follow:

```javascript title="Validating a webhook payload with your secret key"
// This example uses Express to receive webhooks
const express = require("express");

const app = express();

// Find your webhook's secret key on its page in your Knock dashboard
const webhookSecret = "some-secret";

// Match the raw body to content type application/json
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (request, response) => {
    const sig = request.headers["x-knock-signature"];

    // Extract the timestamp and signature from the header and remove the identifiers
    const timestamp = sig.split(",")[0].substring(2);
    const originalSignature = sig.split(",")[1].substring(2);
    // Construct the value to be encoded
    const value = `${timestamp}.${request.body}`;

    // Generate the signature with a HMAC using the SHA256 algorithm
    const reconstructedSignature = crypto
      .createHmac("sha256", webhookSecret)
      .update(value)
      .digest("base64");

    // Compare the signature from the header with your reconstructed signature to validate
    const isValid = crypto.timingSafeEqual(
      originalSignature,
      reconstructedSignature,
    );

    // For additional security, validate that the timestamp is within your
    // tolerance for proximity to the current time (example shown within 5 minutes)
    const date = new Date(timestamp);
    const now = new Date.now();
    const isWithinFiveMinutes = now - date < 60000;

    if (isValid && isWithinFiveMinutes) {
      response.json({ received: true });
    } else {
      response.status(400).send("Webhook Error, invalid signature");
    }
  },
);

app.listen(4242, () => console.log("Running on port 4242"));
```

### Using the data

Once you receive a webhook request and return a `2xx` status code, you can make additional requests to the Knock API to gather more information about the event. For example, if you're building a webhook for the `message.undelivered` event, and you'd like to log the message's content, you can use the message ID to send a request to [get message content](/reference#get-message-content) when that event is received.

## Managing webhooks

### Reading webhook delivery logs

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Data subject to retention policy enforcement.
      </span>{" "}
      See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

When you visit a webhook's page, if it has begun to send data to your endpoint you'll see a log for every POST request. This will give you the following information:

- **Status code:** your server's response to the webhook request
- **Event type:** the type of event it was reporting on
- **Timestamp:** when the event was sent to your endpoint

You'll see details about each log as well. When you select a log, you'll be able to see the **full request payload** sent to your endpoint.

You'll also see if your endpoint has stopped working as it will display a `4xx` or `5xx` status code for undelivered webhooks.

### Disabling a webhook

When you create a webhook it will automatically be set to `enabled`. You can disable it by going to the webhook's page, and toggling the status to `disabled`. This means that it will not trigger any webhook requests when an event it is configured to listen to is fired. When you're ready to start receiving requests again, toggle the status back to `enabled`.

### Deleting a webhook

To stop receiving data to your endpoint, you can delete the webhook from its page. From `/webhooks`, click on the webhook you'd like to delete and you'll see a three-dot menu to the right of the header. Click there and you'll see the delete prompt. Keep in mind that if you delete a webhook, you'll have to recreate it to start receiving data to that endpoint again.


## Event types
Learn more about the types of events that Knock sends webhook events for.
---
title: Webhook event types
description: Learn more about the types of events that Knock sends webhook events for.
section: Developer tools > Outbound Webhooks
tags: ["events", "data", "analytics", "webhook configuration"]
---

## Message events

### `message.sent`

Occurs when a message is successfully sent to a channel provider.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.delivered`

Occurs when a message is marked as delivered to the user by the provider. This is only available on email providers with delivery tracking enabled.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.delivery_attempted`

Occurs when a message delivery attempt fails and may be retried.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the attempt, the total attempts, and whether or not it will be retried"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="attempt"
    type="number"
    description="The current attempt count"
  />
  <Attribute
    name="max_attempts"
    type="number"
    description="The total number of attempts that can be tried"
  />
  <Attribute
    name="retryable"
    type="boolean"
    description="Whether or not the current attempt is retryable"
  />
</Attributes>

### `message.undelivered`

Occurs when a message delivery attempt fails permanently. Delivery will not be retried.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="May include additional information about the failure"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="failure_reason"
    type="string"
    description="The reason for a message failure"
  />
  <Attribute
    name="failure_details"
    type="string"
    description="Details about a message failure"
  />
</Attributes>

### `message.bounced`

Occurs when a message delivery attempt fails due to bounce or a delivery status check results in a bounce because of a bad recipient(s) identifier. Delivery will not be retried.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="May include additional information about the failure."
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="failure_reason"
    type="string"
    description="The reason for a message failure"
  />
  <Attribute
    name="failure_details"
    type="string"
    description="Details about a message bounce"
  />
  <Attribute
    name="token"
    type="string"
    description="The erroneous token causing the bounce. Only applicable for push messages."
  />
</Attributes>

### `message.seen`

Occurs when a message is seen by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.unseen`

Occurs when a message is unseen by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.read`

Occurs when a message is read by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.unread`

Occurs when a message is unread by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.archived`

Occurs when a message is archived by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.unarchived`

Occurs when a message is unarchived by its recipient.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
</Attributes>

### `message.interacted`

Occurs when a message is interacted with by its recipient. For the Knock in-app feed, this indicates that your recipient has explicitly clicked on the notification cell in their feed.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
  <Attribute
    name="event_data"
    type="object"
    description="Includes any additional metadata included in the interacted event"
  />
</Attributes>

### `message.link_clicked`

Occurs when a link is clicked by the message recipient. This is only available when Knock link tracking is enabled.

<Attributes>
  <Attribute
    name="data"
    type="Message"
    description="The associated message"
    typeSlug="/reference#messages"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="May include additional information about the link click event"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="url"
    type="string"
    description="The target URL that was clicked"
  />
</Attributes>

## Workflow events

### `workflow.updated`

Occurs whenever a workflow is updated in the environment.

<Attributes>
  <Attribute
    name="data"
    type="Workflow"
    description="The associated workflow"
    typeSlug="/mapi#workflows-object"
  />
</Attributes>

### `workflow.committed`

Occurs whenever a workflow is committed to the environment.

<Attributes>
  <Attribute
    name="data"
    type="Workflow"
    description="The associated workflow"
    typeSlug="/mapi#workflows-object"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the commit"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="commit_id"
    type="string"
    description="The ID of the corresponding commit for the event"
  />
</Attributes>

## Email layout events

### `email_layout.updated`

Occurs whenever an email layout is updated in the environment.

<Attributes>
  <Attribute
    name="data"
    type="EmailLayout"
    description="The associated email layout"
    typeSlug="/mapi#email-layouts-object"
  />
</Attributes>

### `email_layout.committed`

Occurs whenever an email layout is committed to the environment.

<Attributes>
  <Attribute
    name="data"
    type="EmailLayout"
    description="The associated email layout"
    typeSlug="/mapi#email-layouts-object"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the commit"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="commit_id"
    type="string"
    description="The ID of the corresponding commit for the event"
  />
</Attributes>

## Translation events

### `translation.updated`

Occurs whenever a translation is updated in the environment.

<Attributes>
  <Attribute
    name="data"
    type="Translation"
    description="The associated translation"
    typeSlug="/mapi#translations-object"
  />
</Attributes>

### `translation.committed`

Occurs whenever a translation is committed to the environment.

<Attributes>
  <Attribute
    name="data"
    type="Translation"
    description="The associated translation"
    typeSlug="/mapi#translations-object"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the commit"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="commit_id"
    type="string"
    description="The ID of the corresponding commit for the event"
  />
</Attributes>

## Source event action events

### `source_event_action.updated`

Occurs whenever a source event action is updated in the environment.

<Attributes>
  <Attribute
    name="data"
    type="SourceEventAction"
    description="The associated source event action"
    typeSlug="/integrations/sources/overview#events"
  />
</Attributes>

### `source_event_action.committed`

Occurs whenever a source event action is committed to the environment.

<Attributes>
  <Attribute
    name="data"
    type="SourceEventAction"
    description="The associated source event action"
    typeSlug="/integrations/sources/overview#events"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the commit"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="commit_id"
    type="string"
    description="The ID of the corresponding commit for the event"
  />
</Attributes>

## Partial events

### `partial.updated`

Occurs whenever a partial is updated in the environment.

<Attributes>
  <Attribute
    name="data"
    type="Partial"
    description="The associated partial"
    typeSlug="/mapi#partials-object"
  />
</Attributes>

### `partial.committed`

Occurs whenever a partial is committed to the environment.

<Attributes>
  <Attribute
    name="data"
    type="Partial"
    description="The associated partial"
    typeSlug="/mapi#partials-object"
  />
  <Attribute
    name="event_data"
    type="EventData"
    description="Additional information about the commit"
  />
</Attributes>

`EventData` attributes:

<Attributes>
  <Attribute
    name="commit_id"
    type="string"
    description="The ID of the corresponding commit for the event"
  />
</Attributes>


## Validating trigger data
Learn how to validate the data passed to your Knock workflows using JSON schemas to ensure accuracy and prevent errors in your notifications.
---
title: Validating workflow trigger data
description: Learn how to validate the data passed to your Knock workflows using JSON schemas to ensure accuracy and prevent errors in your notifications.
section: Developer tools
---

Workflow trigger data is critical for ensuring your notifications have the right content and context. To help prevent errors and maintain data integrity, Knock offers a trigger data validation feature that allows you to specify the expected structure of the data passed to your workflows.

Trigger data validation lets you define a <a href="https://json-schema.org/" target="_blank">JSON schema</a> that describes the expected shape and types of data passed to your workflow. If the incoming data doesn't match the specified schema, the trigger endpoint will return a `422 Unprocessable Entity` error with details about where the validation failed.

## How to set up trigger data validation

You can enable and configure trigger data validation in two ways:

1. **Via the Workflow Builder:**

   - Navigate to the "Trigger step" in the workflow builder
   - Under the "API params" section, click "Edit schema"
   - Supply a valid JSON schema
   - Commit your changes for the schema to take effect

2. **Via the Management API or CLI:**
   - Use the `trigger_data_json_schema` field to provide your schema

## Example schema

Here's an example of a simple schema that expects a `name` property in the trigger data:

```json title="Trigger data validation schema"
{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "required": ["name"]
}
```

With this schema in place, if the `name` property is missing or not a string, the trigger endpoint will return a `422` error.

## Error handling

When the incoming data fails validation, the API will respond with:

- Status code: `422 Unprocessable Entity`
- Response body: A list of validation errors, indicating where the data failed to meet the schema requirements

This ensures that your workflows are not executed with incorrect or incomplete data, helping to maintain the integrity of your notification system.

## Availability

Trigger data validation is available to all Knock customers. We recommend implementing it for all critical workflows to ensure data consistency and prevent potential issues in your notification pipeline.


## LLM resources

## llms.txt

## llms-full.txt


# SDKs

## Overview
Libraries and tools for interacting with your Knock integration.
---
title: Knock SDKs
description: Libraries and tools for interacting with your Knock integration.
tags: ["cancellations", "cancellation_key", "cancel", "batch", "remove"]
section: Send notifications
---

## Server-side SDKs

Knock's server-side helper libraries (also known as server-side SDKs) reduce the amount of work required to use Knock's REST APIs, starting with reducing the boilerplate code you have to write when integrating Knock in your server-side application.

<SdkCardGroup>
  <SdkCard
    title="Node SDK"
    linkUrl="https://github.com/knocklabs/knock-node"
    icon="node"
    languages={["Node.js", "TypeScript"]}
    isExternal={true}
  />
  <SdkCard
    title="Python SDK"
    linkUrl="https://github.com/knocklabs/knock-python"
    icon="python"
    languages={["Python"]}
    isExternal={true}
  />
  <SdkCard
    title="Ruby SDK"
    linkUrl="https://github.com/knocklabs/knock-ruby"
    icon="ruby"
    languages={["Ruby"]}
    isExternal={true}
  />
  <SdkCard
    title="Go SDK"
    linkUrl="https://github.com/knocklabs/knock-go"
    icon="go"
    languages={["Golang"]}
    isExternal={true}
  />
  <SdkCard
    title="Java SDK"
    linkUrl="https://github.com/knocklabs/knock-java"
    icon="java"
    languages={["Java"]}
    isExternal={true}
  />
  <SdkCard
    title=".NET SDK"
    linkUrl="https://github.com/knocklabs/knock-dotnet"
    icon="dotnet"
    languages={["C#"]}
    isExternal={true}
  />
  <SdkCard
    title="Elixir SDK"
    linkUrl="https://github.com/knocklabs/knock-elixir"
    icon="elixir"
    languages={["Elixir"]}
    isExternal={true}
  />
  <SdkCard
    title="PHP SDK"
    linkUrl="https://github.com/knocklabs/knock-php"
    icon="php"
    languages={["PHP"]}
    isExternal={true}
  />
</SdkCardGroup>

## Client-side SDKs

Knock's client-side libraries (also known as client-side SDKs) reduce the amount of work required to use Knock within your client-side applications and provide a foundation for [building in-app notification experiences](/in-app-ui/overview) on top of.

### Web SDKs

<SdkCardGroup>
  <SdkCard
    title="Javascript SDK"
    linkUrl="https://github.com/knocklabs/javascript/tree/main/packages/client"
    icon="javascript"
    languages={["JavaScript", "TypeScript"]}
    isExternal={true}
  />
  <SdkCard
    title="React SDK"
    linkUrl="https://github.com/knocklabs/javascript/tree/main/packages/react"
    icon="react"
    languages={["JavaScript", "TypeScript"]}
    isExternal={true}
  />
</SdkCardGroup>

### Mobile SDKs

<SdkCardGroup>
  <SdkCard
    title="iOS SDK"
    linkUrl="https://github.com/knocklabs/knock-swift"
    icon="swift"
    languages={["Swift"]}
    isExternal={true}
  />
  <SdkCard
    title="Android SDK"
    linkUrl="https://github.com/knocklabs/knock-android"
    icon="kotlin"
    languages={["Kotlin"]}
    isExternal={true}
  />
  <SdkCard
    title="Flutter SDK"
    linkUrl="https://github.com/knocklabs/knock-flutter"
    icon="flutter"
    languages={["Flutter", "Dart"]}
    isExternal={true}
  />
  <SdkCard
    title="React Native SDK"
    linkUrl="https://github.com/knocklabs/javascript/tree/main/packages/react-native"
    icon="reactnative"
    languages={["JavaScript", "TypeScript"]}
    isExternal={true}
  />
  <SdkCard
    title="Expo SDK"
    linkUrl="https://github.com/knocklabs/javascript/tree/main/packages/expo"
    icon="expo"
    languages={["JavaScript", "TypeScript"]}
    isExternal={true}
  />
</SdkCardGroup>


## React (Web)

## Overview
Learn more about integrating Knock into your web applications through our React SDK.
---
title: "Knock React SDK"
description: Learn more about integrating Knock into your web applications through our React SDK.
section: SDKs
---

Our [`@knocklabs/react`](https://github.com/knocklabs/javascript/tree/main/packages/react) library lets you create notification experiences using Knock's APIs. It comes with pre-built UI components that you can use to easily get up-and-running with a fully functional notification feed experience in your product.

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">New Knock React components.</span> If you're
      currently using <code>@knocklabs/react-notification-feed</code>, check out
      our{" "}
      <a href="/in-app-ui/react/migrating-from-react-notification-feed">
        migration guide
      </a>{" "}
      to learn how to use our new React library.
    </>
  }
/>

The React library is built on-top of the `@knocklabs/client` JS SDK and includes that library as an implicit dependency.

[See a live demo](https://in-app-demo.knock.app/)

**You can also use the library to build:**

- [Floating notification feeds](/in-app-ui/react/feed)
- [Real-time notification toasts](/in-app-ui/react/toasts)
- [Notification inboxes](/in-app-ui/react/inbox)
- [Custom notification UI](/in-app-ui/react/custom-notifications-ui)
- [Notification preferences](/in-app-ui/react/preferences)

**Quick links:**

- [`@knocklabs/react` on npm](https://www.npmjs.com/package/@knocklabs/react)
- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Package on GitHub](https://github.com/knocklabs/javascript/tree/main/packages/react)
- [React SDK reference](/sdks/react/reference)
- [JS SDK reference](/sdks/javascript/reference)

## Need help?

Our React library is worked on full-time by the Knock JavaScript team.

### Join the community

Ask questions and find answers on those following platforms:

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/javascript/issues/new)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/javascript/pulls/new).


## API reference
Complete API reference for the Knock React SDK.
---
title: "React SDK API reference"
description: Complete API reference for the Knock React SDK.
tags: ["mark as read"]
section: SDKs
---

In this section, you'll find the complete documentation for the components exposed in `@knocklabs/react`, including the props available.

**Note**: You can see a reference for the methods available for the `Knock` class, as well as a `Feed` instance under the [client JS docs](/sdks/javascript/reference).

## Context

### `KnockProvider`

The top-level provider that connects to Knock with the given API key and authenticates a user.

#### Props

Accepts `KnockProviderProps`

<Attributes>
  <Attribute
    name="apiKey*"
    type="string"
    description="The public API key for the environment"
  />
  <Attribute
    name="userId*"
    type="string"
    description="The ID of the user for which to retrieve a feed"
  />
  <Attribute
    name="userToken"
    type="string"
    description={
      <span>
        A JWT that identifies the authenticated user, signed with the private
        key provided in the Knock dashboard. Required to secure your production
        environment.{" "}
        <a
          href="https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled"
          target="_blank"
        >
          Learn more.
        </a>
      </span>
    }
  />
  <Attribute
    name="onUserTokenExpiring"
    type="(oldToken: string) => Promise<string | void>"
    description="A callback to provide that will fire before a user Token expires. By default will fire 30s before the token is set to expire. If a string is returned from the resolved promise, that will be used as the new user token."
  />
  <Attribute
    name="timeBeforeExpirationInMs"
    type="number"
    description="Determines the amount of time in milliseconds before the token expires that the callback should be fired."
  />
  <Attribute
    name="host"
    type="string"
    description="A custom API host for Knock"
  />
  <Attribute
    name="i18n"
    type="I18nContent"
    description="An optional set of translations to override the default `en` translations used in the feed components"
  />
</Attributes>

#### `useKnockClient`

The `KnockProvider` exposes a `useKnockClient` hook for all child components.

**Returns**: `Knock`, an instance of the Knock JS client.

**Example**:

```jsx
import { KnockProvider, useKnockClient } from "@knocklabs/react";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <MyComponent />
  </KnockProvider>
);

const MyComponent = () => {
  const knock = useKnockClient();

  return null;
};
```

### `KnockFeedProvider`

The feed-specific provider that connects to a feed for that user. Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockFeedProviderProps`:

<Attributes>
  <Attribute
    name="feedId*"
    type="string"
    description="The channel ID of the in-app feed to be displayed"
  />
  <Attribute
    name="defaultFeedOptions"
    type="FeedClientOptions"
    description="Set defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queries"
  />
  <Attribute
    name="colorMode"
    type="ColorMode"
    description="Sets the theme as either light or dark mode (defaults to light)"
  />
</Attributes>

#### `useKnockFeed`

The `KnockFeedProvider` exposes a `useKnockFeed` hook for all child components.

**Returns**: `KnockFeedProviderState`

<Attributes>
  <Attribute
    name="knock"
    type="Knock"
    description="The instance of the Knock client"
  />
  <Attribute
    name="feedClient"
    type="Feed"
    description="The instance of the authenticated Feed"
  />
  <Attribute
    name="useFeedStore"
    type="UseStore<FeedStoreState>"
    description="A zustand store containing the FeedStoreState"
  />

  <Attribute
    name="colorMode"
    type="ColorMode"
    description="The current theme color"
  />
</Attributes>

**Example**:

```jsx
import {
  KnockProvider,
  KnockFeedProvider,
  useKnockFeed,
} from "@knocklabs/react";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
      <MyFeedComponent />
    </KnockFeedProvider>
  </KnockProvider>
);

const MyFeedComponent = () => {
  const { useFeedStore } = useKnockFeed();
  const items = useFeedStore((state) => state.items);

  return (
    <div className="notifications">
      {items.map((item) => (
        <NotificationCell key={item.id} item={item} />
      ))}
    </div>
  );
};
```

### `KnockInAppMessagesChannelProvider`

#### Props

<Attributes>
  <Attribute
    name="channelId*"
    type="string"
    description="The in-app messaging channel ID obtained from the Knock dashboard under “Integrations > Channels”. Should be a UUID."
  />
  <Attribute
    name="defaultOptions*"
    type="string"
    description="A set of default options to apply to all fetches for in-app messages. Here you can set common defaults, like the tenants you wish to scope messages for etc."
  />
  <Attribute
    name="colorMode*"
    type="string"
    description="Either light or dark to pass a theme down to components."
  />
</Attributes>

#### `useInAppMessagesChannel`

Only available under the `KnockInAppMessagesChannelProvider`.

**Returns**:

<Attributes>
  <Attribute
    name="inAppMessagesChannelClient*"
    type="string"
    description="An in-app message client that stores the shared state of in-app messages."
  />
  <Attribute
    name="colorMode*"
    type="string"
    description="The current color mode."
  />
</Attributes>

### `KnockSlackProvider`

The Slack-specific provider that connects to a Slack workspace for the given tenant. Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockSlackProviderProps`

<Attributes>
  <Attribute
    name="knockSlackChannelId*"
    type="string"
    description="The ID of the Slack channel in the Knock dashboard that the Slack application is linked to."
  />
  <Attribute
    name="tenant*"
    type="string"
    description="The ID of the tenant that will be storing the Slack access token"
  />
</Attributes>

### `KnockMsTeamsProvider`

The Microsoft Teams-specific provider that connects to Microsoft Teams for the given tenant. Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockMsTeamsProviderProps`

<Attributes>
  <Attribute
    name="knockMsTeamsChannelId*"
    type="string"
    description="The ID of the Microsoft Teams channel in the Knock dashboard that the Microsoft Teams bot is linked to."
  />
  <Attribute
    name="tenantId*"
    type="string"
    description="The ID of the Knock tenant that will be storing the Microsoft Entra tenant ID"
  />
</Attributes>

#### `useKnockSlackClient`

The `KnockSlackProvider` exposes a `useKnockSlackClient` hook for all child components.

**Returns**:

<Attributes>
  <Attribute
    name="connectionStatus"
    type="ConnectionStatus"
    description="The status of the auth connection to the given Slack client"
  />
  <Attribute
    name="setConnectionStatus"
    type="function"
    description="A function to set the connection status"
  />
  <Attribute
    name="errorLabel"
    type="string"
    description="An error message about the connection status"
  />
  <Attribute
    name="setErrorLabel"
    type="function"
    description="A function to set an error label"
  />
  <Attribute
    name="actionLabel"
    type="string"
    description="A label that gives an action for the user to take, like 'Retry' or 'Disconnect'"
  />
  <Attribute
    name="setActionLabel"
    type="function"
    description="A function to set the action label"
  />
</Attributes>

**Example**:

```jsx
import {
  KnockProvider,
  KnockSlackProvider,
  useKnockSlackClient,
} from "@knocklabs/react-core";

const App = ({ authenticatedUser, tenant }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <KnockSlackProvider knockSlackChannelId={process.env.KNOCK_SLACK_CHANNEL_ID} tenant={tenant}>
      <MySlackComponent />
    </KnockFeedProvider>
  </KnockProvider>
);

const MySlackComponent = () => {
    const { connectionStatus,
        setConnectionStatus,
        errorLabel,
        setErrorLabel,
        actionLabel,
        setActionLabel,
        knockSlackChannelId,
        tenant, } =
    useKnockSlackClient();

  return (
    <div className="slack-auth-status">
        <AuthStatus connectionStatus={connectionStatus} />
    </div>
  );
};
```

## General components

### `Button`

A generic Button component that can be used to add action buttons to items in a notification feed.

#### Props

<Attributes>
  <Attribute
    name="variant"
    type="string"
    description="The variant of the button; either `primary` or `secondary`. Defaults to `primary`."
  />
  <Attribute
    name="loadingText"
    type="string"
    description="Text to display while the button is loading."
  />
  <Attribute
    name="isLoading"
    type="boolean"
    description="When true, will display a spinner next to the `loadingText` (if present)."
  />
  <Attribute
    name="isDisabled"
    type="boolean"
    description="When true, will mark the button as disabled."
  />
  <Attribute
    name="isFullWidth"
    type="boolean"
    description="When true, will make the button occupy 100% of the parent container."
  />
  <Attribute
    name="onClick*"
    type="function"
    description="The click handler to be invoked when the button is clicked."
  />
  <Attribute
    name="children"
    type="ReactNode"
    description="The text to display inside of the button."
  />
</Attributes>

### `ButtonGroup`

Used to group and space multiple `Button` components into a single line.

#### Props

<Attributes>
  <Attribute
    name="children*"
    type="ReactNode"
    description="One or more `Button` components"
  />
</Attributes>

### `KnockI18nProvider`

A provider to inject translations into components.

#### Props

<Attributes>
  <Attribute
    name="i18n"
    type="I18nContent"
    description="A set of translations and a locale to use in child components via the `useTranslations` hook"
  />
  <Attribute
    name="children*"
    type="ReactNode"
    description="One or more `Button` components"
  />
</Attributes>

## Feed components

### `NotificationFeed`

#### Props

<Attributes>
  <Attribute
    name="EmptyComponent*"
    type="ReactNode"
    description="The empty component to render, when not set defaults to <EmptyFeed />."
  />
  <Attribute
    name="renderItem"
    type="function"
    description="A function invoked per `FeedItem` to be rendered that should return a cell to be rendered in the feed. Useful when you want to render a custom feed cell. Defaults to rendering a `NotificationCell`."
  />
  <Attribute
    name="renderHeader"
    type="function"
    description="A function invoked that returns a header to be rendered in the feed. Useful when you want to render a custom header. Defaults to rendering a `NotificationFeedHeader`."
  />
  <Attribute
    name="onNotificationClick"
    type="function"
    description="A custom function to be invoked when a notification cell is clicked."
  />
  <Attribute
    name="onNotificationButtonClick"
    type="function"
    description="A custom function to be invoked when an action button in a notification cell is clicked."
  />
  <Attribute
    name="onMarkAllAsReadClick"
    type="function"
    description="A custom function to be invoked when the `Mark all as read` button is clicked."
  />
  <Attribute
    name="initialFilterStatus"
    type="FilterStatus"
    description="The initial filter applied by the NotificationFeed (e.g., `FilterStatus.All` or `FilterStatus.Unread`). If unspecified, defaults to 'All'."
  />
</Attributes>

### `NotificationFeedPopover`

Renders a `NotificationFeed` in a floating popover, rendered by `popper-js`.

#### Props

Accepts the same base props as `NotificationFeed`, and overrides with the following:

<Attributes>
  <Attribute
    name="isVisible*"
    type="boolean"
    description="Whether or not to show the popover."
  />
  <Attribute
    name="onClose*"
    type="function"
    description="The function to be invoked when the popover is closed."
  />
  <Attribute
    name="onOpen"
    type="function"
    description="A function that's invoked whenever the feed popover is opened, useful for updating any items in view and marking them as read, seen, or archived."
  />
  <Attribute
    name="buttonRef*"
    type="RefObject<HTMLElement>"
    description="A ref of the button to position the popover adjacent to."
  />
  <Attribute
    name="closeOnClickOutside"
    type="boolean"
    description="When true, will close the popover whenever any area outside of the popover is clicked."
  />
  <Attribute
    name="placement"
    type="Placement"
    description="Determines the popper-js position of the popover (defaults to `bottom-end`)."
  />
</Attributes>

### `NotificationCell`

#### Props

<Attributes>
  <Attribute
    name="item*"
    type="FeedItem"
    description="The feed item (notification) to render"
  />
  <Attribute
    name="onItemClick"
    type="function"
    description="The function to be invoked when the notification cell is clicked"
  />
  <Attribute
    name="onButtonClick"
    type="function"
    description="The function to be invoked when a button rendered in the notification cell is clicked"
  />
  <Attribute
    name="avatar"
    type="ReactNode"
    description="Render a custom avatar for the feed item"
  />
  <Attribute
    name="archiveButton"
    type="ReactNode"
    description="Render a custom archive button for the feed item"
  />
  <Attribute
    name="children"
    type="ReactNode"
    description="A set of children to render inside of the cell, will be rendered under the main content in a `rnf-notification-cell__child-content` div. Useful for rendering action buttons."
  />
</Attributes>

### `NotificationIconButton`

Renders a notification bell icon, with a badge showing the number of unseen items present in the notification feed.

#### Props

<Attributes>
  <Attribute
    name="onClick*"
    type="function"
    description="The function to be invoked when the IconButton is clicked"
  />
  <Attribute
    name="badgeCountType"
    type="enum"
    description="One of `unseen` | `unread` | `all` to determine which count to display"
  />
</Attributes>

## Messaging components

By default, our React library exposes 3 different out of the box components: `Banner`, `Card`, and `Modal`. Each component maps to a message type that Knock ships.

Each of the components exports a `*View` component that contains granular view components that can be composed to override specific parts of the pre-built components.

### `Banner`

#### Props

<Attributes>
  <Attribute
    name="filters"
    type="UseInAppMessageOptions"
    description="A set of query filters"
  />
</Attributes>

#### Example

```jsx
import { Banner } from "@knocklabs/react";

<Banner filters={{ tenant_id: "tenant-1" }} />;
```

### `Card`

#### Props

<Attributes>
  <Attribute
    name="filters"
    type="UseInAppMessageOptions"
    description="A set of query filters"
  />
</Attributes>

#### Example

```jsx
import { Card } from "@knocklabs/react";

<Card filters={{ tenant_id: "tenant-1" }} />;
```

### `Modal`

#### Props

<Attributes>
  <Attribute
    name="filters"
    type="UseInAppMessageOptions"
    description="A set of query filters"
  />
</Attributes>

#### Example

```jsx
import { Modal } from "@knocklabs/react";

<Modal filters={{ tenant_id: "tenant-1" }} />;
```

## Slack components

### `SlackAuthButton`

#### Props

<Attributes>
  <Attribute
    name="slackClientId*"
    type="string"
    description="The client ID of your Slack application."
  />
  <Attribute
    name="redirectUrl"
    type="string"
    description="The URL of your application to return to once Slack authorization is complete."
  />
  <Attribute
    name="onAuthenticationComplete"
    type="(authenticationResult: 'authComplete' | 'authFailed') => void;"
    description="An optional callback function you can pass to this component that will execute upon completion of the authentication flow. Takes one argument of the authentication result for you to handle in your callback."
  />
</Attributes>

### `SlackAuthContainer`

#### Props

<Attributes>
  <Attribute
    name="actionButton*"
    type="ReactNode"
    description="Render a button, either a custom one or the SlackAuthButton, to connect to Slack"
  />
</Attributes>

### `SlackChannelCombobox`

#### Props

<Attributes>
  <Attribute
    name="slackChannelsRecipientObject*"
    type="RecipientObject"
    description="Object ID and collection of the Knock object that will store the channel data of the connected Slack channels."
  />
  <Attribute
    name="queryOptions"
    type="SlackChannelQueryOptions"
    description="An optional map of params to control the query to the Slack API"
  />
</Attributes>

## Microsoft Teams components

### `MsTeamsAuthButton`

#### Props

<Attributes>
  <Attribute
    name="msTeamsBotId*"
    type="string"
    description="The ID of your Microsoft Teams bot."
  />
  <Attribute
    name="redirectUrl"
    type="string"
    description="The URL of your application to return to once Microsoft Teams authorization is complete."
  />
  <Attribute
    name="onAuthenticationComplete"
    type="(authenticationResult: 'authComplete' | 'authFailed') => void;"
    description="An optional callback function you can pass to this component that will execute upon completion of the authentication flow. Takes one argument of the authentication result for you to handle in your callback."
  />
</Attributes>

### `MsTeamsAuthContainer`

#### Props

<Attributes>
  <Attribute
    name="actionButton*"
    type="ReactNode"
    description="Render a button, either a custom one or the MsTeamsAuthButton, to connect to Microsoft Teams"
  />
</Attributes>

### `MsTeamsChannelCombobox`

#### Props

<Attributes>
  <Attribute
    name="msTeamsChannelsRecipientObject*"
    type="RecipientObject"
    description="Object ID and collection of the Knock object that will store the channel data of the connected Microsoft Teams channels."
  />
</Attributes>

## General hooks

### `useAuthenticatedKnockClient`

Creates an authenticated Knock client.

#### Params

<Attributes>
  <Attribute
    name="apiKey*"
    type="string"
    description="The public API key for the Knock environment"
  />
  <Attribute
    name="userId"
    type="string"
    description="The userId of the user to authenticate with Knock."
  />
  <Attribute
    name="userToken"
    type="string"
    description="Optional user token to authenticate requests for the current user with."
  />
  <Attribute
    name="options"
    type="AuthenticatedKnockClientOptions"
    description="A set of options to provide to the Knock instance."
  />
</Attributes>

#### Returns

`Knock` instance, authenticated against the user

#### Example

```jsx
import { useAuthenticatedKnockClient } from "@knocklabs/react";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  return null;
};
```

### `useTranslations`

Exposed under `KnockI18nProvider` child components.

**Returns**:

<Attributes>
  <Attribute
    name="locale"
    type="string"
    description="The current locale code (defaults to `en`)"
  />
  <Attribute
    name="t"
    type="(key: string) => string"
    description="A helper function to get the value of a translation from the current `Translations`."
  />
</Attributes>

## Feed hooks

### `useNotifications`

Creates a `Feed` instance for the provided `Knock` client which creates a stateful, real-time connection to Knock to build in-app experiences.

#### Params

<Attributes>
  <Attribute
    name="knock"
    type="Knock"
    description="The Knock instance to create the feed with"
  />
  <Attribute
    name="feedChannelId"
    type="string"
    description="The in-app feed channel ID, obtained from the Knock dashboard"
  />
  <Attribute
    name="options"
    type="FeedClientOptions"
    description="An optional set of feed client options to pass to the created Feed instance"
  />
</Attributes>

#### Returns

`Feed` instance

#### Example

```js
import {
  useAuthenticatedKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/react";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  const notificationFeed = useNotifications(
    knock,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { metadata } = useNotificationStore(notificationFeed);

  useEffect(() => {
    notificationFeed.fetch();
  }, [notificationFeed]);

  return <span>Total unread: {metadata.unread_count}</span>;
};
```

### `useNotificationStore`

Given a `Feed` will return reactive access to the `FeedStateStore`. Can optionally accept a `selector` to retrieve a fine-grained slice of state from the store.

#### Params

<Attributes>
  <Attribute
    name="feedClient"
    type="Feed"
    description="The feed instance to select content from"
  />
  <Attribute
    name="selector"
    type="StateSelector<FeedStoreState>"
    description="An optional selector to limit the state slice returned from the store. Defaults to returning all state."
  />
</Attributes>

#### Returns

`FeedStoreState`

#### Example

```js
import { useNotificationStore } from "@knocklabs/react";

const MyComponent = () => {
  // Fetch everything
  const state = useNotificationStore(feedClient);

  // Only select the metadata
  const metadata = useNotificationStore(feedClient, (state) => state.metadata);

  // Filter for only unread items
  const unreadItems = useNotificationStore(feedClient, (s) =>
    s.items.filter((item) => !item.read_at),
  );
};
```

## Messaging hooks

### `useInAppMessages`

A hook used to fetch in-app messages for a particular user, channel, message type triple.

**Props**:

<Attributes>
  <Attribute
    name="messageType"
    type="string"
    description="The key of the message type you wish to fetch messages about"
  />
  <Attribute
    name="options"
    type="InAppMessagesClientOptions"
    description="A set of filtering options to apply to the message fetched from this hook"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="messages"
    type="Message[]"
    description="The returned in-app messages"
  />
  <Attribute
    name="loading"
    type="boolean"
    description="Whether the network request is currently in-flight"
  />
  <Attribute
    name="networkStatus"
    type="NetworkStatus"
    description="Granular information about the current network status"
  />
  <Attribute
    name="inAppMessagesClient"
    type="InAppMessagesClient"
    description="A message client instance to interact with the message"
  />
</Attributes>

**Example**:

```jsx
import { useInAppMessage } from "@knocklabs/react";

const MyMessage = () => {
  const { message, inAppMessagesClient } = useInAppMessage("type", {
    tenant_id: "tenant-1",
  });

  if (!message) return null;

  return <div>Fetched message: {message.id}</div>;
};
```

## Slack hooks

Exposed under `KnockSlackProvider` child components.

### useSlackAuth

Builds a Slack authorization URL generator and a disconnect function.

**Props**:

<Attributes>
  <Attribute
    name="slackClientId"
    type="string"
    description="The client ID from your Slack app"
  />
  <Attribute
    name="redirectUrl"
    type="string"
    description="The URL to redirect back to after authorizing; should be your own application's URL"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="buildSlackAuthUrl"
    type="function"
    description="Function to build a valid Slack URL with the necessary scopes"
  />
  <Attribute
    name="disconnectFromSlack"
    type="function"
    description="Function to disconnect from Slack which revokes the access token and removes it from the tenant in Knock"
  />
</Attributes>

### useSlackChannels

This hook will continually fetch partial data about Slack channels from a given workspace up to the max limit given.

**Props**:

<Attributes>
  <Attribute
    name="queryOptions"
    type="SlackChannelQueryOptions"
    description="An optional map of params to control the query to the Slack API"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="data"
    type="SlackChannel[]"
    description="List of partial data about each Slack channel"
  />
  <Attribute
    name="isLoading"
    type="boolean"
    description="Whether the channels are loading"
  />
  <Attribute
    name="refetch"
    type="function"
    description="Function to fetch the channels again"
  />
</Attributes>

### useConnectedSlackChannels

This hook returns partial data about the Slack channels that are present on the given recipient object's channel data. These are the Slack channels that would be notified with this object as a recipient of a workflow.

**Props**:

<Attributes>
  <Attribute
    name="slackChannelsRecipientObject"
    type="RecipientObject"
    description="The object that holds connected Slack channels as channel data"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="data"
    type="SlackChannelConnection[]"
    description="List of data about the connected Slack channels"
  />
  <Attribute
    name="loading"
    type="boolean"
    description="Whether the channels are loading"
  />
  <Attribute
    name="error"
    type="string"
    description="Error message if something went wrong; otherwise null"
  />
  <Attribute
    name="updateConnectedChannels"
    type="(connectedChannels: SlackChannelConnection[]) => Promise<void>;"
    description="Function to set the connected channels. Updates all connected channels for the object, does not add to the current ones."
  />
  <Attribute
    name="updating"
    type="boolean"
    description="Whether the channels are currently being set"
  />
</Attributes>

## Microsoft Teams hooks

Exposed under `KnockMsTeamsProvider` child components.

### `useMsTeamsAuth`

Builds a Microsoft Teams authorization URL generator and a disconnect function.

**Props**:

<Attributes>
  <Attribute
    name="msTeamsBotId"
    type="string"
    description="The ID of your Microsoft Teams bot"
  />
  <Attribute
    name="redirectUrl"
    type="string"
    description="The URL to redirect back to after authorizing; should be your own application's URL"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="buildMsTeamsAuthUrl"
    type="function"
    description="Function to build a valid Microsoft Teams authorization URL"
  />
  <Attribute
    name="disconnectFromMsTeams"
    type="function"
    description="Function to disconnect from Microsoft Teams which removes the Microsoft Entra tenant ID from the tenant in Knock"
  />
</Attributes>

### `useMsTeamsTeams`

This hook will continually fetch partial data about Microsoft Teams teams within a given Microsoft Entra tenant up to the max limit given.

**Props**:

<Attributes>
  <Attribute
    name="queryOptions"
    type="MsTeamsTeamQueryOptions"
    description="An optional map of params to control the query to the Microsoft Graph API"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="data"
    type="MsTeamsTeam[]"
    description="List of partial data about each team"
  />
  <Attribute
    name="isLoading"
    type="boolean"
    description="Whether the teams are loading"
  />
  <Attribute
    name="refetch"
    type="function"
    description="Function to fetch the teams again"
  />
</Attributes>

### `useMsTeamsChannels`

This hook will continually fetch partial data about Microsoft Teams channels within a given team.

**Props**:

<Attributes>
  <Attribute
    name="teamId"
    type="string"
    description="The ID of the team to fetch channels from"
  />
  <Attribute
    name="queryOptions"
    type="MsTeamsChannelQueryOptions"
    description="An optional map of params to control the query to the Microsoft Graph API"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="data"
    type="MsTeamsChannel[]"
    description="List of partial data about each Microsoft Teams channel"
  />
  <Attribute
    name="isLoading"
    type="boolean"
    description="Whether the Microsoft Teams channels are loading"
  />
  <Attribute
    name="refetch"
    type="function"
    description="Function to fetch the Microsoft Teams channels again"
  />
</Attributes>

### `useConnectedMsTeamsChannels`

This hook returns partial data about the Microsoft Teams channels that are present on the given recipient object's channel data. These are the Microsoft Teams channels that would be notified with this object as a recipient of a workflow.

**Props**:

<Attributes>
  <Attribute
    name="msTeamsChannelsRecipientObject"
    type="RecipientObject"
    description="The object that holds connected Microsoft Teams channels as channel data"
  />
</Attributes>

**Returns**:

<Attributes>
  <Attribute
    name="data"
    type="MsTeamsChannelConnection[]"
    description="List of data about the connected Microsoft Teams channels"
  />
  <Attribute
    name="loading"
    type="boolean"
    description="Whether the Microsoft Teams channels are loading"
  />
  <Attribute
    name="error"
    type="string"
    description="Error message if something went wrong; otherwise null"
  />
  <Attribute
    name="updateConnectedChannels"
    type="(connectedChannels: MsTeamsChannelConnection[]) => Promise<void>;"
    description="Function to set the connected Microsoft Teams channels. Updates all connected channels for the object, does not add to the current ones."
  />
  <Attribute
    name="updating"
    type="boolean"
    description="Whether the Microsoft Teams channels are currently being set"
  />
</Attributes>

## Types

### `I18nContent`

Used to set translations available in the child components exposed under `KnockFeedProvider`, `KnockSlackProvider`, and `KnockMsTeamsProvider`. Used in the `useTranslations` hook.

**Note:** `locale` must be a valid locale code.

```typescript
interface Translations {
  readonly emptyFeedTitle: string;
  readonly emptyFeedBody: string;
  readonly notifications: string;
  readonly poweredBy: string;
  readonly markAllAsRead: string;
  readonly archiveNotification: string;
  readonly all: string;
  readonly unread: string;
  readonly read: string;
  readonly unseen: string;

  readonly msTeamsChannelSetError: string;
  readonly msTeamsConnect: string;
  readonly msTeamsConnected: string;
  readonly msTeamsConnecting: string;
  readonly msTeamsConnectionErrorExists: string;
  readonly msTeamsConnectionErrorOccurred: string;
  readonly msTeamsConnectContainerDescription: string;
  readonly msTeamsDisconnect: string;
  readonly msTeamsDisconnecting: string;
  readonly msTeamsError: string;
  readonly msTeamsReconnect: string;
  readonly msTeamsTenantIdNotSet: string;

  readonly slackConnectChannel: string;
  readonly slackChannelId: string;
  readonly slackConnecting: string;
  readonly slackDisconnecting: string;
  readonly slackConnect: string;
  readonly slackConnected: string;
  readonly slackConnectContainerDescription: string;
  readonly slackSearchbarDisconnected: string;
  readonly slackSearchbarNoChannelsConnected: string;
  readonly slackSearchbarNoChannelsFound: string;
  readonly slackSearchbarChannelsError: string;
  readonly slackSearchChannels: string;
  readonly slackConnectionErrorOccurred: string;
  readonly slackConnectionErrorExists: string;
  readonly slackChannelAlreadyConnected: string;
  readonly slackError: string;
  readonly slackDisconnect: string;
  readonly slackChannelSetError: string;
  readonly slackAccessTokenNotSet: string;
  readonly slackReconnect: string;
}

interface I18nContent {
  readonly translations: Partial<Translations>;
  readonly locale: string;
}
```

### `SlackChannelQueryOptions`

```typescript
type SlackChannelQueryOptions = {
  maxCount?: number; // The max number of channels to return; default: 1000
  limitPerPage?: number; // How many Slack channels will be returned per request; default: 200
  excludeArchived?: boolean; // Whether to include archived channels; default: true
  types?: string; // Types of channels to return; default: "private_channel,public_channel"
  teamId?: string; // Filters channels to a specific team ID; default: null
};
```

### `SlackChannel`

```typescript
type SlackChannel = {
  name: string;
  id: string;
  is_private: boolean;
  is_im: boolean;
  context_team_id: boolean;
};
```

### `SlackChannelConnection`

```typescript
type SlackChannelConnection = {
  access_token?: string;
  channel_id?: string;
  incoming_webhook?: string;
  user_id?: null;
};
```

### `MsTeamsTeamQueryOptions`

```typescript
type MsTeamsTeamQueryOptions = {
  maxCount?: number; // The max number of teams to return; default: 1000
  limitPerPage?: number; // How many teams will be returned per request; default: 100
  filter?: string; // OData $filter query param to filter teams; default: null
  select?: string; // OData $select query param to select fields; default: "id,displayName"
};
```

### `MsTeamsChannelQueryOptions`

```typescript
type MsTeamsChannelQueryOptions = {
  filter?: string; // OData $filter query param to filter channels; default: "isArchived eq false and membershipType eq 'standard'"
  select?: string; // OData $select query param to select fields; default: "id,displayName"
};
```

### `MsTeamsTeam`

```typescript
type MsTeamsTeam = {
  id: string;
  displayName: string;
  description?: string;
};
```

### `MsTeamsChannel`

```typescript
type MsTeamsChannel = {
  id: string;
  displayName: string;
  description?: string;
  membershipType?: string;
  isArchived?: boolean;
  createdDateTime?: string;
};
```

### `MsTeamsChannelConnection`

```typescript
type MsTeamsChannelConnection = {
  ms_teams_tenant_id?: string;
  ms_teams_team_id?: string;
  ms_teams_channel_id?: string;
  ms_teams_user_id?: null;
  incoming_webhook?: {
    url: string;
  };
};
```

### `RecipientObject`

```typescript
type RecipientObject = {
  objectId: string;
  collection: string;
};
```

### `ConnectionStatus`

```typescript
type ConnectionStatus =
  | "connecting"
  | "connected"
  | "disconnected"
  | "error"
  | "disconnecting";
```


## Javascript (Web)

## Overview
Learn more about integrating Knock into your web applications through our Javascript SDKs.
---
title: Knock Javascript (Web) SDK
description: Learn more about integrating Knock into your web applications through our Javascript SDKs.
section: SDKs
---

The `@knocklabs/client` library is a low-level JavaScript SDK for interacting with Knock from the client side of your JS application.

<Callout
  emoji="💡"
  text={
    <>
      If you're looking to use pre-built in-app UI elements for a web
      application, you can look at{" "}
      <a href="/in-app-ui/react/overview">React components</a>.
    </>
  }
/>

**Quick links**

- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Package on GitHub](https://github.com/knocklabs/javascript/tree/main/packages/client)
- [Full reference guide](/sdks/javascript/reference)

## Need help?

Our `@knocklabs/client` library is worked on full-time by the Knock JavaScript team.

### Join the community

Ask questions and find answers on the following platforms:

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/javascript/issues)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/javascript/pulls).


## Quick start
Get started with our Javascript SDK to build notification feed, toasts, and inbox experiences.
---
title: "Getting started with the Javascript SDK"
description: Get started with our Javascript SDK to build notification feed, toasts, and inbox experiences.
section: SDKs
---

The `@knocklabs/client` library is a low-level JavaScript SDK for interacting with Knock from the client side of your JS application. In this guide we'll show some of the main ways you can interact with the SDK:

**Quick links**

- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Package on GitHub](https://github.com/knocklabs/javascript/tree/main/packages/client)
- [Full reference guide](/sdks/javascript/reference)

## Getting started

To use this example, you'll need [an account on Knock](https://dashboard.knock.app), as well as an in-app feed channel, with a workflow that produces in-app feed messages. You'll also need:

- A public API key for the Knock environment (set as `KNOCK_PUBLIC_API_KEY`)
- The channel ID for the in-app feed (set as `KNOCK_FEED_CHANNEL_ID`)

## Installing dependencies

```bash title="Installing the package"
npm install @knocklabs/client
```

## Authenticating the current user

```javascript title="Authenticating the current user"
import Knock from "@knocklabs/client";

const knockClient = new Knock(process.env.KNOCK_PUBLIC_API_KEY);

// Tell Knock to use the users id
knockClient.authenticate(currentUser.id);
```

## Initialize a feed connection for the user

The `Knock` class exposes a `Feed` via the `initialize` method that can be used to connect the authenticated user to a Knock Feed Channel. Additionally, the `Feed` exposes a stateful store to build client-side feeds and other notification experiences.

```javascript title="Working with the Knock feed"
const knockFeed = knockClient.feeds.initialize(
  process.env.KNOCK_FEED_CHANNEL_ID,
);

// Setup a real-time connection
knockFeed.listenForUpdates();

// Fetch items for the feed
knockFeed.fetch();
```

## Marking feed item statuses

A feed instance supports marking items as seen, unseen, read, unread, archived, and unarchived:

```javascript title="Handling feed item statuses"
// Initialize the feed as in above examples
const knockFeed = knockClient.feeds.initialize(
  process.env.KNOCK_FEED_CHANNEL_ID,
);

// Mark one or more items as read
knockFeed.markAsRead(feedItemOrItems);
// Mark one or more items as seen
knockFeed.markAsSeen(feedItemOrItems);
// Mark one or more items as archived
knockFeed.markAsArchived(feedItemOrItems);

// Mark one or more items as unread
knockFeed.markAsUnread(feedItemOrItems);
// Mark one or more items as unseen
knockFeed.markAsUnseen(feedItemOrItems);
// Mark one or more items as unarchived
knockFeed.markAsUnarchived(feedItemOrItems);
```

## Retrieving preferences for the user

You can use the JS SDK to retrieve the preferences for the authenticated user, which is useful to build in-app preference UIs.

```javascript title="Getting user preferences"
const preferences = await knockClient.preferences.get();
```

## Setting preferences for the user

Similar to retrieving preferences, the `Knock` class also allows you to set preferences directly in the client for the authenticated user.

```javascript title="Setting user preferences"
await knockClient.preferences.set({
  channel_types: { email: true, sms: false },
  workflows: {
    "dinosaurs-loose": {
      channel_types: { email: false, in_app_feed: true },
    },
  },
});
```

## Automatically disconnecting sockets from inactive tabs

Optionally, you can configure the client to disconnect socket connections with inactive tabs after a brief delay. If the tab becomes active again, the socket will reconnect to continue receiving real-time updates.

```javascript title="Automatically manage socket connections"
// Initialize the feed and configure the automatic disconnect settings
const feedClient = knockClient.feeds.initialize(
  process.env.KNOCK_FEED_CHANNEL_ID,
  {
    // Turn on the automatic connection manager
    auto_manage_socket_connection: true,
    // Optionally, customize the delay amount in milliseconds. Defaults to 2000ms or 2s
    auto_manage_socket_connection_delay: 2500,
  },
);
```


## API reference
Complete API reference for the Knock Javascript SDK.
---
title: "Javascript SDK API Reference"
description: Complete API reference for the Knock Javascript SDK.
tags: ["mark as read"]
section: SDKs
---

In this section, you'll find the documentation for the classes and methods available in the [`@knocklabs/client`](https://github.com/knocklabs/javascript/tree/main/packages/client) library.

## `Knock`

The top-level `Knock` class, used to interact with a client instance.

**Params**:

<Attributes>
  <Attribute
    name="apiKey"
    type="string*"
    description="The public API key for the Knock environment."
  />
  <Attribute
    name="options"
    type="KnockOptions"
    description="Additional options to pass through."
  />
</Attributes>

**Example**:

```javascript
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
```

### `userId`

Returns the user ID of the authenticated user.

**Returns**: `string`

### `feeds`

Returns a `FeedClient` instance that can be initialized to return a feed.

Optionally a feed can be initialized with a default set of `FeedClientOptions` which will be applied to all subsequent requests.

**Returns**: `Feed` instance

**Example**:

```javascript
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

// knockFeed is now a `Feed` instance.
const knockFeed = knock.feeds.initialize(process.env.KNOCK_FEED_CHANNEL_ID, {
  archived: "exclude",
  page_size: 25,
});
```

### `user`

Returns a `UserClient` instance to interact with the users API for the current, authenticated user.

**Returns**: `UserClient` instance

**Example**:

```javascript
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const channelData = await knock.user.getChannelData({
  channelId: process.env.KNOCK_CHANNEL_ID,
});
```

### `preferences`

Returns a `Preferences` instance to interact with the preferences API for the current, authenticated user.

**Returns**: `Preferences` instance

**Example**:

```javascript
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

// Returns a `Preferences` instance that can be invoked.
await knock.preferences.getAll();
```

### `client`

Returns an instance of an authenticated `ApiClient` that can be used to make HTTP and Websocket requests to Knock.

**Returns**: `ApiClient` instance

### `authenticate`

Authenticates the current user and creates a new Knock session.

**Params**:

<Attributes>
  <Attribute
    name="userId"
    type="string*"
    description="The authenticated user to retrieve a feed for"
  />
  <Attribute
    name="userToken"
    type="string"
    description="JWT for the authenticated user. Not required in development environments."
  />
  <Attribute
    name="options"
    type="AuthenticateOptions"
    description="Additional options to authenticate your Knock user with."
  />
</Attributes>

**Returns**: `void`

**Example**:

```javascript
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id, user.knockUserToken);
```

### `teardown`

Tears down a current session and disconnects any connected sockets.

**Returns**: `void`

---

## `ApiClient`

The API client exposes direct functions for communicating with the Knock API over HTTP and websocket.

### `socket`

**Returns**: a `Socket`

---

## `FeedClient`

### `initialize`

Creates a new `Feed` instance.

### `teardownInstances`

Tears down any current feed instances.

### `reinitializeInstances`

Reinitializes any current feed instances by reconnecting their realtime connections.

---

## `Feed`

Represents the connection between a user and a feed, including methods for interacting with the items on that feed. Also includes a stateful store that can be used to build in-app notification experiences easily. See [`FeedStoreState`](#feedstorestate) for more on the shape of the store.

### `store`

**Returns**: `StoreApi<FeedStoreState>`

### `listenForUpdates`

Connects the feed instance to the realtime socket so that any new items published to the feed are received over the websocket.

**Returns**: `void`

**Example**:

```javascript title="Connecting to a realtime stream"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const knockFeed = knock.feeds.initialize(process.env.KNOCK_FEED_CHANNEL_ID);

// Listen for updates
knockFeed.listenForUpdates();

// Stop listening
knockFeed.teardown();
```

### `on`

Binds an event handler to be invoked when the event is triggered.

**Events**:

<Attributes>
  <Attribute
    name="items.received.realtime"
    type="event"
    description="Invoked whenever items are received in realtime from the socket."
  />
  <Attribute
    name="items.received.page"
    type="event"
    description="Invoked whenever items are received from performing a fetch. Will be invoked for the initial fetch as well."
  />
  <Attribute
    name="items.archived"
    type="event"
    description="Invoked when one or more items are archived."
  />
  <Attribute
    name="items.unarchived"
    type="event"
    description="Invoked when one or more items are unarchived."
  />
  <Attribute
    name="items.seen"
    type="event"
    description="Invoked when one or more items are seen."
  />
  <Attribute
    name="items.unseen"
    type="event"
    description="Invoked when one or more items are unseen."
  />
  <Attribute
    name="items.read"
    type="event"
    description="Invoked when one or more items are read."
  />
  <Attribute
    name="items.unread"
    type="event"
    description="Invoked when one or more items are unread."
  />
</Attributes>

**Params**:

<Attributes>
  <Attribute
    name="eventName"
    type="enum of `messages.new` | `items.received.realtime` | `items.received.page` | `items.received.*`"
    description="The type of event to bind to."
  />
  <Attribute
    name="callback"
    type="function"
    description="A function to be invoked when the event is triggered."
  />
</Attributes>

**Returns**: `void`.

**Example**:

```javascript title="Listening to items being received"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const knockFeed = knock.feeds.initialize(process.env.KNOCK_FEED_CHANNEL_ID);

knockFeed.on("items.received.page", ({ items }) => {
  console.log(items);
});
```

### `off`

Unbinds an existing event handler previously bound with `on`. Use this method to cleanup bound event handlers.

**Returns**: `void`.

### `getState`

Programmatically access the current `FeedStoreState`.

**Returns**: `FeedStoreState`.

### `markAllAsSeen`

Marks all of the items in the store optimistically as seen and performs a server-side request to mark **all items on the feed in the current scope** as seen. Broadcasts a `items:all_seen` event.

**Please note**: this operation is deferred and may take some time to process all items in the feed.

**Returns**: `Promise<ApiResponse>`

### `markAsSeen`

Marks the given items as `seen`. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAsUnseen`

Removes the `seen` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAllAsRead`

Marks all of the items in the store optimistically as read and performs a server-side request to mark **all items on the feed in the current scope** as read. Broadcasts a `items:all_read` event.

**Please note**: this operation is deferred and may take some time to process all items in the feed.

**Returns**: `Promise<ApiResponse>`

### `markAsRead`

Sets the `read` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAsUnread`

Removes the `read` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAllAsArchived`

Marks all of the items in the store optimistically as archived and performs a server-side request to mark **all items on the feed in the current scope** as archived. Broadcasts a `items:all_archived` event.

**Please note**: this operation is deferred and may take some time to process all items in the feed.

**Returns**: `Promise<ApiResponse>`

### `markAsArchived`

Sets the `archived` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`. Broadcasts a `items:archived` event.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAsUnarchived`

Removes the `archived` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `markAsInteracted`

Sets the `interacted` status on the item or items given. Will perform the operation optimistically, including updating the current `metadata` in the `FeedStoreState`. Broadcasts an `items:interacted` event.

**Params**:

<Attributes>
  <Attribute
    name="itemOrItems"
    type="FeedItemOrItems"
    description="A single `FeedItem` or a list of `FeedItem` to perform the update on."
  />
  <Attribute
    name="metadata"
    type="Record<string, any>"
    description="Additional metadata to be stored with the interaction event."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `fetch`

Fetches

Emits `items.received.page` events on a successful fetch.

**Params**:

<Attributes>
  <Attribute
    name="options"
    type="FetchFeedOptions"
    description="Options to pass through to the feed request"
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

### `fetchNextPage`

Fetches the next page of the feed items (if there are any more to fetch).

Emits `items.received.page` events on a successful fetch.

Note: this will apply any current feed filters and append returned items to the end of the current set of items.

---

## `UserClient`

### `get`

Retrieves the current, authenticated user by calling the [get user endpoint](/reference#get-user) directly from the client.

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Getting the authenticated user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const user = await knock.user.get();
```

### `identify`

Identifies a user by calling the [identify user endpoint](/reference#identify-user) directly from the client.

**Params**:

<Attributes>
  <Attribute
    name="properties"
    type="object"
    description="An object of key-value pairs for attributes you want to associate with the user."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Identifying a user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const user = await knock.user.identify({
  id: "1",
  name: "John Hammond",
  email: "jhammond@ingen.net",
});
```

### `getAllPreferences`

Retrieves all preferences for the authenticated user by calling the [get preferences endpoint](/reference#get-preferences-user) directly from the client.

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Getting preferences for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const preferences = await knock.user.getAllPreferences();
```

### `getPreferences`

Retrieves a preference set for the authenticated user by calling the [get preferences endpoint](/reference#get-preferences-user) directly from the client.

<Attributes>
  <Attribute
    name="preferenceSet"
    type="String"
    description="The preference set from Knock"
  />
  <Attribute
    name="tenant"
    type="String (optional)"
    description="The tenant from Knock"
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Getting a preference set for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const preferenceSet = await knock.user.getPreferences({
  preferenceSet: "default",
});
```

### `setPreferences`

Updates the authenticated user's preferences by calling the [set preferences endpoint](/reference#set-preferences-user) directly from the client.

**Params**:

<Attributes>
  <Attribute
    name="preferenceSet"
    type="SetPreferencesProperties"
    description="The preferences to set for the current user."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Setting preferences for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const preferenceSet = await knock.user.setPreferences({
  channel_types: { email: true, sms: false },
  workflows: {
    "dinosaurs-loose": {
      channel_types: { email: false, in_app_feed: true },
    },
  },
});
```

### `getChannelData`

Retrieves channel data for the authenticated user by calling the [get channel data endpoint](/reference#get-user-channel-data) directly from the client.

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID from Knock"
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Getting channel data for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const channelData = await knock.user.getChannelData({
  channelId: process.env.KNOCK_CHANNEL_ID,
});
```

### `setChannelData`

Updates the channel data for the current user by calling the [set channel data endpoint](/reference#set-user-channel-data) directly from the client.

**Params**:

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to update the channel data for"
  />
  <Attribute
    name="channelData"
    type="Any"
    description="The data to update for the channel data"
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Setting channel data for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const channelData = await knock.user.setChannelData({
  channelId: process.env.KNOCK_CHANNEL_ID,
  data: {
    tokens: ["some-fcm-token"],
  },
});
```

---

## `InAppMessagesChannelClient`

### `subscribe`

Subscribes the given in-app message client to the socket to receive real-time in-app message updates.

### `unsubscribe`

Unsubscribes the given in-app message client from the socket, cleaning up any connection handlers in the process.

### `store`

Exposes a `@tanstack/store` store for setting message and query information per in-app message client.

## `InAppMessagesClient`

An in-app message client represents the query for a single UI element to the in-app messages API.

### `constructor`

Initializes a new in-app message client. Used to track the state of messages returned from the API for a particular message type.

**Params**:

<Attributes>
  <Attribute
    name="channelClient"
    type="InAppMessagesChannelClient"
    description=""
  />
  <Attribute name="messageType" type="string" description="" />
</Attributes>

**Returns**: `InAppMessagesClient`

### `fetch`

Initiates a fetch to the in-app messages API to retrieve messages, setting the result of the fetch and the returned messages in the in-app message channel client store.

**Returns**: `Promise<ApiResponse>`

### `markAs{status}`

Marks one or more messages as the provided status, optimistically updating the status in the process on the store.

**Params**:

<Attributes>
  <Attribute name="itemOrItems" type="InAppMessage | InAppMessage[]" />
</Attributes>

**Returns**: `Promise<ApiResponse>`

---

## `Preferences`

### `get`

Retrieves a preference set for the authenticated user by calling the [get preferences endpoint](/reference#get-preferences-user) directly from the client.

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Getting preferences for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const preferenceSet = await knock.preferences.get();
```

### `set`

Updates the authenticated users preferences by calling the [set preferences endpoint](/reference#set-preferences-user) directly from the client.

**Params**:

<Attributes>
  <Attribute
    name="preferenceSet"
    type="SetPreferencesProperties"
    description="The preferences to set for the current user."
  />
</Attributes>

**Returns**: `Promise<ApiResponse>`

**Example**:

```javascript title="Setting preferences for the user"
import { Knock } from "@knocklabs/client";

const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY);
knock.authenticate(user.id);

const preferenceSet = await knock.preferences.set({
  channel_types: { email: true, sms: false },
  workflows: {
    "dinosaurs-loose": {
      channel_types: { email: false, in_app_feed: true },
    },
  },
});
```

## Types

### `KnockOptions`

<Attributes>
  <Attribute
    name="host"
    type="string"
    description="A base URL to use for all API requests to Knock"
  />
  <Attribute
    name="logLevel"
    type="'debug' | null"
    description="When set to debug, will output log events"
  />
</Attributes>

### `AuthenticateOptions`

Options to pass through to the `authenticate` method.

<Attributes>
  <Attribute
    name="onUserTokenExpiring"
    type="(oldToken: string) => Promise<string | void>"
    description="A callback to provide that will fire before a user Token expires. By default will fire 30s before the token is set to expire. If a string is returned from the resolved promise, that will be used as the new user token."
  />
  <Attribute
    name="timeBeforeExpirationInMs"
    type="number"
    description="Determines the amount of time in milliseconds before the token expires that the callback should be fired."
  />
</Attributes>

### `FeedStoreState`

A **[zustand](https://github.com/pmndrs/zustand) state store** that holds the current feed state, including item counts, for easy notification feed rendering within your application. The FeedStoreState is entirely managed by the `Feed` instance, and any calls to `fetch()`, `markAsX`, or `fetchNextPage` will update the state accordingly.

<Attributes>
  <Attribute
    name="items"
    type="FeedItem[]"
    description="An ordered list of feed items to be rendered."
  />
  <Attribute
    name="pageInfo"
    type="PageInfo"
    description="The page info of the last successful fetch."
  />
  <Attribute
    name="metadata"
    type="FeedMetadata"
    description="The current feed metadata including unread, unseen, read, and total counts of items in the feed."
  />
  <Attribute
    name="loading"
    type="boolean"
    description="Whether or not the feed is currently loading."
  />
  <Attribute
    name="networkStatus"
    type="NetworkStatus"
    description="Represents the various network states the feed can be in, including differentiating between 'fetching more' and 'fetching'."
  />
</Attributes>


## iOS (Swift)

## Overview
Learn more about integrating Knock into your iOS and macOS applications through our Swift SDK.
---
title: "Knock Swift SDK (iOS and macOS)"
description: Learn more about integrating Knock into your iOS and macOS applications through our Swift SDK.
section: SDKs
---

The Knock Swift SDK is a client-side SDK for interacting with the Knock API and for building in-app notification experiences across iOS, macOS, and watchOS.

**Quick links**

- [SDK on GitHub](https://github.com/knocklabs/knock-swift)
- [Full reference guide](/sdks/ios/reference)

## Example app

You can find a complete iOS example application that uses the Swift SDK [here](https://github.com/knocklabs/ios-example-app). The app shows patterns for handling push token registration, building an in-app feed using SwiftUI, and managing user notification preferences.

## Need help?

Our Swift SDK is worked on full-time by the Knock Mobile team.

### Join the community

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/knock-swift/issues/new)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/knock-swift/pulls/new).


## Quick start
Get started with the Knock Swift SDK to build in-app notification experiences.
---
title: "Getting started with the Swift SDK"
description: Get started with the Knock Swift SDK to build in-app notification experiences.
section: SDKs
---

To get started, you will need the following:

- [A Knock Account](https://dashboard.knock.app/signup)
- A public API key for the Knock environment (which you'll use in the `publishableKey`)
- An in-app feed channel with a workflow that produces in-app feed messages (optional)
- An APNs channel with a workflow that produces push notifications (optional)

## Installation

You can install the Swift SDK in a few different ways:

- Swift Package Manager (SPM)
- Carthage
- Cocoapods

See [here](https://github.com/knocklabs/knock-swift) for more information on installation.

### Initializing a Knock instance

To initialize the shared Knock instance, you are required to use your public API key, which is identified by the prefix `pk_`. Additionally, if you opt to utilize our `KnockAppDelegate` for comprehensive device token registration and management, you must also include your `pushChannelId` during the setup process of your instance.

You should do this setup as soon as you can. Preferably within your `AppDelegate`.

```swift
import Knock

try? Knock.shared.setup(publishableKey: "your-public-key", pushChannelId: "apns-channel-id")
```

### Authenticating a user

Once you've configured the shared Knock instance with your public API key, the next step is to sign the user into Knock with their `userId`. We recommend you initiate the user sign-in process at the earliest point where the **`userId`** is known to you. This ensures that your application is ready to leverage Knock's features with the context of the signed-in user.

For interactions with your production Knock environment, you should enable [**enhanced security mode**](tps://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled) and provide a **`userToken`** to the `signIn` method. The **`userToken`** is a server-signed JWT that identifies the user making the request. This token is used to verify the authenticity of the user and is required when **enhanced security mode** is enabled.

```swift
import Knock

await Knock.shared.signIn(userId: "userid", userToken: nil)

```


## Push notifications
Usage guides to help you get started with the Push Notifications in the iOS Knock SDK.
---
title: "Handling iOS push notifications"
description: "Usage guides to help you get started with the Push Notifications in the iOS Knock SDK."
section: SDKs
---

**Note:** We Recommend taking advantage of our [KnockAppDelegate](/sdks/ios/reference#knockappdelegate) to make managing your Push Notifications simpler.

## Prerequisites

Before proceeding, ensure you've configured push notifications within your Knock account. For guidance on this initial setup, refer to our [Push Notification Configuration Guide](/integrations/push/overview).

## Step 1: Enabling Push Notifications in Your App

1. **Configure APNs in Your App:**
   - Open your project in Xcode.
   - Navigate to your app target's **Signing & Capabilities** tab.
   - Click the "+" capability button and add **Push Notifications** to enable Apple Push Notification service (APNs).
2. **Enable Background Modes:**
   - Still in the **Signing & Capabilities** tab, add the **Background Modes** capability.
   - Check **Remote notifications** to allow your app to receive silent push notifications.

## Step 2: Registering for Push Notifications

Implement the following in your AppDelegate or SceneDelegate to register for push notifications:

**KnockAppDelegate:**

If using the `KnockAppDelegate`, this will be handled for you automatically.

**Manually:**

```swift
class MyAppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        UNUserNotificationCenter.current().delegate = self
		// Will request push notification permissions, and will automatically register if perms are granted.
        Knock.shared.requestAndRegisterForPushNotifications()

        // Check if launched from the tap of a notification
        if let launchOptions = launchOptions,
           let userInfo = launchOptions[.remoteNotification] as? [String: AnyObject] {
            pushNotificationTapped(userInfo: userInfo)
        }

        return true
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Register the token with Knock
        Task {
            let channelId = await Knock.shared.getPushChannelId()

            do {
                let _ = try await Knock.shared.registerTokenForAPNS(channelId: channelId, token: Knock.convertTokenToString(token: deviceToken))
            } catch {
               // Handle error
            }
        }
    }
}
```

## Step 3: Updating the Message Status of a Push Notification.

If a push notification is sent via Knock, it will contain a `knock_message_id` property that includes the corresponding message Id. This can then be used to update the message status.

**KnockAppDelegate:**

If using the `KnockAppDelegate`, this will be handled for you automatically.

**Manually:**

```swift
class AppDelegate: UIResponder, UIApplicationDelegate {
    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        if let messageId = getMessageId(userInfo: notification.request.content.userInfo) {
            Knock.shared.updateMessageStatus(messageId: messageId, status: .seen) { _ in }
        }
        completionHandler(presentationOptions)
    }
}
```

## Step 4: Configuring Silent Push Notifications

Silent push notifications allow your app to update content in the background without alerting the user. Ensure that your Knock APNs message template has silent notifications enabled.

<Image
  src="/images/message-template-settings.png"
  alt="Message Template Settings"
  className="rounded-md mx-auto border border-gray-200"
  width={1470}
  height={1200}
/>

**KnockAppDelegate:**

```swift
 class MyAppDelegate: KnockAppDelegate {
     override func pushNotificationDeliveredSilently(userInfo: [AnyHashable : Any], completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
         // Pull any information you need out of userInfo, and change the completionHandler value depending on your needs.
         completionHandler(.noData)
     }
}
```

**Manually:**

```swift
class MyAppDelegate: UIResponder, UIApplicationDelegate {
    open func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        // Pull any information you need out of userInfo, and change the completionHandler value depending on your needs.
         completionHandler(.noData)
    }
}
```

## Full Example

Here's the complete `AppDelegate` implementation:

```swift
class AppDelegate: KnockAppDelegate {

    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Task {
            try? await Knock.shared.setup(publishableKey: Utils.publishableKey, pushChannelId: Utils.apnsChannelId, options: .init(hostname: Utils.hostname, loggingOptions: .verbose))
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    override func pushNotificationTapped(userInfo: [AnyHashable : Any]) {
        super.pushNotificationTapped(userInfo: userInfo)
        if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
            UIApplication.shared.open(url)
        }
    }

    override func pushNotificationDeliveredInForeground(notification: UNNotification) -> UNNotificationPresentationOptions {
        let options = super.pushNotificationDeliveredInForeground(notification: notification)
        // Handle push notification here
        return [options]
    }

    override func pushNotificationDeliveredSilently(userInfo: [AnyHashable : Any], completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        // Handle silent push notification here
        completionHandler(.noData)
    }
}
```

## Using FCM in iOS

If you prefer to use Firebase Cloud Messaging (FCM) within your iOS app, you can follow the same steps outlined above for push notifications with a few modifications to your `AppDelegate`.

### Step 1: Configure Firebase

In your `application(_:didFinishLaunchingWithOptions:)` method, add the following:

1. **Initialize Firebase**:

   ```swift
   FirebaseApp.configure()
   ```

2. **Set the Messaging Delegate**:

   ```swift
   Messaging.messaging().delegate = self
   ```

3. **Setup Knock**:
   ```swift
   Task {
       try? await Knock.shared.setup(
           publishableKey: Utils.publishableKey,
           pushChannelId: Utils.apnsChannelId,
           options: .init(hostname: Utils.hostname, loggingOptions: .verbose)
       )
   }
   ```

### Step 2: Override Push Notification Registration Methods

Override the `application(_:didRegisterForRemoteNotificationsWithDeviceToken:)` method to prevent the `KnockAppDelegate` from handling this automatically:

```swift
override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {}
```

### Step 3: Implement `MessagingDelegate`

Extend your `AppDelegate` to conform to `MessagingDelegate` and implement the `messaging(_:didReceiveRegistrationToken:)` method:

```swift
extension AppDelegate: MessagingDelegate {
    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        Task {
            if let channelId = await Knock.shared.getPushChannelId(), let token = fcmToken {
                let _ = try? await Knock.shared.registerTokenForAPNS(channelId: channelId, token: token)
            }
        }
    }
}
```

### Full Example

Here's the complete `AppDelegate` implementation with FCM support:

```swift
class AppDelegate: KnockAppDelegate {

    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        // Step 1: Configure Firebase and Knock
        FirebaseApp.configure()
        Messaging.messaging().delegate = self

        Task {
            try? await Knock.shared.setup(
                publishableKey: Utils.publishableKey,
                pushChannelId: Utils.apnsChannelId,
                options: .init(hostname: Utils.hostname, loggingOptions: .verbose)
            )
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    // Step 2: Override registration for remote notifications
    override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {}

    override func pushNotificationTapped(userInfo: [AnyHashable : Any]) {
        super.pushNotificationTapped(userInfo: userInfo)
        if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
            UIApplication.shared.open(url)
        }
    }

    override func pushNotificationDeliveredInForeground(notification: UNNotification) -> UNNotificationPresentationOptions {
        let options = super.pushNotificationDeliveredInForeground(notification: notification)
        return [options]
    }

    override func pushNotificationDeliveredSilently(userInfo: [AnyHashable : Any], completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        completionHandler(.noData)
    }
}

// Step 3: Implement MessagingDelegate
extension AppDelegate: MessagingDelegate {
    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        Task {
            if let channelId = await Knock.shared.getPushChannelId(), let token = fcmToken {
                let _ = try? await Knock.shared.registerTokenForAPNS(channelId: channelId, token: token)
            }
        }
    }
}
```


## Deep/universal links
Usage guides to help you get started with deep/universal linking in the iOS Knock SDK.
---
title: Handling deep/universal links
description: Usage guides to help you get started with deep/universal linking in the iOS Knock SDK.
section: SDKs
---

**Note:** We Recommend taking advantage of our [KnockAppDelegate](/sdks/ios/reference#knockappdelegate) to make handling deep links simpler.

# Deep Links:

## 1. Define URL Schemes:

- In Xcode, navigate to your app target's **Info** tab.
- Add a new URL type under **URL Types** with a unique scheme.

<Image
  src="/images/xcode-project-info.png"
  alt="Xcode Project Info"
  className="rounded-md mx-auto border border-gray-200"
  width={1020}
  height={802}
/>

## 2. Include a deep link in your Knock message payload:

- In your message payload that you send to Knock, include a property with a value of your deep link. The name of the property doesn't matter, so long as you know beforehand what it will be called.
- This can also be done in your Knock Dashboard in your [Payload overrides](/integrations/push/overview#push-overrides).

<Image
  src="/images/deep-link-payload-override.png"
  alt="Deep link payload override"
  className="rounded-md mx-auto border border-gray-200"
  width={500}
  height={507}
/>

## 3. Handle Incoming URLs:

- To handle a push notification being tapped while the app is closed:

**KnockAppDelegate:**

```swift
class MyAppDelegate: KnockAppDelegate {
     override func pushNotificationTapped(userInfo: [AnyHashable : Any]) {
         super.pushNotificationTapped(userInfo: userInfo)
         if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
             UIApplication.shared.open(url)
         }
     }
}
```

**Manually:**

```swift
class MyAppDelegate: UIResponder, UIApplicationDelegate {
     open func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
         // Check if launched from the tap of a notification
         if let launchOptions = launchOptions, let userInfo = launchOptions[.remoteNotification] as? [String: AnyObject] {
             // retrieve url
             if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
                 UIApplication.shared.open(url)
             }
         }
         return true
     }
}
```

---

- To handle a push notification being tapped while the app is in the foreground or background:

**KnockAppDelegate:**

```swift
 class MyAppDelegate: KnockAppDelegate {
     override func pushNotificationTapped(userInfo: [AnyHashable : Any]) {
         super.pushNotificationTapped(userInfo: userInfo)
         if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
             UIApplication.shared.open(url)
         }
     }
}
```

**Manually:**

```swift
class MyAppDelegate: UIResponder, UIApplicationDelegate {
     open func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
         if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
             UIApplication.shared.open(url)
         }
         completionHandler()
     }
}
```

---

# Universal Links:

## 1. Enable Associated Domains:

- Add the **Associated Domains** capability in your app target's **Signing & Capabilities** tab.
- Add your domain in the format **`applinks:yourdomain.com`**.

## 2. Handle Incoming Links:

- Implement **`application(_:continue:restorationHandler:)`** in your AppDelegate or SceneDelegate.

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
     if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
         if let incomingURL = userActivity.webpageURL {
             // Handle the incoming URL appropriately
         }
     }
     return true
 }
```

## 3. Server Configuration:

- Ensure your server hosts an Apple App Site Association (AASA) file at **`https://yourdomain.com/.well-known/apple-app-site-association`**.

For more detailed instructions on configuring universal links, visit [Apple's Official Documentation](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app).


## API reference
The complete API reference for the Knock iOS SDK.
---
title: "iOS SDK API reference"
description: The complete API reference for the Knock iOS SDK.
section: SDKs
---

In this section, you'll find the documentation for the classes and methods available in the [iOS SDK](https://github.com/knocklabs/knock-swift).

## Knock

The top-level Knock class. This is a shared instance to interact with the SDK's API methods.

### `Knock.shared.setup()`

Sets up the shared Knock instance. Make sure to call this as soon as you can. Preferably in your AppDelegate.

**Params**

<Attributes>
  <Attribute
    name="publishableKey"
    type="string*"
    description="The public API key for the Knock environment."
  />
  <Attribute
    name="pushChannelId"
    type="string (optional)"
    description="The Knock APNs channel id that you plan to use within your app."
  />
  <Attribute
    name="options"
    type="Knock.KnockStartupOptions (optional)"
    description="Optional startup options to configure your Knock instance."
  />
</Attributes>

## KnockAppDelegate

This class serves as an optional base class designed to streamline the integration of Knock into your application. By inheriting from KnockAppDelegate in your AppDelegate, you gain automatic handling of Push Notification registration and device token management, simplifying the initial setup process for Knock's functionalities.

The class also provides a set of open helper functions that are intended to facilitate the handling of different Push Notification events such as delivery in the foreground, taps, and dismissals. These helper methods offer a straightforward approach to customizing your app's response to notifications, ensuring that you can tailor the behavior to fit your specific needs.

Override any of the provided methods to achieve further customization, allowing you to control how your application processes and reacts to Push Notifications. Additionally, by leveraging this class, you ensure that your app adheres to best practices for managing device tokens and interacting with the notification system on iOS, enhancing the overall reliability and user experience of your app's notification features.

Key Features:

- Automatic registration for remote notifications, ensuring your app is promptly set up to receive and handle Push Notifications.
- Simplified device token management, with automatic storage of the device token, facilitating easier access and use in Push Notification payloads.
- Customizable notification handling through open helper functions, allowing for bespoke responses to notification events such as foreground delivery, user taps, and dismissal actions.
- Automatic message status updates, based on Push Notification interaction.

```swift
import UIKit
import Knock

class AppDelegate: KnockAppDelegate {

    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Task {
            try? await Knock.shared.setup(publishableKey: "your-publishableKey", pushChannelId: "your-apns-channel-id")
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    override func pushNotificationTapped(userInfo: [AnyHashable : Any]) {
        super.pushNotificationTapped(userInfo: userInfo)
        if let deeplink = userInfo["link"] as? String, let url = URL(string: deeplink) {
            UIApplication.shared.open(url)
        }
    }

    override func pushNotificationDeliveredInForeground(notification: UNNotification) -> UNNotificationPresentationOptions {
        let options = super.pushNotificationDeliveredInForeground(notification: notification)
        return [options]
    }

    override func pushNotificationDeliveredSilently(userInfo: [AnyHashable : Any], completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        completionHandler(.noData)
    }
}
```

## KnockInAppFeedViewModel

`KnockInAppFeedViewModel` manages the state and behavior of the in-app feed. It handles data fetching, user actions, state updates, and feed configuration.

This class is used with our [`KnockInAppFeedView`](/in-app-ui/ios/components#knockinappfeedview) component, but it can also be used independently if you would like to build your own UI.

### Properties

<Attributes>
  <Attribute
    name="feed"
    type="Knock.Feed"
    description="Holds the current feed data."
  />
  <Attribute
    name="currentTenantId"
    type="String?"
    description="Identifies the tenant associated with the current feed."
  />
  <Attribute
    name="currentFilter"
    type="InAppFeedFilter"
    description="The currently active filter for displaying feed items."
  />
  <Attribute
    name="filterOptions"
    type="[InAppFeedFilter]"
    description="Available filter options for customizing feed display."
  />
  <Attribute
    name="topButtonActions"
    type="[Knock.FeedTopActionButtonType]?"
    description="Actions available at the top of the feed interface, such as archiving or marking all as read. If set to nil, this view will be hidden."
  />
  <Attribute
    name="feedClientOptions"
    type="Knock.FeedClientOptions"
    description="Configuration options for feed."
  />
  <Attribute
    name="didTapFeedItemButtonPublisher"
    type="PassthroughSubject<String, Never>()"
    description="Publisher for feed item button tap events."
  />
  <Attribute
    name="didTapFeedItemRowPublisher"
    type="PassthroughSubject<Knock.FeedItem, Never>()"
    description="Publisher for feed item row tap events."
  />
</Attributes>

### Methods

<Attributes>
  <Attribute
    name="connectFeedAndObserveNewMessages"
    description="Connects to the feed and subscribes to new message events."
  />
  <Attribute
    name="refreshFeed(showLoadingIndicator: Bool)"
    description="Refreshes the feed using the original filter options."
  />
  <Attribute
    name="fetchNewPageOfFeedItems"
    description="Loads additional feed items when the end of the list is reached."
  />
  <Attribute
    name="isMoreContentAvailable"
    description="Determines if there are more pages of feed content that need to be fetched."
  />
  <Attribute
    name="archiveItem(_ item: Knock.FeedItem)"
    description="Archives a specific feed item."
  />
  <Attribute
    name="archiveAll(scope: Knock.FeedItemScope)"
    description="Archives all items within the specified scope."
  />
  <Attribute
    name="markAllAsRead"
    description="Marks all items in the feed as read."
  />
  <Attribute
    name="markAllAsSeen"
    description="Marks all unseen items as seen."
  />
  <Attribute
    name="markAsInteracted"
    description="Marks message as interacted. Typically used when user taps on an item."
  />
  <Attribute
    name="didSwipeRow(item: Knock.FeedItem, swipeAction: FeedNotificationRowSwipeAction)"
    description="Called when a user performs a horizontal swipe action on a row item."
  />
  <Attribute
    name="topActionButtonTapped(action: Knock.FeedTopActionButtonType)"
    description="Called when a user taps on one of the action buttons at the top of the list."
  />
</Attributes>

### Examples

```swift
@State var viewModel = Knock.InAppFeedViewModel()
let feedView = Knock.InAppFeedView().environmentObject(viewModel)
```

## Authentication

### `Knock.shared.isAuthenticated()`

Convenience method to determine if a user is currently authenticated for the Knock instance.

**Returns**: `Bool`

**Params**

<Attributes>
  <Attribute
    name="checkUserToken"
    type="Bool"
    description="Whether Knock should also check to make sure user has a user token. Only required when using a Knock prod environment."
  />
</Attributes>

### `Knock.shared.signIn()`

Sets the userId and userToken for the current Knock instance.
If the device token and pushChannelId were set previously, this will also attempt to register the token to the user that is being signed in.
This does not get the user from the database nor does it return the full User object.
You should consider using this in areas where you update your local user's state.

**Params**

<Attributes>
  <Attribute
    name="userId"
    type="String"
    description="The Knock user ID to make requests against."
  />
  <Attribute
    name="userToken"
    type="String (optional)"
    description={
      <>
        A JWT that identifies the authenticated user, signed with the private
        key provided in the Knock dashboard. Required to secure your production
        environment.{" "}
        <a
          href="https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled"
          target="_blank"
        >
          Learn more.
        </a>
      </>
    }
  />
</Attributes>

**Example**

```swift title="Signing user into Knock instance"
import Knock

await Knock.shared.signIn(userId: "your-user-id", userToken: "your-user-token")

```

### `Knock.shared.signOut()`

Sets the userId and userToken for the current Knock instance back to nil.
If the device token and pushChannelId were set previously, this will also attempt to unregister the token to the user that is being signed out so they don't receive pushes they shouldn't get.
You should call this when your user signs out

- Note: This will not clear the device token so that it can be accessed for the next user to login.

**Example**

```swift
import Knock

await Knock.shared.signOut()

```

## User Management

### `Knock.shared.getUserId()`

Fetch the userId that was set from the Knock.shared.signIn method.

**Returns**: `String?`

### `Knock.shared.getUser()`

Returns the current user's profile stored in Knock.
[https://docs.knock.app/reference#get-user#get-user](https://docs.knock.app/reference#get-user#get-user)

**Returns**: `Knock.User`

### `Knock.shared.updateUser()`

Updates the current user's profile in Knock.
[https://docs.knock.app/reference#get-user#get-user](https://docs.knock.app/reference#get-user#get-user)

**Returns**: `Knock.User`

**Params**

<Attributes>
  <Attribute
    name="user"
    type="Knock.User"
    description="The User object that you want to set for the current user."
  />
</Attributes>

## Channels/Push Notifications

### `Knock.shared.getUserChannelData()`

Returns the channel data for the current user on the channel specified with `channelId`.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to get channel data for"
  />
</Attributes>

**Returns**: `Knock.ChannelData`

### `Knock.shared.updateUserChannelData()`

Updates the channel data for the current user on the channel specified with `channelId`.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to update the channel data for"
  />
  <Attribute
    name="data"
    type="AnyEncodable"
    description="The data to update for the channel data"
  />
</Attributes>

**Returns**: `Knock.ChannelData`

### `Knock.shared.getApnsDeviceToken()`

Returns the apnsDeviceToken that was set from the Knock.shared.registerTokenForAPNS.
If you use our KnockAppDelegate, the token registration will be handled for you automatically.

**Returns** `String?`

### `Knock.shared.registerTokenForAPNS()`

Registers an Apple Push Notification Service token so that the device can receive remote push notifications.
This is a convenience method that internally gets the channel data and searches for the token. If it exists, then it's already registered and it returns.
If the data does not exists or the token is missing from the array, it's added.
If the new token differs from the last token that was used on the device, the old token will be unregistered.

You can learn more about APNs [here](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns).

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The Knock APNs channel id to associate the device token to."
  />
  <Attribute
    name="token"
    type="String OR Data"
    description="the APNs device token."
  />
</Attributes>

**Returns**: `Knock.ChannelData`

### `Knock.shared.unregisterTokenForAPNS()`

Unregisters the current deviceId associated to the user so that the device will no longer receive remote push notifications for the provided channelId.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The Knock APNs channel id to associate the device token to."
  />
  <Attribute
    name="token"
    type="String OR Data"
    description="the APNs device token."
  />
</Attributes>

**Returns**: `Knock.ChannelData`

### `Knock.shared.getNotificationPermissionStatus()`

Convenience method to determine whether or not the user is allowing Push Notifications for the app.

**Returns**: `UNAuthorizationStatus`

### `Knock.shared.requestNotificationPermission()`

Requests push notification permissions to the user.

**Params**

<Attributes>
  <Attribute
    name="options"
    type="UNAuthorizationOptions"
    description="The type of push notification permissions you want. Defaults to `[.sound, .badge, .alert]`"
  />
</Attributes>

**Returns**: `UNAuthorizationStatus`

### `Knock.shared.requestAndRegisterForPushNotifications()`

Convenience method to request Push Notification permissions for the app, and then, if successful, registerForRemoteNotifications in order to get a device token.

## Preferences

### `Knock.shared.getAllUserPreferences()`

Returns all of the preference sets for the current user.

**Returns**: `Knock.PreferenceSet`

### `Knock.shared.getUserPreferences()`

Returns a single preference set for the current user, specified by the `preferenceId`. For the default preference set, set the `preferenceId` to be `default`.

**Params**

<Attributes>
  <Attribute
    name="preferenceId"
    type="String"
    description="The ID of the preference set to retrieve"
  />
</Attributes>

**Returns**: `Knock.PreferenceSet`

### `Knock.shared.setUserPreferences()`

Updates the preference set specified by the `preferenceId` with the new `preferenceSet`.

**Params**

<Attributes>
  <Attribute
    name="preferenceId"
    type="String"
    description="The ID of the preference set"
  />
  <Attribute
    name="preferenceSet"
    type="Knock.PreferenceSet"
    description="The preferences to update for the preference set"
  />
</Attributes>

**Returns**: `Knock.PreferenceSet`

## Messages

### `Knock.shared.getMessage()`

Returns information about a single message specified by the `messageId`.
[https://docs.knock.app/reference#get-a-message](https://docs.knock.app/reference#get-a-message)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The ID of the message to retrieve"
  />
</Attributes>

**Returns** `Knock.KnockMessage`

### `Knock.shared.updateMessageStatus()`

Updates the status of a single message specified by the `message` or `messageId`.
[https://docs.knock.app/reference#undo-message-status](https://docs.knock.app/reference#undo-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The ID of the message to update"
  />
  <Attribute
    name="message"
    type="KnockMessage"
    description="A Knock message to update"
  />
  <Attribute
    name="status"
    type="KnockMessageStatusUpdateType"
    description="The status to set on the message"
  />
</Attributes>

**Returns** `Knock.KnockMessage`

### `Knock.shared.deleteMessageStatus()`

Un-marks the given status on a message specified by the `message` or `messageId`, recording an event in the process.
[https://docs.knock.app/reference#undo-message-status](https://docs.knock.app/reference#undo-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The ID of the message to update"
  />
  <Attribute
    name="message"
    type="KnockMessage"
    description="A Knock message to update"
  />
  <Attribute
    name="status"
    type="KnockMessageStatusUpdateType"
    description="The status to set on the message"
  />
</Attributes>

**Returns** `Knock.KnockMessage`

### `batchUpdateStatuses`

Updates up to 50 messages with the given status in a single request specified by `messageIds` or `messages`.
[https://docs.knock.app/reference#batch-update-message-status](https://docs.knock.app/reference#batch-update-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageIds"
    type="[String]"
    description="A list of message IDs"
  />
  <Attribute
    name="message"
    type="[Knock.KnockMessage]"
    description="A list of messages"
  />
  <Attribute
    name="status"
    type="Knock.KnockMessageStatusBatchUpdateType"
    description="The status to set on the messages"
  />
</Attributes>

**Returns** `[Knock.KnockMessage]`

## FeedManager

## `Knock.FeedManager.init()`

Creates a new instance of a `FeedManager` for interacting with a user's in-app notification feed.

**Params**

<Attributes>
  <Attribute
    name="feedId"
    type="String"
    description="The UUID of your Knock in-app feed channel ID."
  />
  <Attribute
    name="options"
    type="Knock.FeedClientOptions"
    description="Feed options to apply as defaults."
  />
</Attributes>

**Example**

```swift title="Creating a Knock.FeedManager"
import Knock

Knock.shared.feedManager = try? await Knock.FeedManager(feedId: "in-app-channel-id", options: FeedClientOptions(archived: .exclude))

```

### `Knock.shared.feedManager.connectToFeed()`

Connects the feed instance to the real-time socket so that any new items published to the feed are received over the websocket.

**Params**

<Attributes>
  <Attribute
    name="options"
    type="Knock.FeedClientOptions (optional)"
    description="Feed options to apply. Will override any options specified in the FeedManager constructor."
  />
</Attributes>

### `Knock.shared.feedManager.disconnectFromFeed()`

Disconnects a connected real-time instance.

### `Knock.shared.feedManager.on()`

Binds an event listener for incoming web socket events. Must have called `connectToFeed` first.

<Attributes>
  <Attribute
    name="eventName"
    type="String"
    description="The event name to listen for. Currently only `new-message` is supported."
  />
</Attributes>

**Example**

```swift title="Listen to incoming feed messages"
Knock.shared.feedManager.on(eventName: "new-message") { _ in
  // Do something with the new incoming feed message; likely need to refetch the feed contents
  feedManager.getUserFeedContent(options: options) { result in
      switch result {
      case .success(let feed):
          // Set the new items in the feed
      case .failure(let error):
          print(error.localizedDescription)
      }
  }
}

```

### `Knock.shared.feedManager.getUserFeedContent()`

Retrieves the user's feed content for the feed. Can be scoped by passing `options`, which also allows for paginating the contents of the feed using the `before` and `after` cursors.

**Params**

<Attributes>
  <Attribute
    name="options"
    type="Knock.FeedClientOptions*"
    description="Feed options to apply to the fetch. Will override any options specified in the FeedManager constructor."
  />
</Attributes>

**Returns** `Knock.Feed`

**Example**

```swift title="Fetching user feed content"
import Knock

knockClient = try! Knock(publishableKey: "your-pk", userId: "user-id")
feedManager = Knock.FeedManager(client: knockClient!, feedId: "in-app-channel-id")

feedManager?.getUserFeedContent() { result in
  switch result {
  case .success(let feed):
      // Do something with the returned feed
  case .failure(let error):
      print(error.localizedDescription)
  }
}

```

---

### `makeBulkStatusUpdate`

Updates all of the items within the feed with the given status. Can be passed `options` to scope the request further. Note: this method returns a `BulkUpdate` via the Knock API, which is an async operation.

**Params**

<Attributes>
  <Attribute
    name="type"
    type="Knock.BulkChannelMessageStatusUpdateType"
    description="The type of update to make in bulk."
  />
  <Attribute
    name="options"
    type="Knock.FeedClientOptions"
    description="Feed options to scope the bulk update by."
  />
</Attributes>

**Returns** `Knock.BulkOperation`

## `Knock.FeedClientOptions`

Used to scope a feed request.

**Params**

<Attributes>
  <Attribute
    name="before"
    type="String"
    description="A cursor to return records before, used for pagination"
  />
  <Attribute
    name="after"
    type="String"
    description="A cursor to return records after, used for pagination"
  />
  <Attribute
    name="page_size"
    type="Int"
    description="The maximum number of items to return per page"
  />
  <Attribute
    name="status"
    type="FeedItemScope"
    description="One of either `all`, `unread`, `read`, `unseen`, `seen`"
  />
  <Attribute
    name="source"
    type="String"
    description="Scope to a single workflow source for the feed items"
  />
  <Attribute
    name="tenant"
    type="String"
    description="Scope to a single tenant"
  />
  <Attribute
    name="has_tenant"
    type="Bool"
    description="Scope to whether the feed items have or do not have a tenant set"
  />
  <Attribute
    name="archived"
    type="FeedItemArchivedScope"
    description="Scope by archive status. One of `include`, `exclude`, or `only`"
  />
  <Attribute
    name="trigger_data"
    type="[String: AnyCodable]"
    description="Match a set of trigger data on the generated feed messages"
  />
</Attributes>


## Android (Kotlin)

## Overview
Learn more about integrating Knock into your Android applications through our Android SDK.
---
title: "Knock Android SDK"
description: Learn more about integrating Knock into your Android applications through our Android SDK.
section: SDKs
---

The Knock Kotlin SDK is a client-side SDK for interacting with the Knock API and for building notification experiences within Android applications.

**Quick links**

- [SDK on GitHub](https://github.com/knocklabs/knock-android)
- [Full reference guide](/sdks/android/reference)

## Example app

You can find a complete Android example application that uses the Knock Android SDK [here](https://github.com/knocklabs/knock-android). The app shows patterns for handling push token registration, building an in-app feed using Combine, and managing user notification preferences.

## Need help?

Our Android SDK is worked on full-time by the Knock Mobile team.

### Join the community

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/knock-android/issues/new)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/knock-android/pulls/new).


## Quick start
Get started with the Knock Android SDK to build in-app notification experiences.
---
title: "Getting started with the Android SDK"
description: Get started with the Knock Android SDK to build in-app notification experiences.
section: SDKs
---

To get started, you will need the following:

- [A Knock Account](https://dashboard.knock.app/signup)
- A public API key for the Knock environment (which you'll use in the `publishableKey`)
- An in-app feed channel with a workflow that produces in-app feed messages (optional)
- A Firebase Cloud Messaging channel with a workflow that produces push notifications (optional)

## Installation

You can install the Android SDK in a the following ways:

- Jitpack
- Manually

See [here](https://github.com/knocklabs/knock-android) for more information on installation.

### Initializing a Knock instance

To initialize the shared Knock instance, you are required to use your publishable key, which is identified by the prefix **`pk_`**. Additionally, if you opt to utilize our **`KnockMessagingService`** and **`KnockActivity`** for comprehensive device token registration and management, you must also include your **`pushChannelId`** during the setup process of your instance.

You should do this setup as soon as you can. Preferably within your **`Application`** class.

```kotlin
Knock.setup(context = "applicationContext", publishableKey = "your-pk", pushChannelId = "apns-channel-id")
```

### Authenticating a user

Once you've configured the shared Knock instance with your publishable key, the next step is to sign the user into Knock. This requires the **`userId`** and, for interactions with your production Knock environment, the **`userToken`**. For further details on **`userTokens`**, please refer to our [documentation](https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled).

We recommend you initiate the user sign-in process at the earliest point where the **`userId`** is known to you. This ensures that your application is ready to leverage Knock's features with the context of the signed-in user.

```kotlin
Knock.shared.signIn(userId = "userId", userToken = "userToken")
```


## Push notifications
Usage guides to help you get started with the Push Notifications in the Android Knock SDK.
---
title: "Handling Android push notifications"
description: "Usage guides to help you get started with the Push Notifications in the Android Knock SDK."
section: SDKs
---

**Note:** We Recommend taking advantage of our [KnockMessagingService & KnockActivity](/sdks/android/reference#knockmessagingservice--knockactivity) to make managing your Push Notifications simpler.

## Prerequisites

- Before proceeding, ensure you've configured push notifications within your Knock account. For guidance on this initial setup, refer to our [Push Notification Configuration Guide](/integrations/push/overview).
- Review Firebase's [documentation](https://firebase.google.com/docs/cloud-messaging) for advanced features and updated practices.

## 1. Create a Firebase project

- **Go to the [Firebase Console](https://console.firebase.google.com/).**
- **Click on "Add project"** and follow the on-screen instructions to create a new Firebase project.

## 2. Add your Android app to the Firebase project

- In the Firebase Console, open the project you just created.
- Click on the Android icon to add an Android app to your Firebase project.
- Enter your app's package name and a nickname for your app.
- (Optional) Enter the SHA-1 of your signing certificate.
- Download the `google-services.json` file and place it in your app's `app/` directory.

## 3. Add Firebase SDK to your project

- In your project-level `build.gradle` file, add the Google services Gradle plugin as a dependency:
  ```groovy
  buildscript {
      dependencies {
          classpath 'com.google.gms:google-services:4.3.10'
      }
  }
  ```
- In your app-level `build.gradle` file, apply the Google services plugin at the bottom of the file and add Firebase Messaging dependency:

  ```groovy
  apply plugin: 'com.android.application'

  android {
      // Your android config
  }

  dependencies {
      // Add the Firebase Messaging dependency
      implementation 'com.google.firebase:firebase-messaging:23.0.0'
  }

  // Add this line at the bottom
  apply plugin: 'com.google.gms.google-services'
  ```

## 4. Update your app's manifest

- Add the service you just created to your `AndroidManifest.xml`:
  ```xml
  <service
      android:name=".MyFirebaseMessagingService">
      <intent-filter>
          <action android:name="com.google.firebase.MESSAGING_EVENT"/>
      </intent-filter>
  </service>
  ```

## 5: Requesting user permission for push notifications

- To prompt the user to approve or deny push notification permissions call the `Knock.shared.requestNotificationPermission()` method.

  ```kotlin
  public class MainActivity {
      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)

          Knock.shared.requestNotificationPermission(this)
      }
  }
  ```

## 6. Register device token

- **KnockMessagingService:**

  - If using the `KnockMessagingService`, this will be handled for you automatically.

- **Manually:**

  ```kotlin
  class MyMessagingService: FirebaseMessagingService() {

      override fun onNewToken(token: String) {
          super.onNewToken(token)
          Knock.shared.registerTokenForFCM(channelId = YOUR_PUSH_CHANNEL_ID, token = token) { _ -> }
      }
  }
  ```

## 5. Receive push notifications

To detect when a push notification is received in the foreground:

- **KnockMessagingService:**

  ```kotlin
  class MyMessagingService: KnockMessagingService() {
    override fun fcmRemoteMessageReceived(message: RemoteMessage) {
        super.fcmRemoteMessageReceived(message)

        // This is just an example of how you could present a notification with the app in the foreground.
        // You should customize this to fit your own app's needs.
        message.presentNotification(
            context = this,
            handlingClass = MainActivity::class.java,
            icon = android.R.drawable.ic_dialog_info
        )
    }
  }
  ```

- **Manually:**

  ```kotlin
  class MyMessagingService: FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)

        // This is just an example of how you could present a notification with the app in the foreground.
        // You should customize this to fit your own app's needs.
        message.presentNotification(
            context = this,
            handlingClass = MainActivity::class.java,
            icon = android.R.drawable.ic_dialog_info
        )
    }
  }
  ```

## 8. Handling push notification taps

- **KnockMessagingService:**

  ```kotlin
  class MainActivity: KnockActivity() {
    override fun onKnockPushNotificationTappedInBackground(intent: Intent) {
        super.onKnockPushNotificationTappedInBackground(intent)

        // Perform any action here
    }

    override fun onKnockPushNotificationTappedInForeground(message: RemoteMessage) {
        super.onKnockPushNotificationTappedInForeground(message)

        // Perform any action here
    }
  }
  ```

- **Manually:**

  ```kotlin
  class MainActivity: AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // See if there is a pending tap event from a PushNotification
        checkForPushNotificationTap(intent)
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)

        // See if there is a pending tap event from a PushNotification
        checkForPushNotificationTap(intent)
    }

    fun checkForPushNotificationTap(intent: Intent?) {
        intent?.extras?.getString(Knock.KNOCK_MESSAGE_ID_KEY)?.let {
            Knock.shared.updateMessageStatus(it, KnockMessageStatusUpdateType.INTERACTED) {}

            // Push notification tapped in background

        } ?: (intent?.extras?.get(Knock.KNOCK_PENDING_NOTIFICATION_KEY) as? RemoteMessage)?.let { message ->
            // Clear the intent extra
            intent.extras?.remove(Knock.KNOCK_PENDING_NOTIFICATION_KEY)
            message.data[Knock.KNOCK_MESSAGE_ID_KEY]?.let {
                Knock.shared.updateMessageStatus(it, KnockMessageStatusUpdateType.INTERACTED) {}
            }

            // Push notification tapped in foreground
        }
    }
  }
  ```


## Deep links
Usage guides to help you get started with deep linking in the Android Knock SDK.
---
title: Handling deep links
description: Usage guides to help you get started with deep linking in the Android Knock SDK.
section: SDKs
---

**Note:** We Recommend taking advantage of our [KnockMessagingService & KnockActivity](/sdks/android/reference#knockmessagingservice--knockactivity) to make handling deep links simpler.

## 1. Define URL Schemes:

- In Xcode, navigate to your app target's **Info** tab.
- Add a new URL type under **URL Types** with a unique scheme.

<Image
  src="/images/xcode-project-info.png"
  alt="Xcode Project Info"
  className="rounded-md mx-auto border border-gray-200"
  width={1020}
  height={802}
/>

## 2. Include a deep link in your Knock message payload:

- In your message payload that you send to Knock, include a property with a value of your deep link. The name of the property doesn't matter, so long as you know beforehand what it will be called.
- This can also be done in your Knock Dashboard in your [payload overrides](/integrations/push/firebase#using-overrides-to-customize-notifications).

```json title="FCM payload override configuration"
{
  "data": {
    "link": "https://example.com/deep-link"
  }
}
```

## 3. Handle Incoming URLs:

```kotlin title="Example for handling deep links"
class MainActivity: KnockActivity() {
  override fun onKnockPushNotificationTappedInBackGround(intent: Intent) {
    super.onKnockPushNotificationTappedInBackGround(intent)

    intent?.extras?.getString("link")?.let { deepLink ->
        // Handle your deep link routing here
    }
  }

  override fun onKnockPushNotificationTappedInForeground(message: RemoteMessage) {
      super.onKnockPushNotificationTappedInForeground(message)

      remoteMessage.data.isNotEmpty().let {
          val deepLink = remoteMessage.data["link"]
          deepLink?.let {
            // Handle your deep link routing here
          }
      }
  }
}
```


## API reference
The complete API reference for the Knock Android SDK.
---
title: "Android API reference"
description: The complete API reference for the Knock Android SDK.
section: SDKs
---

In this section, you'll find the documentation for the classes and methods available in the [Android SDK](https://github.com/knocklabs/knock-android).

## Knock

The top-level Knock class. This is a shared instance to interact with the SDK's API methods.

### `Knock.shared.setup()`

Sets up the shared Knock instance. Make sure to call this as soon as you can. Preferably in your AppDelegate.

**Params**

<Attributes>
  <Attribute
    name="publishableKey"
    type="String"
    description="The public API key for the Knock environment."
  />
  <Attribute
    name="pushChannelId"
    type="String (optional)"
    description="The Knock APNs channel id that you plan to use within your app."
  />
  <Attribute
    name="options"
    type="KnockStartupOptions (optional)"
    description="Optional startup options to configure your Knock instance."
  />
</Attributes>

## KnockMessagingService & KnockActivity

These classes serves as optional base classes designed to streamline the integration of Knock into your application. By inheriting from KnockMessagingService in your FirebaseMessagingService class and the KnockActivity in your MainActivity class, you gain automatic handling of FCM Push Notification registration and device token management, simplifying the initial setup process for Knock's functionalities.

These classes also provide a set of open helper functions that are intended to facilitate the handling of different Push Notification events such as delivery in the foreground and taps. These helper methods offer a straightforward approach to customizing your app's response to notifications, ensuring that you can tailor the behavior to fit your specific needs.

Override any of the provided methods to achieve further customization, allowing you to control how your application processes and reacts to Push Notifications. Additionally, by leveraging this class, you ensure that your app adheres to best practices for managing device tokens and interacting with the notification system on Android, enhancing the overall reliability and user experience of your app's notification features.

Key Features:

- Automatic registration for remote notifications, ensuring your app is promptly set up to receive and handle Push Notifications.
- Simplified device token management, with automatic storage of the device token, facilitating easier access and use in Push Notification payloads.
- Customizable notification handling through open helper functions, allowing for bespoke responses to notification events such as foreground delivery, and user taps.
- Automatic message status updates, based on Push Notification interaction.

```kotlin title="Example KnockMessagingService"
class ExampleMessagingService: KnockMessagingService() {
    override fun messageReceivedInForeground(message: RemoteMessage) {
        super.messageReceivedInForeground(message)

        // This is just an example of how you could present a notification with the app in the foreground.
        // You should customize this to fit your own app's needs.
        message.presentNotification(
            context = this,
            handlingClass = MainActivity::class.java,
            icon = android.R.drawable.ic_dialog_info
        )
    }
}
```

---

```kotlin title="Example KnockActivity"
class MainActivity : KnockComponentActivity() {
    override fun onKnockPushNotificationTappedInBackGround(intent: Intent) {
        super.onKnockPushNotificationTappedInBackGround(intent)
        Log.d(Utils.loggingTag, "tapped in background")
    }

    override fun onKnockPushNotificationTappedInForeground(message: RemoteMessage) {
        super.onKnockPushNotificationTappedInForeground(message)
        Log.d(Utils.loggingTag, "tapped in foreground")
    }
}
```

## Authentication

### `Knock.shared.isAuthenticated()`

Convienience method to determine if a user is currently authenticated for the Knock instance.

**Returns**: `Bool`

**Params**

<Attributes>
  <Attribute
    name="checkUserToken"
    type="Bool"
    description="Whether Knock should also check to make sure user has a user token. Only required when using a Knock prod environment."
  />
</Attributes>

### `Knock.shared.signIn()`

Sets the userId and userToken for the current Knock instance.
If the device token and pushChannelId were set previously, this will also attempt to register the token to the user that is being signed in.
This does not get the user from the database nor does it return the full User object.
You should consider using this in areas where you update your local user's state.

**Params**

<Attributes>
  <Attribute
    name="userId"
    type="String"
    description="The Knock user ID to make requests against."
  />
  <Attribute
    name="userToken"
    type="String (optional)"
    description={
      <>
        A JWT that identifies the authenticated user, signed with the private
        key provided in the Knock dashboard. Required to secure your production
        environment.{" "}
        <a
          href="https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled"
          target="_blank"
        >
          Learn more.
        </a>
      </>
    }
  />
</Attributes>

**Example**

```kotlin title="Signing user into Knock instance"
import Knock

await Knock.shared.signIn(userId: "your-user-id", userToken: "your-user-token")

```

### `Knock.shared.signOut()`

Sets the userId and userToken for the current Knock instance back to nil.
If the device token and pushChannelId were set previously, this will also attempt to unregister the token to the user that is being signed out so they don't receive pushes they shouldn't get.
You should call this when your user signs out

**Example**

```swift
import Knock

await Knock.shared.signOut()

```

## User Management

### `Knock.shared.getUserId()`

Fetch the userId that was set from the Knock.shared.signIn method.

**Returns**: `String?`

### `Knock.shared.getUser()`

Returns the current user's profile stored in Knock.
[https://docs.knock.app/reference#get-user#get-user](https://docs.knock.app/reference#get-user#get-user)

**Returns**: `KnockUser`

### `Knock.shared.updateUser()`

Updates the current user's profile in Knock.
[https://docs.knock.app/reference#get-user#get-user](https://docs.knock.app/reference#get-user#get-user)

**Returns**: `KnockUser`

**Params**

<Attributes>
  <Attribute
    name="user"
    type="KnockUser"
    description="The User object that you want to set for the current user."
  />
</Attributes>

## Channels/Push Notifications

### `Knock.shared.getUserChannelData()`

Returns the channel data for the current user on the channel specified with `channelId`.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to get channel data for"
  />
</Attributes>

**Returns**: `ChannelData`

### `Knock.shared.updateUserChannelData()`

Updates the channel data for the current user on the channel specified with `channelId`.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to update the channel data for"
  />
  <Attribute
    name="data"
    type="AnyEncodable"
    description="The data to update for the channel data"
  />
</Attributes>

**Returns**: `ChannelData`

### `Knock.shared.getCurrentDeviceToken()`

Returns the FCM device token that was set from the Knock.shared.registerTokenForAPNS.
If you use our KnockMessagingService, the token registration will be handled for you automatically.

**Returns** `String?`

### `Knock.shared.registerTokenForFCM()`

Registers an FCM token so that the device can receive remote push notifications.
This is a convenience method that internally gets the channel data and searches for the token. If it exists, then it's already registered and it returns.
If the data does not exists or the token is missing from the array, it's added.
If the new token differs from the last token that was used on the device, the old token will be unregistered.

You can learn more about FCM [here](https://firebase.google.com/docs/cloud-messaging/android/client).

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The Knock FCM channel id to associate the device token to."
  />
  <Attribute
    name="token"
    type="String OR Data"
    description="the FCM device token."
  />
</Attributes>

**Returns**: `ChannelData`

### `Knock.shared.unregisterTokenForAPNS()`

Unregisters the current deviceId associated to the user so that the device will no longer receive remote push notifications for the provided channelId.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The Knock FCM channel id to associate the device token to."
  />
  <Attribute
    name="token"
    type="String OR Data"
    description="the FCM device token."
  />
</Attributes>

**Returns**: `ChannelData`

### `Knock.shared.isPushPermissionGranted()`

Convenience method to determine whether or not the user is allowing Push Notifications for the app.

**Returns**: `Boolean`

### `Knock.shared.requestNotificationPermission()`

Requests push notification permissions to the user.

**Params**

<Attributes>
  <Attribute
    name="requestCode"
    type="Int"
    description="Application specific request code to match with a result reported to. Default is `1`."
  />
</Attributes>

## Preferences

### `Knock.shared.getAllUserPreferences()`

Returns all of the preference sets for the current user.

**Returns**: `PreferenceSet`

### `Knock.shared.getUserPreferences()`

Returns a single preference set for the current user, specified by the `preferenceId`. For the default preference set, set the `preferenceId` to be `default`.

**Params**

<Attributes>
  <Attribute
    name="preferenceId"
    type="String"
    description="The ID of the preference set to retrieve"
  />
</Attributes>

**Returns**: `PreferenceSet`

### `Knock.shared.setUserPreferences()`

Updates the preference set specified by the `preferenceId` with the new `preferenceSet`.

**Params**

<Attributes>
  <Attribute
    name="preferenceId"
    type="String"
    description="The ID of the preference set"
  />
  <Attribute
    name="preferenceSet"
    type="PreferenceSet"
    description="The preferences to update for the preference set"
  />
</Attributes>

**Returns**: `PreferenceSet`

## Messages

### `Knock.shared.getMessage()`

Returns information about a single message specified by the `messageId`.
[https://docs.knock.app/reference#get-a-message](https://docs.knock.app/reference#get-a-message)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The ID of the message to retrieve"
  />
</Attributes>

**Returns** `KnockMessage`

### `Knock.shared.updateMessageStatus()`

Updates the status of a single message specified by the `message` or `messageId`.
[https://docs.knock.app/reference#undo-message-status](https://docs.knock.app/reference#undo-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The ID of the message to update"
  />
  <Attribute
    name="message"
    type="KnockMessage"
    description="A Knock message to update"
  />
  <Attribute
    name="status"
    type="KnockMessageStatusUpdateType"
    description="The status to set on the message"
  />
</Attributes>

**Returns** `KnockMessage`

### `Knock.shared.deleteMessageStatus()`

Un-marks the given status on a message specified by the `message` or `messageId`, recording an event in the process.
[https://docs.knock.app/reference#undo-message-status](https://docs.knock.app/reference#undo-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageId"
    type="String"
    description="The id of the message to update"
  />
  <Attribute
    name="message"
    type="KnockMessage"
    description="A Knock message to update"
  />
  <Attribute
    name="status"
    type="KnockMessageStatusUpdateType"
    description="The status to set on the message"
  />
</Attributes>

**Returns** `KnockMessage`

### `batchUpdateStatuses`

Updates up to 50 messages with the given status in a single request specified by `messageIds` or `messages`.
[https://docs.knock.app/reference#batch-update-message-status](https://docs.knock.app/reference#batch-update-message-status)

**Params**

<Attributes>
  <Attribute
    name="messageIds"
    type="[String]"
    description="A list of message IDs"
  />
  <Attribute
    name="status"
    type="KnockMessageStatusUpdateType"
    description="The status to set on the messages"
  />
</Attributes>

**Returns** `[KnockMessage]`

## FeedManager

## `Knock.FeedManager.init()`

Creates a new instance of a `FeedManager` for interacting with a user's in-app notification feed.

**Params**

<Attributes>
  <Attribute
    name="feedId"
    type="String"
    description="The UUID of your Knock in-app feed channel ID."
  />
  <Attribute
    name="options"
    type="FeedClientOptions"
    description="Feed options to apply as defaults."
  />
</Attributes>

### `Knock.shared.feedManager.connectToFeed()`

Connects the feed instance to the real-time socket so that any new items published to the feed are received over the websocket.

**Params**

<Attributes>
  <Attribute
    name="options"
    type="FeedClientOptions (optional)"
    description="Feed options to apply. Will override any options specified in the FeedManager constructor."
  />
</Attributes>

### `Knock.shared.feedManager.disconnectFromFeed()`

Disconnects a connected real-time instance.

### `Knock.shared.feedManager.on()`

Binds an event listener for incoming web socket events. Must have called `connectToFeed` first.

<Attributes>
  <Attribute
    name="eventName"
    type="String"
    description="The event name to listen for. Currently only `new-message` is supported."
  />
</Attributes>

**Example**

```kotlin
Knock.shared.feedManager?.on("new-message") {
    viewModelScope.launch {
        val feedOptions = FeedClientOptions(before = feed.value?.pageInfo?.before)
        val result = withContext(Dispatchers.IO) {
            Knock.shared.feedManager?.getUserFeedContent(feedOptions)
        }
        result?.let { feedResult ->
            _feed.value?.let { currentFeed ->
                val updatedEntries = feedResult.entries + (currentFeed.entries)
                _feed.value = currentFeed.copy(entries = updatedEntries)
            }
            _feed.value?.let {
                it.meta.unseenCount = feedResult.meta.unseenCount
                it.meta.unreadCount = feedResult.meta.unreadCount
                it.meta.totalCount = feedResult.meta.totalCount
                it.pageInfo.before = feedResult.entries.firstOrNull()?.feedCursor
            }
        }
    }
}

```

### `Knock.shared.feedManager.getUserFeedContent()`

Retrieves the user's feed content for the feed. Can be scoped by passing `options`, which also allows for paginating the contents of the feed using the `before` and `after` cursors.

**Params**

<Attributes>
  <Attribute
    name="options"
    type="FeedClientOptions (optional)"
    description="Feed options to apply to the fetch. Will override any options specified in the FeedManager constructor."
  />
</Attributes>

**Returns** `Feed`

### `Knock.shared.feedManager.makeBulkStatusUpdate()`

Updates all of the items within the feed with the given status. Can be passed `options` to scope the request further. Note: this method returns a `BulkUpdate` via the Knock API, which is an async operation.

**Params**

<Attributes>
  <Attribute
    name="type"
    type="KnockMessageStatusUpdateType"
    description="The type of update to make in bulk."
  />
  <Attribute
    name="options"
    type="FeedClientOptions (optional)"
    description="Feed options to scope the bulk update by."
  />
</Attributes>

**Returns** `BulkOperation`

## `FeedClientOptions`

Used to scope a feed request.

**Params**

<Attributes>
  <Attribute
    name="before"
    type="String (optional)"
    description="A cursor to return records before, used for pagination"
  />
  <Attribute
    name="after"
    type="String (optional)"
    description="A cursor to return records after, used for pagination"
  />
  <Attribute
    name="page_size"
    type="Int (optional)"
    description="The maximum number of items to return per page"
  />
  <Attribute
    name="status"
    type="FeedItemScope (optional)"
    description="One of either `all`, `unread`, `read`, `unseen`, `seen`"
  />
  <Attribute
    name="source"
    type="String (optional)"
    description="Scope to a single workflow source for the feed items"
  />
  <Attribute
    name="tenant"
    type="String (optional)"
    description="Scope to a single tenant"
  />
  <Attribute
    name="has_tenant"
    type="Boolean (optional)"
    description="Scope to whether the feed items have or do not have a tenant set"
  />
  <Attribute
    name="archived"
    type="FeedItemArchivedScope (optional)"
    description="Scope by archive status. One of `include`, `exclude`, or `only`"
  />
  <Attribute
    name="trigger_data"
    type="Map<String, Any> (optional)"
    description="Match a set of trigger data on the generated feed messages"
  />
</Attributes>


## Flutter

## Overview
Learn more about integrating Knock into your Flutter applications.
---
title: "Knock Flutter SDK"
description: Learn more about integrating Knock into your Flutter applications.
section: SDKs
tags: ["flutter", "dart"]
---

Our [`knock_flutter`](https://pub.dev/packages/knock_flutter) library lets you create in-app notification experiences in Flutter applications using Knock's client APIs.

**Quick links:**

- [`knock_flutter` on pub.dev](https://pub.dev/packages/knock_flutter)
- [Example application using the Flutter SDK](https://github.com/knocklabs/knock-flutter/tree/main/example)
- [Full reference](/sdks/flutter/reference)
- [GitHub repository](https://github.com/knocklabs/knock-flutter)

Using the Flutter SDK it's possible to:

- Integrate push notifications
- Build in-app experiences, like feeds that update in real-time
- Create notification preference control centers

## Need help?

Our Flutter library is worked on full-time by the Knock Mobile team.

### Join the community

Ask questions and find answers on the following platforms:

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/knock-flutter/pulls/new).


## Quick start
Get started with the Knock Flutter SDK to build in-app notification experiences.
---
title: "Getting started with the Flutter SDK"
description: Get started with the Knock Flutter SDK to build in-app notification experiences.
section: SDKs
---

The Knock Flutter SDK is a client-side SDK for interacting with the Knock API and for building in-app notification experiences for Flutter applications. In this guide, we'll show some of the main ways you can interact with the SDK.

## Quick links

- [SDK on GitHub](https://github.com/knocklabs/knock-flutter)
- [Full reference guide](/sdks/flutter/reference)
- [Example application](https://github.com/knocklabs/knock-flutter/tree/main/example)

## Installation

You can find `knock_flutter` on [pub.dev](https://pub.dev/packages/knock_flutter).

```bash
flutter pub add knock_flutter
```

## Setup the SDK

```dart
import 'package:knock_flutter/knock_flutter.dart';

late Knock knock = Knock(const String.fromEnvironment("KNOCK_API_KEY"));
knock.authenticate("your-user-id");
```


## API reference
The complete API reference for the Knock Flutter SDK.
---
title: "Flutter API reference"
description: The complete API reference for the Knock Flutter SDK.
section: SDKs
---

In this section, you'll find the documentation for the classes and methods available in the [Flutter SDK](https://github.com/knocklabs/knock-flutter).

## `Knock`

The top-level Knock class. Create an authenticated Knock client instance for interacting with Knock.

**Params**

<Attributes>
  <Attribute
    name="apiKey"
    type="String*"
    description="The public API key for the Knock environment."
  />
  <Attribute
    name="options"
    type="KnockOptions"
    description="Any additional options to instantiate your Knock instance with"
  />
</Attributes>

**Returns**

`Knock`

### `authenticate`

Authenticates the current user.

**Params**

<Attributes>
  <Attribute
    name="userId"
    type="String*"
    description="The ID of the user to authenticate against."
  />
  <Attribute
    name="userToken"
    type="String"
    description="The signed user token, required when using enhanced security mode in the environment."
  />
</Attributes>

**Returns**

`void`

### `logout`

Clears any user authentication and disposes of any created clients.

**Returns**

`void`

### `isAuthenticated`

Returns whether or this Knock instance is authenticated. Passing `true` will check the presence of the `userToken` as well.

**Returns**

`bool`

### `dispose`

Releases any connected resources used by this instance.

**Returns**

`void`

### `getApnsToken`

Returns the current device's APNs token. Only relevant for iOS applications.

**Returns**

`Future<String>`

### `getFcmToken`

Returns the current device's FCM token.

**Returns**

`Future<String>`

### `user`

Returns the current user client.

**Returns**

`UserClient`

### `preferences`

Returns the current preferences client.

**Returns**

`PreferencesClient`

### `feed`

Returns a new feed client for the channel ID specified.

**Params**

<Attributes>
  <Attribute
    name="feedChannelId"
    type="String*"
    description="The channel ID from Knock for the in-app feed"
  />
  <Attribute
    name="options"
    type="FeedOptions"
    description="Any additional options to instantiate your feed instance with"
  />
</Attributes>

**Returns**

`FeedClient`

---

## `UserClient`

Methods for interacting with the current user resource in Knock. You access this under `knock.user()`.

### `get`

Returns the current authenticated user from Knock.

**Returns**

`Future<User>`

### `identify`

Upserts the current authenticated user properties in Knock.

**Returns**

`Future<User>`

### `getChannelData`

Returns any channel data set for the channelId given for the current authenticated user.

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID from Knock"
  />
</Attributes>

**Returns**

`Future<ChannelData>`

### `setChannelData`

Updates the channel data for the current user on the channel specified with `channelId`.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The channel ID to update the channel data for"
  />
  <Attribute
    name="data"
    type="Any"
    description="The data to update for the channel data"
  />
</Attributes>

**Returns**

`Future<ChannelData>`

### `registerTokenForChannel`

Registers the current device's token for the user in Knock.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The push channel ID from Knock"
  />
  <Attribute
    name="token"
    type="String"
    description="The device token to register"
  />
</Attributes>

**Returns**

`Future<ChannelData>`

### `deregisterTokenForChannel`

De-registers the current device's token for the user in Knock.

**Params**

<Attributes>
  <Attribute
    name="channelId"
    type="String"
    description="The push channel ID from Knock"
  />
  <Attribute
    name="token"
    type="String"
    description="The device token to remove"
  />
</Attributes>

**Returns**

`Future<ChannelData>`

---

## `PreferencesClient`

### `getAll`

Returns all preference sets for the current user.

**Returns**

`Future<List<PreferenceSet>>`

### `get`

Returns a single preference set for the current user.

**Returns**

`Future<PreferenceSet>`

### `set`

<Attributes>
  <Attribute
    name="properties"
    type="SetPreferencesProperties"
    description="The preference set to upsert"
  />
</Attributes>

**Returns**

`Future<PreferenceSet>`

---

## `FeedClient`

<Attributes>
  <Attribute
    name="feedChannelId"
    type="String"
    description="The in-app channel ID from Knock"
  />
  <Attribute
    name="options"
    type="FeedOptions"
    description="Default options to apply to the feed instance"
  />
</Attributes>

**Returns**

`FeedClient`

### `feed`

Returns the current feed controller to be bound and used when building UI.

**Returns**

`Stream<Feed>`

### `fetchNextPage`

Fetches the next page of items in the feed, as long as there are more items to fetch.

**Returns**

`void`

### `on`

Binds an event listener to the feed.

**Params**

<Attributes>
  <Attribute
    name="bindableFeedEvent"
    type="BindableFeedEvent"
    description="The type of event to listen to"
  />
</Attributes>

**Returns**

`Stream<FeedEvent>`

### `markAsSeen`

Marks the given set of items as seen. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsUnseen`

Marks the given set of items as unseen. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsRead`

Marks the given set of items as read. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsUnread`

Marks the given set of items as unread. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsArchived`

Marks the given set of items as archived. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsUnarchived`

Marks the given set of items as unarchived. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAsInteracted`

Marks the given set of items as interacted. Will optimistically update the feed.

**Params**

<Attributes>
  <Attribute
    name="items"
    type="List<FeedItem>"
    description="One or more feed items to mark"
  />
</Attributes>

**Returns**

`Future<void>`

### `markAllAsSeen`

Marks all items in the user's feed as seen. Will optimistically update the items currently in the feed.

**Returns**

`Future<void>`

### `markAllAsRead`

Marks all items in the user's feed as read. Will optimistically update the items currently in the feed.

**Returns**

`Future<void>`

### `markAllAsArchived`

Marks all items in the user's feed as archived. Will optimistically update the items currently in the feed.

**Returns**

`Future<void>`


## React Native

## Overview
Learn more about integrating Knock into your React Native applications through our React Native SDKs.
---
title: "Knock React Native SDK"
description: Learn more about integrating Knock into your React Native applications through our React Native SDKs.
section: SDKs
tags: ["expo", "rn", "react native"]
---

Our [`@knocklabs/react-native`](https://www.npmjs.com/package/@knocklabs/react-native) library lets you create in-app notification experiences in React Native powered applications using Knock's client APIs.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Using Expo?</strong> See our{" "}
      <a href="/sdks/expo/overview">Expo SDK</a>. Our React Native SDK is meant
      for use with React Native apps that are not built with a framework such as
      Expo.
    </>
  }
/>

The React Native library is built on top of the `@knocklabs/client` JS SDK and includes that library as an implicit dependency. Internally, our React Native SDK is tested with React Native v0.73.4, but it should work with all recent versions of React Native. If you encounter issues with React Native compatibility, please [reach out to our support team](mailto:support@knock.app).

**Quick links:**

- [`@knocklabs/react-native` on npm](https://www.npmjs.com/package/@knocklabs/react-native)
- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [React Native SDK reference](/sdks/react-native/reference)
- [Javascript SDK reference](/sdks/javascript/reference)

Using the React Native SDK it's possible to build:

- [Notification feeds](/in-app-ui/react-native/notification-feeds) that update in real time
- Notification preference control centers
- Push notification management

## Example app

You can find a basic example application that uses the React Native SDK [here](https://github.com/knocklabs/javascript/tree/main/examples/react-native-example). The app shows patterns for handling push token registration, building an in-app feed, and managing user notification preferences.

## Need help?

Our React Native SDK is worked on full-time by the Knock JavaScript team.

### Join the community

Ask questions and find answers on the following platforms:

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/javascript/issues/new)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/javascript/pulls/new).


## Quick start
Get started with the Knock React Native SDK to build in-app notification experiences.
---
title: "Getting started with the Knock React Native SDK"
description: Get started with the Knock React Native SDK to build in-app notification experiences.
section: SDKs
---

To get started, you will need the following:

- [A Knock account](https://dashboard.knock.app/signup)
- A public API key for the Knock environment (which you'll use in the `publishableKey`)
- An in-app feed channel with a workflow that produces in-app feed messages (optional)

## Installation

- Via NPM: `npm install @knocklabs/react-native`
- Via Yarn: `yarn add @knocklabs/react-native`

<Callout
  emoji="💡"
  text={
    <>
      <strong>Using Expo?</strong> Install <code>@knocklabs/expo</code> instead
      to use our <a href="/sdks/expo/overview">Expo SDK</a>.
    </>
  }
/>

### Configuration

To configure the feed you will need:

1. A public API key (found in the Knock dashboard)
2. A user ID and an auth token

   <Callout
     emoji="💡"
     text={
       <>
         Auth tokens are strongly recommended for production environments and
         are required when enhanced security mode is enabled. For more
         information, see our{" "}
         <a href="/in-app-ui/security-and-authentication#authentication-with-enhanced-security">
           Security & Authentication documentation
         </a>
         .
       </>
     }
   />

3. If integrating an in-app feed, a feed channel ID (found in the Knock dashboard)

### Usage

You can integrate the feed into your app as follows:

```typescript
import {
  KnockProvider,
  KnockFeedProvider,
  NotificationFeed,
} from "@knocklabs/react-native";

const YourAppLayout = () => {
  return (
    <KnockProvider apiKey={process.env.KNOCK_PUBLIC_API_KEY} userId={userId}>
      {/* Optionally, use the KnockFeedProvider to connect an in-app feed */}
      <KnockFeedProvider feedId={process.env.KNOCK_FEED_ID}>
        <NotificationFeed
          onRowTap={(item) => {
            console.log("Notification tapped:", item);
          }}
        />
      </KnockFeedProvider>
    </KnockProvider>
  );
};
```

### Headless usage

Alternatively, if you don't want to use our components you can render the feed in a headless mode using our hooks:

```typescript
import {
  useAuthenticatedKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/react-native";

const YourAppLayout = () => {
  const knockClient = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    currentUser.id,
  );

  const notificationFeed = useNotifications(
    knockClient,
    process.env.KNOCK_FEED_ID,
  );

  const { metadata } = useNotificationStore(notificationFeed);

  useEffect(() => {
    notificationFeed.fetch();
  }, [notificationFeed]);

  return <Text>Total unread: {metadata.unread_count}</Text>;
};
```


## Push notifications
A guide on integrating FCM push notifications with the Knock SDK in your React Native application.
---
title: "Handling Push Notifications with React Native and Firebase Cloud Messaging"
description: A guide on integrating FCM push notifications with the Knock SDK in your React Native application.
section: SDKs
---

<Callout
  emoji="💡"
  text={
    <>
      <strong>Using Expo?</strong> See our{" "}
      <a href="/sdks/expo/push-notifications">
        guide to handling push notifications using our Expo SDK
      </a>
      .
    </>
  }
/>

<Steps titleSize="h2">

<Step title="Set up a Firebase Cloud Messaging channel in Knock">

If you haven't already, create a new Firebase Cloud Messaging channel in the **Integrations** page of your Knock dashboard. Follow our [Firebase Cloud Messaging push notification guide](/integrations/push/firebase) to configure FCM with Knock using your Service Account JSON file.

</Step>

<Step title="Set up React Native Firebase">

The simplest way to get started with FCM in your React Native app is to use <a href="https://rnfirebase.io/" target="_blank">React Native Firebase</a>, which simplifies the process of handling push notifications and device tokens. Follow their Getting Started guide to set up React Native Firebase in your project.

</Step>

<Step title="Add KnockPushNotificationProvider to your app">

Ensure your app is wrapped with both `KnockProvider` and `KnockPushNotificationProvider`.

```tsx
import React from "react";
import { View } from "react-native";
import {
  KnockProvider,
  KnockPushNotificationProvider,
} from "@knocklabs/react-native";

export default function App() {
  return (
    <KnockProvider apiKey="{YOUR_KNOCK_PUBLIC_API_KEY}" userId="{YOUR_USER_ID}">
      <KnockPushNotificationProvider>
        <View> {/* Your app content here */} </View>
      </KnockPushNotificationProvider>
    </KnockProvider>
  );
}
```

</Step>

<Step title="Request permissions">

Depending upon the platforms supported by your app, you may need to request permissions to receive push notifications on the user's device. See React Native Firebase's documentation on <a href="https://rnfirebase.io/messaging/usage#android---requesting-permissions" target="_blank">how to request permissions on Android</a> and <a href="https://rnfirebase.io/messaging/usage#ios---requesting-permissions" target="_blank">how to request permissions on iOS</a>. Alternatively, consider using a third-party library such as <a href="https://github.com/zoontek/react-native-permissions" target="_blank">react-native-permissions</a>.

</Step>

<Step title="Register for push notifications">

When your app launches, retrieve the device token using <a href="https://rnfirebase.io/reference/messaging#getToken" target="_blank">React Native Firebase's `getToken` function</a>. Pass this token to the `registerPushTokenToChannel` function provided by Knock's [`usePushNotifications` hook](/sdks/react-native/reference#usepushnotifications) and include the channel ID of your FCM channel.

Additionally, when your app is in the foreground, register a listener using <a href="https://rnfirebase.io/reference/messaging#onTokenRefresh" target="_blank">`onTokenRefresh`</a> and invoke `registerPushTokenToChannel` whenever the token is refreshed.

```tsx
import { Text } from "react-native";
import { usePushNotifications } from "@knocklabs/react-native";
import messaging from "@react-native-firebase/messaging";

const MyComponent = () => {
  const { registerPushTokenToChannel } = usePushNotifications();

  useEffect(() => {
    messaging()
      .getToken()
      .then((token) =>
        registerPushTokenToChannel(token, "{YOUR_KNOCK_FCM_CHANNEL_ID}"),
      )
      .catch(console.error);

    const unsubscribe = messaging().onTokenRefresh((token) =>
      registerPushTokenToChannel(token, "{YOUR_KNOCK_FCM_CHANNEL_ID}").catch(
        console.error,
      ),
    );
    return unsubscribe;
  }, [registerPushTokenToChannel]);

  return <Text>Hello, world!</Text>;
};
```

</Step>

<Step title="Handle incoming push notifications">

Listen for push notifications using React Native Firebase's <a href="https://rnfirebase.io/reference/messaging#getInitialNotification" target="_blank">`getInitialNotification`</a> and <a href="https://rnfirebase.io/reference/messaging#onNotificationOpenedApp" target="_blank">`onNotificationOpenedApp`</a> functions. See <a href="https://rnfirebase.io/messaging/notifications#handling-interaction" target="_blank">React Native Firebase's Notifications guide</a> for more details on these two functions.

```tsx
useEffect(() => {
  messaging()
    .getInitialNotification()
    .then((remoteMessage) => {
      if (remoteMessage) {
        console.log("App opened via notification from quit state");
      }
    })
    .catch(console.error);

  const unsubscribe = messaging().onNotificationOpenedApp(() => {
    console.log("App opened via notification while in the background");
  });

  return unsubscribe;
}, []);
```

</Step>

<Step title="Send a test notification">

Use the Knock dashboard or API to send a test notification to ensure your setup is correct. Verify that the notification appears on your device and that tapping on it triggers the expected behavior.

</Step>

</Steps>

## Troubleshooting

<Callout
  emoji="💡"
  text={
    <>
      Check out our{" "}
      <a
        href="https://github.com/knocklabs/javascript/tree/main/examples/react-native-example"
        target="_blank"
      >
        React Native example app
      </a>{" "}
      to see a fully working example of how to integrate push notifications with
      Knock, Firebase Cloud Messaging, and React Native Firebase.
    </>
  }
/>

- **Not Receiving Notifications:** Ensure your FCM device token is correctly registered with Knock and that your device's notification settings allow push notifications from your app.
- **Handling Silent Notifications:** If implementing silent notifications, ensure that your notification payload is correctly configured to not display an alert or sound.

For further assistance, [reach out to our support team](mailto:support@knock.app).


## API reference
Complete API reference for the Knock React Native SDK.
---
title: "React Native API reference"
description: Complete API reference for the Knock React Native SDK.
tags: ["mark as read"]
section: SDKs
---

In this section, you'll find the complete documentation for the components exposed in `@knocklabs/react-native`, including the props available.

**Note**: You can see a reference for the methods available for the `Knock` class, as well as a `Feed` instance under the [client JS docs](/sdks/javascript/reference).

## Components

### `KnockProvider`

The top-level provider that connects to Knock with the given API key and authenticates a user.

#### Props

Accepts `KnockProviderProps`

<Attributes>
  <Attribute
    name="apiKey*"
    type="string"
    description="The public API key for the environment"
  />
  <Attribute
    name="userId*"
    type="string"
    description="The ID of the user for which to retrieve a feed"
  />
  <Attribute
    name="userToken"
    type="string"
    description={
      <span>
        A JWT that identifies the authenticated user, signed with the private
        key provided in the Knock dashboard. Required to secure your production
        environment.{" "}
        <a
          href="https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security"
          target="_blank"
        >
          Learn more.
        </a>
      </span>
    }
  />
  <Attribute
    name="host"
    type="string"
    description="A custom API host for Knock"
  />
  <Attribute
    name="i18n"
    type="I18nContent"
    description="An optional set of translations to override the default `en` translations used in the feed components"
  />
</Attributes>

### `KnockFeedProvider`

The feed-specific provider that connects to a feed for that user. Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockFeedProviderProps`:

<Attributes>
  <Attribute
    name="feedId*"
    type="string"
    description="The channel ID of the in-app feed to be displayed"
  />
  <Attribute
    name="defaultFeedOptions"
    type="FeedClientOptions"
    description="Set defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queries"
  />
  <Attribute
    name="colorMode"
    type="ColorMode"
    description="Sets the theme as either light or dark mode (defaults to light)"
  />
</Attributes>

### `KnockPushNotificationProvider`

A context provider designed to streamline the integration of push notifications within your React Native application.
It facilitates the registration of device push tokens with the Knock backend, enabling the delivery of notifications.

It is recommended to use the [`usePushNotifications`](#usepushnotifications) hook to interact with this context provider.

**Note:** Must be a child of the `KnockProvider`.

#### Props

None other than `children`.

## Hooks

### `useKnock`

The `KnockProvider` exposes a `useKnock` hook for all child components.

**Returns**: `Knock`, an instance of the Knock JS client.

**Example**:

```jsx
import { KnockProvider, useKnock } from "@knocklabs/react";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <MyComponent />
  </KnockProvider>
);

const MyComponent = () => {
  const knock = useKnock();

  return null;
};
```

### `useKnockFeed`

The `KnockFeedProvider` exposes a `useKnockFeed` hook for all child components.

**Returns**: `KnockFeedProviderState`

<Attributes>
  <Attribute
    name="knock"
    type="Knock"
    description="The instance of the Knock client"
  />
  <Attribute
    name="feedClient"
    type="Feed"
    description="The instance of the authenticated Feed"
  />
  <Attribute
    name="useFeedStore"
    type="UseStore<FeedStoreState>"
    description="A zustand store containing the FeedStoreState"
  />
  <Attribute
    name="status"
    type="FilterStatus"
    description="Current value of the filter status for the Feed"
  />
  <Attribute
    name="setStatus"
    type="function"
    description="A function to set the current FilterStatus"
  />
  <Attribute
    name="colorMode"
    type="ColorMode"
    description="The current theme color"
  />
</Attributes>

**Example**:

```jsx
import {
  KnockProvider,
  KnockFeedProvider,
  useKnockFeed,
} from "@knocklabs/react-native";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
      <MyFeedComponent />
    </KnockFeedProvider>
  </KnockProvider>
);

const MyFeedComponent = () => {
  const { useFeedStore } = useKnockFeed();
  const items = useFeedStore((state) => state.items);

  return (
    <View>
      {items.map((item) => (
        <NotificationCell key={item.id} item={item} />
      ))}
    </View>
  );
};
```

### `useAuthenticatedKnockClient`

Creates an authenticated Knock client.

**Returns**: `Knock` instance, authenticated against the user

**Example**:

```jsx
import { useAuthenticatedKnockClient } from "@knocklabs/react-native";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  return null;
};
```

### `useNotifications`

Creates a `Feed` instance for the provided `Knock` client which creates a stateful, real-time connection to Knock to build in-app experiences.

**Returns**: `Feed` instance

**Example**:

```js
import {
  useAuthenticatedKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/react-native";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  const notificationFeed = useNotifications(
    knock,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { metadata } = useNotificationStore(notificationFeed);

  useEffect(() => {
    notificationFeed.fetch();
  }, [notificationFeed]);

  return (
    <View>
      <Text>Total unread: {metadata.unread_count}</Text>
    </View>
  );
};
```

### `useTranslations`

Exposed under `KnockI18nProvider` child components.

**Returns**:

<Attributes>
  <Attribute
    name="locale"
    type="string"
    description="The current locale code (defaults to `en`)"
  />
  <Attribute
    name="t"
    type="(key: string) => string"
    description="A helper function to get the value of a translation from the current `Translations`."
  />
</Attributes>

### `usePushNotifications`

The `KnockPushNotificationProvider` exposes a `usePushNotifications` hook for all child components, enabling them to register and unregister a device's push token from a channel.

**Returns**: `KnockPushNotificationContextType`

<Attributes>
  <Attribute
    name="registerPushTokenToChannel"
    type="(token: string, channelId: string) => Promise<void>"
    description="Registers the device's push token with a specific channel in the Knock backend."
  />
  <Attribute
    name="unregisterPushTokenFromChannel"
    type="(token: string, channelId: string) => Promise<void>"
    description="Removes the device's push token from a specific channel in the Knock backend."
  />
</Attributes>

**Example**:

```jsx
import React, { useEffect } from "react";
import { View, Text } from "react-native";
import {
  KnockPushNotificationProvider,
  usePushNotifications,
} from "@knocklabs/react-native";

const App = () => (
  <KnockPushNotificationProvider>
    <MyComponent />
  </KnockPushNotificationProvider>
);

const MyComponent = () => {
  // How the push token is retrieved depends upon the push notification service you are using
  const pushToken = getPushTokenForCurrentDevice();
  const { registerPushTokenToChannel } = usePushNotifications();

  useEffect(() => {
    registerPushTokenToChannel(pushToken, process.env.KNOCK_PUSH_CHANNEL_ID)
      .then(() => console.log("Push token registered"))
      .catch(console.error);
  }, [registerPushTokenToChannel, pushToken]);

  return (
    <View>
      <Text>Push Token: {pushToken}</Text>
    </View>
  );
};
```

## Types

### `I18nContent`

Used to set translations available in the child components exposed under `KnockFeedProvider` and `KnockSlackProvider`. Used in the `useTranslations` hook.

**Note:** `locale` must be a valid locale code.

```typescript
interface Translations {
  readonly emptyFeedTitle: string;
  readonly emptyFeedBody: string;
  readonly notifications: string;
  readonly poweredBy: string;
  readonly markAllAsRead: string;
  readonly archiveNotification: string;
  readonly all: string;
  readonly unread: string;
  readonly read: string;
  readonly unseen: string;

  readonly slackConnectChannel: string;
  readonly slackChannelId: string;
  readonly slackConnecting: string;
  readonly slackDisconnecting: string;
  readonly slackConnect: string;
  readonly slackConnected: string;
  readonly slackConnectContainerDescription: string;
  readonly slackSearchbarDisconnected: string;
  readonly slackSearchbarNoChannelsConnected: string;
  readonly slackSearchbarNoChannelsFound: string;
  readonly slackSearchbarChannelsError: string;
  readonly slackSearchChannels: string;
  readonly slackConnectionErrorOccurred: string;
  readonly slackConnectionErrorExists: string;
  readonly slackChannelAlreadyConnected: string;
  readonly slackError: string;
  readonly slackDisconnect: string;
  readonly slackChannelSetError: string;
  readonly slackAccessTokenNotSet: string;
  readonly slackReconnect: string;
}

interface I18nContent {
  readonly translations: Partial<Translations>;
  readonly locale: string;
}
```


## Expo

## Overview
Learn more about integrating Knock into your Expo applications through our Expo SDK.
---
title: "Knock Expo SDK"
description: Learn more about integrating Knock into your Expo applications through our Expo SDK.
section: SDKs
tags: ["expo", "rn", "react native"]
---

Our [`@knocklabs/expo`](https://www.npmjs.com/package/@knocklabs/expo) library lets you create in-app notification experiences using Knock's client APIs in applications built with React Native and Expo.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Not using Expo?</strong> See our{" "}
      <a href="/sdks/react-native/overview">React Native SDK</a>. Our Expo SDK
      is only meant for use with React Native apps that are built with Expo.
    </>
  }
/>

The Expo library is built on top of the `@knocklabs/client` JS SDK and includes that library as an implicit dependency.

**Quick links:**

- [`@knocklabs/expo` on npm](https://www.npmjs.com/package/@knocklabs/expo)
- [`@knocklabs/client` on npm](https://www.npmjs.com/package/@knocklabs/client)
- [Expo SDK reference](/sdks/expo/reference)
- [Javascript SDK reference](/sdks/javascript/reference)

Using the Expo SDK it's possible to build:

- [Notification feeds](/in-app-ui/react-native/notification-feeds) that update in real time
- Notification preference control centers
- Push notification management

## Example app

Our [Expo SDK example app](https://github.com/knocklabs/javascript/tree/main/examples/expo-example) shows patterns for handling push token registration, building an in-app feed, and managing user notification preferences.

## Need help?

Our Expo SDK is worked on full-time by the Knock JavaScript team.

### Join the community

Ask questions and find answers on the following platforms:

- [Knock community Slack](https://knock.app/join-slack)

### Provide feedback

- [Open an issue](https://github.com/knocklabs/javascript/issues/new)
- Use the "Help" dropdown at the top of this page to contact support.

### Contributing

All contributors are welcome, from casual to regular. Feel free to open a [pull request](https://github.com/knocklabs/javascript/pulls/new).


## Push notifications
A guide on integrating Expo push notifications with the Knock SDK in your React Native application.
---
title: "Handling Push Notifications with React Native and Expo"
description: A guide on integrating Expo push notifications with the Knock SDK in your React Native application.
section: SDKs
---

**Note:** This guide assumes you're utilizing our `KnockExpoPushNotificationProvider` for a streamlined push notification setup within your React Native and Expo environment.

## Prerequisites

Before diving into the integration process, ensure your Knock account is set up for push notifications. For initial setup instructions, please visit our [Push Notification Configuration Guide](/integrations/push/overview).

<Steps titleSize="h2">

<Step title="Setting Up Push Notifications with Expo">

1. **Create a Push Notification Channel in Knock:**

   - Log in to your Knock account and navigate to the **Integrations** > **Channels** section of the dashboard.
   - Create a new channel with type `Expo Push Notifications` and note the channel ID.

2. **Install Expo Dependencies:**
   - `expo": "~50.0.14`
   - `expo-constants": "^15.4.0`
   - `expo-device": "^5.9.3`
   - `expo-notifications": "^0.27.6`

</Step>

<Step title="Registering for Push Notifications">

1. **Wrap Your App with `KnockExpoPushNotificationProvider`:**
   - Ensure your app is wrapped with `KnockProvider` and then `KnockExpoPushNotificationProvider`, passing the Expo channel ID from Knock.

```jsx
import React from "react";
import { View } from "react-native";
import {
  KnockProvider,
  KnockExpoPushNotificationProvider,
} from "@knocklabs/expo";

export default function App() {
  return (
    <KnockProvider apiKey="{YOUR_KNOCK_PUBLIC_API_KEY}" userId="{YOUR_USER_ID}">
      <KnockExpoPushNotificationProvider knockExpoChannelId="{YOUR_KNOCK_EXPO_CHANNEL_ID}">
        <View> {/* Your app content here */} </View>
      </KnockExpoPushNotificationProvider>
    </KnockProvider>
  );
}
```

2. **Initiate Registration in Your Component:**
   - The `KnockExpoPushNotificationProvider` automatically registers for push notifications.
   - If you want to manually register, utilize the `useExpoPushNotifications` hook:

```jsx
import React, { useEffect } from "react";
import { Text } from "react-native";
import { useExpoPushNotifications } from "@knocklabs/expo";

const MyComponent = () => {
  const { expoPushToken, registerForPushNotifications } =
    useExpoPushNotifications();

  useEffect(() => {
    registerForPushNotifications();
  }, []);

  return <Text>Your Expo Push Token: {expoPushToken}</Text>;
};
```

</Step>

<Step title="Handling Incoming Push Notifications">

The `KnockExpoPushNotificationProvider` automatically handles receiving and tapping on notifications. To customize this behavior:

1. **Custom Notification Handling:**
   - Use the `onNotificationReceived` and `onNotificationTapped` methods from the `useExpoPushNotifications` hook to set custom handlers.

```jsx
useEffect(() => {
  onNotificationReceived((notification) => {
    console.log("Notification received:", notification);
  });

  onNotificationTapped((response) => {
    console.log("Notification tapped:", response);
  });
}, []);
```

</Step>

<Step title="Sending Test Notifications">

Use the Knock dashboard or API to send a test notification to ensure your setup is correct. Verify that the notification appears on your device and that tapping on it triggers the expected behavior.

</Step>

</Steps>

## Troubleshooting

- **Not Receiving Notifications:** Ensure your Expo push token is correctly registered with Knock and that your device's notification settings allow push notifications from your app.
- **Handling Silent Notifications:** If implementing silent notifications, ensure that your notification payload is correctly configured to not display an alert or sound.

For further assistance, [reach out to our support team](mailto:support@knock.app).


## API reference
Complete API reference for the Knock Expo SDK.
---
title: "Expo SDK API reference"
description: Complete API reference for the Knock Expo SDK.
tags: ["sdk"]
section: SDKs
---

In this section, you'll find the complete documentation for the components exposed in `@knocklabs/expo`, including the props available.

**Note**: You can see a reference for the methods available for the `Knock` class, as well as a `Feed` instance under the [client JS docs](/sdks/javascript/reference).

## Components

### `KnockProvider`

The top-level provider that connects to Knock with the given API key and authenticates a user.

#### Props

Accepts `KnockProviderProps`

<Attributes>
  <Attribute
    name="apiKey*"
    type="string"
    description="The public API key for the environment"
  />
  <Attribute
    name="userId*"
    type="string"
    description="The ID of the user for which to retrieve a feed"
  />
  <Attribute
    name="userToken"
    type="string"
    description={
      <span>
        A JWT that identifies the authenticated user, signed with the private
        key provided in the Knock dashboard. Required to secure your production
        environment.{" "}
        <a
          href="https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security"
          target="_blank"
        >
          Learn more.
        </a>
      </span>
    }
  />
  <Attribute
    name="host"
    type="string"
    description="A custom API host for Knock"
  />
  <Attribute
    name="i18n"
    type="I18nContent"
    description="An optional set of translations to override the default `en` translations used in the feed components"
  />
</Attributes>

### `KnockFeedProvider`

The feed-specific provider that connects to a feed for that user. Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockFeedProviderProps`:

<Attributes>
  <Attribute
    name="feedId*"
    type="string"
    description="The channel ID of the in-app feed to be displayed"
  />
  <Attribute
    name="defaultFeedOptions"
    type="FeedClientOptions"
    description="Set defaults for `tenant`, `has_tenant`, `source`, `archived` to scope all subsequent feed queries"
  />
  <Attribute
    name="colorMode"
    type="ColorMode"
    description="Sets the theme as either light or dark mode (defaults to light)"
  />
</Attributes>

### `KnockExpoPushNotificationProvider`

A context provider designed to streamline the integration of Expo push notifications within your React Native application.
It facilitates the registration of device push tokens with the Knock backend, enabling the delivery of notifications.
Moreover, this provider empowers developers to define custom behavior for handling notifications when they are received or interacted with, either by tapping or performing another action.
By default, it provides a basic notification handling strategy, but it also allows for custom logic to be easily implemented according to specific application needs.

**Note:** Must be a child of the `KnockProvider`.

#### Props

Accepts `KnockExpoPushNotificationProviderProps`:

<Attributes>
  <Attribute
    name="knockExpoChannelId*"
    type="string"
    description="The channel ID of your Expo channel from Knock."
  />
  <Attribute
    name="customNotificationHandler"
    type="Promise<Notifications.NotificationBehavior>"
    description="Allows developers to define custom behavior for handling notifications, including whether to show alerts, play sounds, or set badge counts"
  />
  <Attribute
    name="autoRegister"
    type="boolean"
    description="When true, the Expo provider automatically retrieves a push token from Expo and stores it as channel data on the user."
  />
</Attributes>

## Hooks

### `useKnock`

The `KnockProvider` exposes a `useKnock` hook for all child components.

**Returns**: `Knock`, an instance of the Knock JS client.

**Example**:

```jsx
import { KnockProvider, useKnock } from "@knocklabs/react";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <MyComponent />
  </KnockProvider>
);

const MyComponent = () => {
  const knock = useKnock();

  return null;
};
```

### `useKnockFeed`

The `KnockFeedProvider` exposes a `useKnockFeed` hook for all child components.

**Returns**: `KnockFeedProviderState`

<Attributes>
  <Attribute
    name="knock"
    type="Knock"
    description="The instance of the Knock client"
  />
  <Attribute
    name="feedClient"
    type="Feed"
    description="The instance of the authenticated Feed"
  />
  <Attribute
    name="useFeedStore"
    type="UseStore<FeedStoreState>"
    description="A zustand store containing the FeedStoreState"
  />
  <Attribute
    name="status"
    type="FilterStatus"
    description="Current value of the filter status for the Feed"
  />
  <Attribute
    name="setStatus"
    type="function"
    description="A function to set the current FilterStatus"
  />
  <Attribute
    name="colorMode"
    type="ColorMode"
    description="The current theme color"
  />
</Attributes>

**Example**:

```jsx
import {
  KnockProvider,
  KnockFeedProvider,
  useKnockFeed,
} from "@knocklabs/expo";

const App = ({ authenticatedUser }) => (
  <KnockProvider
    apiKey={process.env.KNOCK_PUBLIC_API_KEY}
    userId={authenticatedUser.id}
  >
    <KnockFeedProvider feedId={process.env.KNOCK_FEED_CHANNEL_ID}>
      <MyFeedComponent />
    </KnockFeedProvider>
  </KnockProvider>
);

const MyFeedComponent = () => {
  const { useFeedStore } = useKnockFeed();
  const items = useFeedStore((state) => state.items);

  return (
    <View>
      {items.map((item) => (
        <NotificationCell key={item.id} item={item} />
      ))}
    </View>
  );
};
```

### `useAuthenticatedKnockClient`

Creates an authenticated Knock client.

**Returns**: `Knock` instance, authenticated against the user

**Example**:

```jsx
import { useAuthenticatedKnockClient } from "@knocklabs/expo";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  return null;
};
```

### `useNotifications`

Creates a `Feed` instance for the provided `Knock` client which creates a stateful, real-time connection to Knock to build in-app experiences.

**Returns**: `Feed` instance

**Example**:

```js
import {
  useAuthenticatedKnockClient,
  useNotifications,
  useNotificationStore,
} from "@knocklabs/expo";

const MyComponent = () => {
  const knock = useAuthenticatedKnockClient(
    process.env.KNOCK_PUBLIC_API_KEY,
    user.id,
    user.knockToken,
  );

  const notificationFeed = useNotifications(
    knock,
    process.env.KNOCK_FEED_CHANNEL_ID,
  );

  const { metadata } = useNotificationStore(notificationFeed);

  useEffect(() => {
    notificationFeed.fetch();
  }, [notificationFeed]);

  return (
    <View>
      <Text>Total unread: {metadata.unread_count}</Text>
    </View>
  );
};
```

### `useTranslations`

Exposed under `KnockI18nProvider` child components.

**Returns**:

<Attributes>
  <Attribute
    name="locale"
    type="string"
    description="The current locale code (defaults to `en`)"
  />
  <Attribute
    name="t"
    type="(key: string) => string"
    description="A helper function to get the value of a translation from the current `Translations`."
  />
</Attributes>

### `useExpoPushNotifications`

The `KnockExpoPushNotificationProvider` exposes a `useExpoPushNotifications` hook for all child components, enabling them to interact with push notification functionalities and state.

**Returns**: `KnockExpoPushNotificationContextType`

<Attributes>
  <Attribute
    name="expoPushToken"
    type="string | null"
    description="The Expo push token for the current device."
  />
  <Attribute
    name="registerForPushNotifications"
    type="() => Promise<void>"
    description="A function to initiate the push notification registration process."
  />
  <Attribute
    name="registerPushTokenToChannel"
    type="(token: string, channelId: string) => Promise<void>"
    description="Registers the device's push token with a specific channel in the Knock backend."
  />
  <Attribute
    name="unregisterPushTokenFromChannel"
    type="(token: string, channelId: string) => Promise<void>"
    description="Removes the device's push token from a specific channel in the Knock backend."
  />
  <Attribute
    name="onNotificationReceived"
    type="(handler: (notification: Notifications.Notification) => void) => void"
    description="Sets a custom handler for notifications received while the app is in the foreground."
  />
  <Attribute
    name="onNotificationTapped"
    type="(handler: (response: Notifications.NotificationResponse) => void) => void"
    description="Sets a custom handler for user interactions with notifications."
  />
</Attributes>

**Example**:

```jsx
import React, { useEffect } from "react";
import { View, Text } from "react-native";
import {
  KnockExpoPushNotificationProvider,
  useExpoPushNotifications,
} from "@knocklabs/expo";

const App = () => (
  <KnockExpoPushNotificationProvider knockExpoChannelId="{YOUR_CHANNEL_ID}">
    <MyComponent />
  </KnockExpoPushNotificationProvider>
);

const MyComponent = () => {
  const { expoPushToken, onNotificationReceived, onNotificationTapped } =
    useExpoPushNotifications();

  useEffect(() => {
    onNotificationReceived((notification) => {
      console.log("Notification Received: ", notification);
    });

    onNotificationTapped((response) => {
      console.log("Notification Tapped: ", response);
    });
  }, []);

  return (
    <View>
      <Text>Expo Push Token: {expoPushToken}</Text>
    </View>
  );
};
```

## Types

### `I18nContent`

Used to set translations available in the child components exposed under `KnockFeedProvider` and `KnockSlackProvider`. Used in the `useTranslations` hook.

**Note:** `locale` must be a valid locale code.

```typescript
interface Translations {
  readonly emptyFeedTitle: string;
  readonly emptyFeedBody: string;
  readonly notifications: string;
  readonly poweredBy: string;
  readonly markAllAsRead: string;
  readonly archiveNotification: string;
  readonly all: string;
  readonly unread: string;
  readonly read: string;
  readonly unseen: string;

  readonly slackConnectChannel: string;
  readonly slackChannelId: string;
  readonly slackConnecting: string;
  readonly slackDisconnecting: string;
  readonly slackConnect: string;
  readonly slackConnected: string;
  readonly slackConnectContainerDescription: string;
  readonly slackSearchbarDisconnected: string;
  readonly slackSearchbarNoChannelsConnected: string;
  readonly slackSearchbarNoChannelsFound: string;
  readonly slackSearchbarChannelsError: string;
  readonly slackSearchChannels: string;
  readonly slackConnectionErrorOccurred: string;
  readonly slackConnectionErrorExists: string;
  readonly slackChannelAlreadyConnected: string;
  readonly slackError: string;
  readonly slackDisconnect: string;
  readonly slackChannelSetError: string;
  readonly slackAccessTokenNotSet: string;
  readonly slackReconnect: string;
}

interface I18nContent {
  readonly translations: Partial<Translations>;
  readonly locale: string;
}
```



# Manage your account
Learn more about the tools available in managing your Knock account.

## Authentication methods
Learn more about the authentication methods available to members on your Knock account.
---
title: Authentication methods
description: Learn more about the authentication methods available to members on your Knock account.
tags: ["auth", "login", "sso", "security"]
section: Manage your account
---

Understand and select your preferred authentication method in Knock.

## Overview

We support three methods of authenticating users to get access to the Knock dashboard: email based passwordless authentication, Google SSO, and SAML 2.0 SSO.

## Email (passwordless)

With this authentication method users will receive an email to authenticate themselves in order to access the Knock dashboard. The email contains a "magic link" that expires after 5 minutes of being generated. Clicking the link will authenticate the user and grant access to the Knock dashboard.

## Google SSO

Users can authenticate using their Google account to access their Knock account. Google SSO works for both personal and organizations using Google Workspace (formerly G Suite).

## SAML 2.0 SSO

Users can authenticate with their chosen corporate identity provider (i.e. Okta) to access their Knock account.

Once SSO is enabled for an account, all members are redirected through that identity provider's authentication flow. Moving forward, they must pass through SSO to access their Knock account.

**Note**: SAML 2.0 SSO is only available to **Enterprise** plan customers. Enabling SAML 2.0 SSO will force all members of your account on a matching domain to authenticate via your identity provider.


## SAML SSO
How to configure SAML SSO on your account.
---
title: SAML SSO
description: How to configure SAML SSO on your account.
tags: ["authentication", "SAML", "SSO"]
section: Manage your account
---

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> SAML SSO is
      only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan.</a>
    </>
  }
/>

## SSO configuration

To configure SAML SSO, an **account owner** will need to complete the following steps:

1. Log in to your Knock dashboard
2. Navigate to **Settings** > **Security**
3. In the Security section, locate the "Single Sign-On (SSO)" panel
4. Click on the "Connect SSO provider" button to begin the configuration process. This will launch our SAML SSO configuration wizard where you can select and configure your identity provider.

<figure>
  <Image
    src="/images/manage-your-account/sso-configuration.png"
    width={500}
    height={514}
    className="rounded-md mx-auto border border-gray-200"
    alt="SAML SSO configuration wizard"
  />
  <figcaption>SAML SSO configuration wizard</figcaption>
</figure>
After completing the steps of the configuration walkthrough, SAML will be successfully
configured for your account. This will allow users with emails under your domain
to be able to log in successfully through the provider you have configured.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Domains.</span> Self-service SAML SSO
      configuration will allow users to authenticate using emails under the same
      domain as your own. If your setup requires support for more than one
      domain, contact support.
    </>
  }
/>

## SSO authentication

Once SAML SSO is configured on your account, all members will be required to log in using the provider you
configured. When visiting the login screen, users must use the email field to start the authentication flow.
Users will **not be allowed to authenticate** using other authentication methods while SAML SSO is enabled on your account.


## Directory sync (SCIM)
How to configure directory sync on your account to automate the management of users and their permissions from your identity management platform to Knock.
---
title: Directory sync (SCIM)
description: How to configure directory sync on your account to automate the management of users and their permissions from your identity management platform to Knock.
tags: ["authentication", "directory sync", "SCIM", "ULM"]
section: Manage your account
---

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Directory sync
      is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan.</a>
    </>
  }
/>

## Overview

Directory sync allows you to automatically provision users and manage their permissions in Knock by leveraging the identity provider your organization is using (e.g. Okta) as the single source for user and group information.

Once configured, it enables automated syncing of user identity information from identity providers to Knock using SCIM (System for Cross-domain Identity Management), an open standard for managing automated user and group provisioning.

Any users that are assigned in the Knock application in your identity provider will be created in Knock (or vice versa), with their roles and permissions automatically configured based on their group memberships (see the default group to [role mapping](/manage-your-account/directory-sync#group-to-role-mapping) for more details).

## Directory sync configuration

To set up directory sync for your account:

1. Contact the [Knock support team](mailto:support@knock.app).
2. Our team will provide you with a customized link to guide you through the Directory Sync setup process for your specific identity provider.
3. Follow the step-by-step instructions in the guide provided at the link in order to complete the configuration.

We support many common identity providers. For detailed, provider-specific setup guides, please refer to the following:

- [CyberArk](https://workos.com/docs/integrations/cyberark-scim/2-select-or-create-your-cyberark-application)
- [Entra ID (formerly Azure AD)](https://workos.com/docs/integrations/entra-id-scim/2-select-or-create-your-azure-application)
- [JumpCloud](https://workos.com/docs/integrations/jumpcloud-scim/2-select-or-create-your-jumpcloud-application)
- [Okta](https://workos.com/docs/integrations/okta-scim/2-select-or-create-your-okta-application)
- [OneLogin](https://workos.com/docs/integrations/onelogin-scim/2-select-or-create-your-onelogin-application)
- [PingFederate](https://workos.com/docs/integrations/pingfederate-scim/2-install-the-scim-connector-in-pingfederate)
- [Rippling](https://workos.com/docs/integrations/rippling-scim/2-create-your-rippling-application)

Once the setup is complete and user data starts syncing from your identity provider to Knock, you'll see a "connected" status for directory sync under **Settings** > **General** in your Knock dashboard

## Group-to-role mapping

You can optionally supply a set of group-to-role mappings for your organization. For instance, you might want to always map the "Team Admins" group to the `admin` role within Knock. You must supply this mapping to the Knock support team to set on your account as there is currently no way to self-service this information.

In the case where you want to force a group to a particular role within your IDP, you can use the following group names to automatically allocate the roles to users in that group.

| Group name         | Role    |
| ------------------ | ------- |
| knock-role-owner   | owner   |
| knock-role-admin   | admin   |
| knock-role-member  | member  |
| knock-role-billing | billing |
| knock-role-support | support |

## How Knock assigns roles

If a user does not belong to any group, Knock will assign the **support** role to the user. If a user belongs to more than one of these groups, then Knock will assign the **highest privileged role available** to that user. See [roles and permissions](/manage-your-account/roles-and-permissions) for more details.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What happens to existing users when directory sync is enabled?">
    Knock will identify existing users based on their email, and update (i.e. overwrite) their access and roles based on the user data synced from your identity provider.

    Any users that exist in Knock but not in identity providers will retain access to Knock and retain its role originally assigned to them.

  </Accordion>
  <Accordion title="What happens to existing users when directory sync gets disabled?">
    If directory sync connection becomes disabled, all users and roles will be left in the state at the time of disconnection and stop syncing from your identity provider.
  </Accordion>
  <Accordion title="Can I use a custom group to role mapping for assigning roles in Knock?">
    Yes, please contact the [Knock support team](mailto:support@knock.app) to configure a custom mapping. Note, however, you cannot override Knock's default role mapping.
  </Accordion>
  <Accordion title="Can I continue to invite users to Knock from the Knock dashboard once directory sync is enabled?">
    Yes, you can still invite users to Knock from the Knock dashboard, but keep in mind that users created via directory sync will take precedence. This means if you invite a user who is managed via directory sync, the user's role will be updated to reflect the state of your identity provider. Once you enable directory sync, Knock uses your identity provider as the source-of-truth for any users synced via SCIM. 
  </Accordion>
</AccordionGroup>


## Managing members
How to invite, manage, and remove members on your account.
---
title: Managing account members
description: How to invite, manage, and remove members on your account.
tags:
  [
    "team",
    "team members",
    "account members",
    "invites",
    "inviting",
    "auto join",
    "auto-join",
  ]
section: Manage your account
---

Learn how to invite, manage, and remove members on your Knock account.

## Overview

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> only account owners and admins
      can view, manage, and invite new members to your account.
    </>
  }
/>

You can manage the members of your account under **Settings** > **Members** in your Knock dashboard:

<Image
  src="/images/manage-your-account/account-members.png"
  alt="Managing account members in the dashboard"
  width={2626}
  height={1751}
  className="rounded-md border border-gray-200"
/>

## Invite members to your account

You can invite new members to your account by selecting the "New member" button on the members page.

Members are always invited via their email address and must be assigned [a role](/manage-your-account/roles-and-permissions). Optionally a message can be supplied that will appear in the invitation email they are sent.

The member will be sent a reminder email if the invite is not accepted within 3 days. Account invites are valid for 2 weeks, after which they'll expire.

<figure>
  <Image
    src="/images/manage-your-account/account-invite-email.png"
    width={1327}
    height={949}
    alt="A Knock invite email"
  />
  <figcaption>
    An example invitation email inviting a user to a Knock account
  </figcaption>
</figure>

### Manage pending invites

Once a user has been invited to your Knock account you will see their invitation as a "pending invite" until they accept to join the account. Pending invitations for users can be revoked which will mark the invite as invalid and expire it immediately.

Once you revoke an invitation for a user, you can reinvite them if needed which will generate a new invite for your account.

## Enabling auto-join for your account

You can enable auto-join on your account to let users that belong to your domain automatically join your account when signing up for Knock. This is helpful
for cases where people from your organization might sign up for Knock on their own without realizing there's already an account they should be working within.

You can enable auto-join under **Settings** > **Security** in your dashboard.

<Image
  src="/images/manage-your-account/auto-join-settings.png"
  alt="Auto-join settings"
  width={2628}
  height={1737}
  className="rounded-md border border-gray-200"
/>

When you enable auto-join for your account, you'll need to select which domains
can auto-join your account. For security reasons, we only let you select non-public domains that belong to the owners of your account.
This means that you cannot enable auto-join for public domains (such as gmail.com). Additionally, before you can add a new domain to auto-join, someone with an email address from that domain must have an [owner role](/manage-your-account/roles-and-permissions) on your account.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Note:</span> All users that join through
      auto-join will receive the <code>member</code> role by default.
      <p>
        If you have a user from your domain you want to invite with a role other
        than <code>member</code>, just send them an invite as you normally
        would. We prioritize the role assigned on an invitation over the
        auto-join default.
      </p>
    </>
  }
/>

## Managing members on your account

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> a user cannot change their own
      role or remove themself from a Knock account
    </>
  }
/>

### Updating a members role

A members role can be changed from the three dot menu and selecting the "Change role" option. You can pick from one of the [available account roles](/manage-your-account/roles-and-permissions) and the role change will immediately take effect.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> the last owner on an account
      cannot have their role changed
    </>
  }
/>

### Removing members from your account

Members can be removed from an account from the three dot menu. Removing a member will revoke their access to Knock and immediately invalidate any session associated with the user. Additionally, the member will also be sent an email letting them know that they have been removed from the account.

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> the last owner on an account
      cannot be removed
    </>
  }
/>


## Roles and permissions
Learn about roles and permissions in Knock.
---
title: Roles and permissions
description: Learn about roles and permissions in Knock.
tags: ["team", "team members", "account members", "invites", "inviting"]
section: Manage your account
---

Learn more about the roles available to members of your Knock account.

## Overview

Knock uses an account-level roles model, where a given account member's role determines what they'll be able to do in your account. You set an account member's role when you invite them to the Knock dashboard. You can update their role in the members tab of account settings. Learn more in our [managing members documentation](/manage-your-account/managing-members).

Here's an overview of the five roles available to Knock account members:

- **Owner.** For your primary admin who manages billing. This role can invite and manage members, manage billing, and do anything available in the admin role. Your account must always have at least one account owner.
- **Admin.** For admins who need to manage account-level settings. This role can invite and manage members (excluding owner and billing roles), manage account branding, manage environments, and manage advanced developer concepts such as signing keys, enhanced security mode, variables, and webhooks. This role has all permissions available to the member role.
- **Member.** For users who are editing notification workflows and templates in Knock. This role can manage workflows, layouts, users, objects, and tenants. It can make commits and push changes to subsequent environments, and has full access to message and API logs for debugging.
- **Support.** For users who shouldn't have access to workflows and templates, but should be able to dig into message and API logs for debugging purposes.
- **Billing.** For account members who shouldn't have access to anything in Knock but billing.

For a complete overview of which permissions are available to which roles, see our lookup table below.

## Roles and permissions lookup table

<Image
  src="/images/permissions-grid.png"
  width={1592}
  height={1080}
  className="rounded-md mx-auto"
  alt="Knock roles and permissions grid"
/>

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">
        Customizing commit promotion permissions.
      </span>{" "}
      This advanced feature is available on our Enterprise plan.{" "}
      <a href="https://knock.app/contact-sales">Contact our sales team</a> to
      learn more.
    </>
  }
/>


## Audit logs
Learn more about audit logs of actions performed on your Knock account.
---
title: Audit logs
description: Learn more about audit logs of actions performed on your Knock account.
tags: ["audit", "audit log", "access log", "security"]
section: Manage your account
---

Search your account's audit log to review member actions and events.

## Overview

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Data subject to retention policy enforcement.
      </span>{" "}
      See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

The account audit log lets you review actions performed by individual members of the account. In addition, each audit log includes events detailing who performed the action, when it happened, and information about the originating IP address and location of the action.

**Note**: accessing an account's audit log is restricted to admins and account owners.

## Review your account audit log

You can review your account audit log under your Knock account settings: `dashboard.knock.app/<slug>/settings/audit-log` where the `slug` is your account identifier (e.g. `foo-corp`).

Once there, you can filter the audit log by the **Actor** who performed the action, and/or the type of **Action** performed.

<Image
  src="/images/manage-your-account/audit-logs.png"
  width={1624}
  height={1056}
  alt="Viewing audit logs in the dashboard"
/>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why do I see migration-bot@knock.app perform changes on my account?">
    When events occur that do not originate from a user action (like a side
    effect as the result of a merge), we attribute these events to a
    Knock-created "Migration Bot."
  </Accordion>
  <Accordion title="Can I export my account audit logs?">
    Please contact the [Knock support team](mailto:support@knock.app) if you
    need to export the data inside your audit logs. We'd be happy to assist.
  </Accordion>
</AccordionGroup>


## Data obfuscation
Learn more about how to protect your customer's production data in the Knock dashboard.
---
title: Customer data obfuscation
description: Learn more about how to protect your customer's production data in the Knock dashboard.
tags: ["privacy", "data controls", "security", "privacy controls"]
section: Manage your account
---

Enable customer data obfuscation on a per-environment basis to determine what data your team members can see in the Knock dashboard.

## Overview

When you choose Knock to power your notifications, you're also choosing to trust us with your customer data and the data you pass in your notifications. This is why [security](/security) is a foundational priority for us at Knock, and it's also why we built our customer data obfuscation controls.

With customer data obfuscation controls, the Knock dashboard automatically hides any data that might contain either user PII or customer proprietary data. This means that the only data your team members will see in the Knock dashboard is anonymous data such as UUIDs. Customer data obfuscation is managed via our backend, so users won't be able to get at this data through their browser consoles.

Customer data obfuscation is enabled on a [per-environment](/concepts/environments) basis. This means you can obfuscate your customer data in your production environment, while still retaining access to your internal data in development environments for easy testing and debugging.

<Image
  src="/images/manage-your-account/data-obfuscation-example.png"
  alt="A preview of customer data obfuscation enabled"
  width={600}
  height={642}
  className="rounded-md mx-auto border border-gray-200"
/>

To enable customer data obfuscation, go to **Settings** > **Environments** in the Knock dashboard. Select the "..." for the environment you'd like to configure and click "Edit environment."


## Account timezone
Learn how to set the default timezone for your account.
---
title: Account timezone
description: Learn how to set the default timezone for your account.
tags: ["default timezone", "recipient timezone"]
section: Manage your account
---

## Overview

You can set a default timezone for your account by navigating to the General tab under your account settings and selecting a timezone.

<Image
  src="/images/manage-your-account/account-timezone.png"
  alt="Account timezone settings in the Knock dashboard"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

The account timezone will be used as a fallback for [send windows](/designing-workflows/send-windows) and [schedules](/concepts/schedules) if the recipient does not have a timezone set.


## Data retention
How Knock enforces data retention policies on your account.
---
title: Data retention
description: How Knock enforces data retention policies on your account.
tags: ["data", "retention"]
section: Manage your account
---

Knock applies a retention policy to some of the data within your account. Once data exceeds its retention period, it will no longer be accessible in the Knock Dashboard, the Management API, or the public API. Knock will eventually prune data that has aged out of its retention period.

## Data retention policies

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Custom retention policies are not currently supported.
      </span>{" "}
      If custom retention windows are critical to your usage of Knock, please
      use the "Help" dropdown at the top of this page to contact support.
    </>
  }
/>

Some Knock data is subject to a retention policy based on your account plan. These policies are:

- **Enterprise plans**: 90 days
- **All other plans**: 30 days

Knock applies this plan-based retention policy to the following data:

- [Audit logs](/manage-your-account/audit-logs)
- [Message log data](/concepts/messages)
- [Outbound webhook delivery logs](/developer-tools/outbound-webhooks/overview#reading-webhook-delivery-logs)
- [Source event and action logs](/integrations/sources/overview#logging)
- [Workflow run logs](/send-notifications/debugging-workflows#accessing-the-workflow-debugger)

Additionally, Knock applies a universal, 30-day retention policy to the following data:

- [API logs](/developer-tools/api-logs)

## Message log data retention details

Message log data subject to your account's retention policy includes both the message log itself and associated metadata, including:

- Message contents
- Message events
- Delivery logs
- Activities

However, this does not mean that the associated notification has been completely removed from Knock's systems. Your recipients can still interact with these older notifications, and you can still take some specific actions on them.

1. **In-app feed notifications are available indefinitely.** Even after your message log data has expired, you can still fetch the associated `FeedItem` data from the [Show feed endpoint](/reference#get-feed) to deliver in-app notifications to your recipients.
2. **Message status updates are allowed indefinitely.** You can still call the [Update message status](/reference#update-message-status), [Remove message status](/reference#undo-message-status), and [Batch change message status](/reference#batch-update-message-status) endpoints to update the status of an older message, either directly or via a Knock SDK. These status updates will still generate new message events and trigger your [outbound webhooks](/developer-tools/outbound-webhooks/overview), even though you will not be able to view the message in the Knock Dashboard any longer.
3. **Tracking behavior will persist.** Your recipients can still click [tracked-links](/send-notifications/tracking#link-click-tracking), and Knock will still register read events for your notifications using [email-open tracking](/send-notifications/tracking#email-open-tracking).



# Guides

## Knock implementation guide
Learn how to plan and execute your Knock integration from start to finish.
---
title: Knock implementation guide
description: Learn how to plan and execute your Knock integration from start to finish.
tags: ["migrate", "migration", "implementation", "building", "planning"]
section: Guides
---

Knock’s APIs and developer tools make it easy to migrate your notification templates, delivery logic, recipient data, and user preferences into Knock. In this guide, we will walk you through planning and executing your Knock integration from start to finish.

If you’re new to Knock, we recommend taking a look at our [What is Knock?](/getting-started/what-is-knock) page to learn more about our product and how it can be used. You may also want to take a closer look at various [Concepts](/concepts/overview) as you familiarize yourself with the product.

## Migrating data into Knock to power your notifications

Using Knock as your notifications service means storing all of the logic for your notifications (the who, when, and where of delivery) in Knock. We offer APIs and developer tools that make your migration a smooth and efficient process:

- A [Management API](/developer-tools/management-api) that allows you to work programmatically with the same resources that you create in your Knock dashboard (like [Workflows](/concepts/workflows) and their associated message templates, email [Layouts](/integrations/email/layouts), and [Translations](/concepts/translations)).
- A command line interface ([Knock CLI](/developer-tools/knock-cli)) that wraps the Management API, allowing you to work with your dashboard resources from the command line while you’re developing.
- [Bulk endpoints](/reference#bulk-endpoints) to upsert large amounts of data in a single API request (more on specific endpoints below).

<Callout
  emoji="🌐"
  text={
    <>
      <strong>The Knock environment model.</strong> Knock uses the concept of
      logically-separated <a href="/concepts/environments">environments</a> in
      order to ensure that development occurs separately from your production
      environment and that sensitive user data only exists in production. Your
      Knock account comes with two environments (Development and Production) by
      default, but you can add custom environments between them if you need
      additional environments in Knock to mirror your own development lifecycle.
      Keep the environment model in mind when planning the migration for each of
      the resources below.
    </>
  }
/>

While there is no one-size-fits-all approach to planning a migration to Knock, we recommend the following order as a starting point to ensure that any resources which are dependencies of other resources are migrated first:

<Steps titleSize="h3">
  <Step title="Channels">
    The first thing you’ll need to do in order to send notifications through Knock is to set up the downstream providers that deliver your messages. In Knock, we refer to these services as [Channels](/concepts/channels).

    Channels are configured under the **Integrations** tab in your Knock dashboard. You can see a full list of supported channel types and providers [here](/integrations/overview).

    In addition to first-party integrations with message delivery platforms, Knock also offers convenient connections to customer data platforms (CDPs) and reverse ETL providers to bring your data into Knock ([Sources](/integrations/sources/overview)).

    You’ll want to configure your channels prior to building any workflows so that you can set the correct delivery methods for each of your notifications.

  </Step>
  <Step title="Workflows">
    Next, you’ll start building your [Workflows](/designing-workflows/overview). Workflows in Knock serve as containers for all of the logic and message templates associated with a given notification in your system. When you’re ready to start sending notifications, you’ll do so by [triggering](/send-notifications/triggering-workflows) these workflows.
    
    <Callout
      emoji="👣"
      text={
        <>
          <strong>Incremental migration.</strong> Sometimes circumstances will require an incremental migration of your notifications into Knock while maintaining your legacy notification system. In these cases, we recommend migrating your notifications by individual use cases/events rather than all use cases for a single delivery channel at a time. The latter approach will often require triggering both your legacy system and Knock for a single event in order to notify your users in the correct places, which can be difficult to maintain and iterate on as you work to complete your migration.
        </>
      }
    />

    Knock’s environment model means that you’ll be creating all of your workflows and other dashboard resources in your Development environment, where you’ll commit and then promote changes to higher environments (like Production). Read more [here](/concepts/environments).

    You can assign one or more [categories](/concepts/workflows#workflow-categories) to your workflows. These can be used to power recipient preferences (which we will cover in more detail below).

    Workflows are constructed from a trigger step, channel steps, and optional function steps. To learn more about creating the messages that are delivered by your workflows, you’ll want to become familiar with the building blocks of your notifications content:

    - [Message template editor](/designing-workflows/template-editor/overview). The message template editor is where you’ll build the content of your notifications. You can use [Variables](/concepts/variables) to inject dynamic content at runtime.
    - [Partials](/designing-workflows/partials). Partials are content blocks that you can reuse across multiple templates.
    - [Layouts](/integrations/email/layouts). Layouts are the "frame" of your email notifications, where you define shared structure and styles.
    - [Translations](/concepts/translations). Send message content in a user's preferred language with translations.

    Workflows and their building blocks can be created in your Knock dashboard or programmatically with our [Management API](/mapi).

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/mapi#workflows-update" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/workflows/:workflow_key" />
        </a>
        <a href="https://docs.knock.app/mapi#email-layouts-upsert" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/email_layouts/:key" />
        </a>
        <a href="https://docs.knock.app/mapi#partials-upsert" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/partials/:partial_key" />
        </a>
        <a href="https://docs.knock.app/mapi#translations-upsert" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/translations/:locale_code" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Users">
    Once you’ve configured the logic of the notifications that you’d like to send, you’ll need to give Knock the necessary data about your users in order to deliver those notifications.

    The [User](/concepts/users) object in Knock has a number of (optional) reserved attributes like `name`, `email`, and `phone_number`, but it can also store any number of custom properties which can be used in the logic and templates of your workflow; for example, you might want to deliver different messages based on a user’s `role`. These attributes can be updated at any time with subsequent upserts.

    We offer a variety of ways to identify your users to Knock, so you’ll want to look over our guide on [identifying recipients](/managing-recipients/identifying-recipients) before you solidify your migration plan. If you’re planning to send notifications to [push](/integrations/push/overview) or [chat](/integrations/chat/overview) channels, you’ll also need to review our guide on [setting channel data](/managing-recipients/setting-channel-data) to ensure that we can deliver your messages to the right place.

    Remember, the Knock environment model means that you’ll need to identify production users directly into your Knock Production environment.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/reference#identify-user" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/users/:user_id" />
        </a>
        <a href="https://docs.knock.app/reference#bulk-identify-users" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/users/bulk/identify" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Objects and Subscriptions">
    After you’ve planned the migration of users into Knock, you may need to consider advanced use cases for non-user recipients (like a public Slack channel) or a resource in your system (like an order that has been placed) that doesn’t fit neatly under the concept of a “user.” In Knock, these resources can be modeled as [Objects](/concepts/objects).

    [Subscriptions](/concepts/subscriptions) are an extension of objects and express the relationship between a [recipient](/concepts/recipients) (the subscriber) and an object. When you trigger a notification to an object recipient, Knock will also fan out individual workflow runs to **any recipients that are subscribed to the object**. This is especially useful for examples like the order placement use case mentioned above: you can trigger an “order updates” workflow with an object that represents the order as the recipient, and we’ll notify any subscribed Users about the change without you needing to resolve the list of recipients in your system.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/reference#set-object" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/objects/:collection/:id" />
        </a>
        <a href="https://docs.knock.app/reference#bulk-set-objects" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/bulk/set" />
        </a>
        <a href="https://docs.knock.app/reference#add-subscriptions" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/:id/subscriptions" />
        </a>
        <a href="https://docs.knock.app/reference#bulk-add-subscriptions" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/bulk/subscriptions/add" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Tenants">
    If your notifications should be scoped to a particular workspace or organization, you’ll need to implement [Tenants](/concepts/tenants) in your Knock integration. A `tenant` can be applied as context to a workflow trigger in order to [apply per-tenant branding](/concepts/tenants#custom-branding), [per-tenant preferences](/concepts/tenants#per-tenant-user-preferences-and-tenant-preference-defaults), and [scope in-app feed messages to particular tenants](/concepts/tenants#scoping-in-app-feeds).
  
    <Callout
      emoji="✨"
      text={
        <>
          <strong>Enterprise plan feature.</strong> Per-tenant branding and per-tenant preferences are
          features of our{" "}
          <a href="https://knock.app/pricing" target="_blank">
            Enterprise plan
          </a>
          . If you’d like to find out more information about Enterprise plan features
          and pricing, please contact us at <a href="mailto:sales@knock.app">
            sales@knock.app
          </a>.
        </>
      }
    />

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/reference#set-tenant" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/tenants/:id" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Preferences">
    Once your recipients (both users and objects) and tenants have been migrated to Knock, you’ll want to consider delivery preferences for your notifications to give your users control of where and when they receive updates from your product. For more information on building a preference center in your app, check out the section on [Completing your client-side integration](#completing-your-client-side-integration) below.

    Knock’s powerful [Preferences](/preferences/overview) API allows your users to opt out of notifications based on the notification’s delivery `channel_type`, the `category` of the notification, the specific notification `workflow`, or a combination of these properties. You can also extend these preferences to be [tenant-specific](/preferences/tenant-preferences) or to [evaluate conditionally](/preferences/preference-conditions) at runtime.

    You can set environment-level default preferences (for example, maybe a given workflow should require a user to manually opt in to receive those notifications) as well as tenant-specific default preferences that will be overridden by a recipient’s individual preferences.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/reference#set-preferences-user" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/users/:user_id/preferences/:id" />
        </a>
        <a href="https://docs.knock.app/reference#bulk-set-preferences" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/users/bulk/preferences" />
        </a>
        <a href="https://docs.knock.app/reference#set-preferences-object" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/objects/:collection/:object_id/preferences/:id" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Schedules">
    Finally, for any notifications that you’ll send on a recurring basis or reminders that should be sent at a specific future date, our [Schedules](/concepts/schedules) feature should be considered before you’re ready to finalize your integration.

    Schedules can be set, updated, and deleted via API. Although they are recipient-specific, you can create a schedule for up to 100 recipients at a time.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
        <a href="https://docs.knock.app/reference#create-schedules" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="POST" path="https://api.knock.app/v1/schedules" />
        </a>
        <a href="https://docs.knock.app/reference#update-schedules" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://api.knock.app/v1/schedules" />
        </a>
        <a href="https://docs.knock.app/reference#delete-schedules" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="DELETE" path="https://api.knock.app/v1/schedules" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
</Steps>

For more information and in-depth guidance on specific use cases, please take a look at our [example apps](/getting-started/example-apps) and the following guides:

- [Alerting](/guides/alerting)
- [Customer-facing webhooks](/guides/customer-webhooks)
- [Recurring digests](/guides/building-recurring-digests)
- [Modeling Users, Objects, and Tenants](/guides/modeling-users-objects-and-tenants)

## Completing your client-side integration

Certain implementations will require some client-side work to [build in-app UI](/in-app-ui/overview) in order to complete your integration. Knock provides [out of the box UI components](/in-app-ui/react/overview#pre-built-components) that you can use, but you can also [implement our in-app feed API and React hooks in a headless way](/in-app-ui/react/custom-notifications-ui) if you’d like to bring your own components and styles.

Here are some use cases that will require additional client-side planning:

- **In-app messaging.** If you’re planning to use Knock-powered in-app messaging (whether that’s a notification feed for web or mobile, other in-product notifications like modals and banners, or custom components powered by our [Message types](/in-app-ui/message-types) feature), you’ll need to build a way to display those messages to your users. For more information on your preferred language or framework, visit the **Building In-app UI** section of our navigation menu.
- **User preferences.** In order to power [user preferences](/preferences/overview) in Knock, you need to [build a preference center](/in-app-ui/react/preferences) in your application that gives your user control over the types of notifications they receive.
- **Chat app authentication.** Some delivery channels like Slack require a way for your users to authenticate your app or bot into their workspace. Knock provides drop-in React components ([SlackKit](/in-app-ui/react/slack-kit) and [TeamsKit](/in-app-ui/react/teams-kit)) for both Slack and Microsoft Teams that will help manage the process of authentication and storing the necessary information (access tokens, etc.) as [channel data](/managing-recipients/setting-channel-data) in Knock so that we can deliver your notifications.

## Testing and observability

Testing your notifications and insight into any errors that occur are a key part of developing and deploying your Knock integration. Knock offers many tools and resources to help you ensure that your users are receiving the right messages at the right time:

- Guides on tools for [testing](/send-notifications/testing-workflows) and [debugging](/send-notifications/debugging-workflows) workflows.
- A [Postman collection](/developer-tools/knock-and-postman) to test against our API.
- An optional [sandbox mode](/integrations/overview#sandbox-mode) on each of your channels that allows you to generate and preview messages without sending them to your downstream provider for delivery.
- [Delivery and engagement statuses](/send-notifications/message-statuses) for all of the notifications sent through Knock.
- [Outbound webhooks](/developer-tools/outbound-webhooks/overview) for real-time updates on events that occur within Knock.
- An **Analytics** page in your Knock dashboard for insight into the messages you’re sending across different workflows and delivery channels.

<Callout
  emoji="✨"
  text={
    <>
      <strong>Enterprise plan feature.</strong> In addition to the tools listed
      above,{" "}
      <a href="https://knock.app/pricing" target="_blank">
        Enterprise plan
      </a>{" "}
      customers have access to{" "}
      <a href="/integrations/extensions/overview">Extensions</a>, our
      integrations with downstream providers that enable advanced observability
      and analytics for your notifications. If you’d like to find out more
      information about Enterprise plan features and pricing, please contact us
      at <a href="mailto:sales@knock.app">sales@knock.app</a>.
    </>
  }
/>

## Going to production

You’re finally ready to move to production – congratulations! Before you flip the switch and sit back to admire your work, here are a few last-minute items to check off your list:

- Be sure to update your application’s [API keys](/developer-tools/api-keys) to point to your Knock Production environment.
- Ensure that all of your work has been [promoted](/concepts/commits#promoting-commits) to your Production environment.
- If you’re using in-app messaging, [generate a signing key](/in-app-ui/security-and-authentication#1-generate-the-signing-key) and enable enhanced security mode for client-side requests in your Production environment. Both of these actions can be completed by navigating to **Developers** > **API Keys** in your Knock dashboard’s Production environment.

As always, we’re here to help. If you have any questions or run into issues as you build with our product, we hope you’ll let us know! Email us at support@knock.app and we’ll be more than happy to assist you.

Knock on. 🤘


## Alerting
Learn how to power cross-channel, configurable alerts using Knock.
---
title: Powering cross-channel configurable alerts with Knock
description: Learn how to power cross-channel, configurable alerts using Knock.
tags: ["alert", "alerts", "alerting"]
section: Guides
---

In this guide, we’ll cover some best practices in creating alerting-style workflows in Knock. Alerts are common in many types of infrastructure tools, like Datadog or Honeycomb, as well as in product management and data tools like Amplitude or Mixpanel.

<Callout
  mt={4}
  emoji="👩‍💻"
  text={
    <>
      <span className="font-bold">See an example.</span> Check out{" "}
      <a href="https://github.com/knocklabs/alerting-example" target="_blank">
        our example app
      </a>{" "}
      to see how you can build configurable alerts with Knock. This app covers
      creating alerts, configuring recipients, and building a UI to allow users
      to manage their channels, events, and batching behavior.
    </>
  }
/>
Here are some assumptions we’ll make about configurable alerts for the purposes of
this guide:

1. The user should be able to pick the channels (like email, SMS, and in-app) that the workflow will use to notify recipients.
2. The user can define the list of recipients who will receive these notifications.
3. The user can also create additional dimensions to determine whether an alert should be triggered, like a list of event types or a particular usage threshold.

In the following steps, we’ll break down this process to help you understand how to create your own alerts. Since Knock can be used flexibly and adopted incrementally, we’ll examine two scenarios for how you can model alerts: modeling alerts in your system vs. modeling them in Knock.

## Modeling alerts in your system

Let’s start with how you would power alerts modeled in your system using Knock to coordinate your cross-channel notification logic.

In the code sample below, you can see an example `alert` entity that might be stored in your database. After querying that entity, you pass the `alert` configuration and `event` type in the `data` payload for your workflow trigger and specify any `recipients` stored on the `alert` itself.

```javascript title="Trigger an alert from your system"
const alert = {
  id: "alert_1YQ4XR18",
  channels: ["email", "sms", "in_app"],
  events: ["sever:warn", "server:info"],
  recipients: [
    {
      id: "user_391d92cd",
    },
  ],
  batchWindow: {
    frequency: "weekly",
    days: ["fri"],
    hours: 17,
  },
};

await knock.workflows.trigger("alert", {
  data: {
    alert,
    event: "server:warn",
  },
  recipients: alert.recipients.map((r) => r.id),
});
```

When you look at this code sample, you’ll see that there’s nothing fundamentally different about triggering an alert than triggering any other type of notification. You pass in data to be used in the workflow itself as well as all of the recipient references. You can then use the data in individual channel and function steps to drive the logic of your workflow.

In the next step of this guide, we’ll explore how you can offload more of this modeling to Knock, but it’s worth discussing the pros and cons of these two approaches.

### Benefits of modeling in your system

**Pros**

- Your alerting data model lives in your system and remains the source of truth around alerts. In some cases, this may be a more natural place for it, depending on the data you’re storing and how you’re using the alerts in your system
- Less bookkeeping; the only call to Knock is when the alert is triggered

**Cons**

- Sending to a large number of recipients requires making multiple calls to Knock (recipients are capped at 1000 per trigger)
- You have to fetch and pass the alert object to Knock on every alert invocation
- More complex to send to a non-user recipient for a channel such as Slack or Microsoft Teams

### Benefits of modeling in Knock

**Pros**

- Knock manages all aspects of your alerting data model and becomes the source of truth for alerts and users subscribed to them
- Object subscriptions work well when you have a large set of recipients and don’t want to send the full list to Knock
- Simple to model non-user recipient channels (like Slack) that can be connected directly to the alert object itself

**Cons**

- More bookkeeping; you have to update Knock when a model changes or a user is added or removed from an alert

Since there is no one-size-fits-all approach here, you’ll need to weigh these pros and cons for your own use case to determine how much of your data model you want to bring into Knock. Knock works best when it’s loosely coupled to your system, so it’s helpful to consider how often your entities will change and how tightly your recipient lists are coupled with other parts of your organizational model.

## Modeling alerts as Knock Objects

<Image
  className="rounded-md mx-auto border border-gray-200"
  src="/images/guides/alerting/alerting-object-diagram.png"
  alt="An Object in Knock configured as an alert"
  width={1128}
  height={944}
/>

The first step in creating an alerting system with Knock as the source of truth involves modeling your alert as an [Object](/concepts/objects). Objects allow you to represent non-user recipients and create a relationship with users through subscriptions, which we’ll cover in the next step.

```javascript title="Create an Object to represent the alert and config"
const alert = await knock.objects.set("alert", alertId, {
  channels: ["email", "sms", "in_app"],
  events: ["maintenance", "compliance", "driver"],
  batchWindow: null,
});
```

Using custom properties, you can store additional information directly on the Object, like the `channels` that should be used in the alert, or the `events` that the alert is configured for. This allows you to encode the conditional logic of where and when a notification should send directly into Knock. Using the `batchWindow` property, you could even store [a custom window rule](/designing-workflows/batch-function#set-a-dynamic-batch-window-using-a-variable) on the alert object to represent how it should batch notifications.

### Subscribe Users to the alert

Once you have an Object modeled to store your alert data, you can add individual recipient [subscriptions](/concepts/subscriptions) to your alert object. This allows you to fan out to an unlimited number of recipients while still triggering a single workflow.

<Image
  className="rounded-md mx-auto border border-gray-200"
  src="/images/guides/alerting/alerting-object-subscription-diagram.png"
  alt="Users subscribed to an alert Object"
  width={2198}
  height={1336}
/>

Subscriptions can also hold their [own unique properties](/concepts/subscriptions#subscribing-recipients-to-an-object) that can be accessed during a workflow run. For example, users could select their own `channels`, `events`, or `batchWindow` if they wanted to and store them as properties of the subscription.

```javascript title="Subscribe a user to an alert Object"
knock.objects.addSubscriptions("alerts", alertId, {
  recipients: ["user_79bc96a9", "user_JG9NGAJQ", "user_391d92cd"],
  properties: {
    channels: ["email", "in_app"],
    events: ["maintenance", "compliance"],
    batchWindow: {
      frequency: "weekly",
      days: ["fri"],
      hours: 17,
    },
  },
});
```

Once you've stored these properties on a subscription, you can access them inside the workflow run on `recipient.subscription.channel` or `recipient.subscription.events` for use in either templates or step conditions. This allows you to create a highly configurable alerting system that can be customized on a per-user basis.

### Triggering an alert

To trigger an alert workflow, your application would only need the `id` of the alert you want to trigger. From there, you would fetch the `alert` Object from Knock (we’re working on some ways to more easily reference objects inside of workflow runs).

Then you trigger the alerting workflow using the Object as a recipient. You’ll also want to pass the entire `alert` in the `data` payload as well as an `event` type.

```javascript title="Trigger an alert workflow"
//Fetch the alert and config, we're working on a way to resolve this in the workflow
const alert = await knock.objects.get("alerts", "alertId");

//Trigger the workflow with the Object as recipient to fan out to subscribers
await knock.workflows.trigger("alert", {
  recipients: [{ collection: "alerts", id: alert.id }],
  data: {
    alert,
    event: "maintenance",
  },
});
```

When Knock processes this workflow run, it will run for the Object as a recipient and will also fan out to all of its subscribers and process a workflow run for each User. Since we passed in the `alert` and `event` as payload data, those values will be present on every recipient run of the workflow. That means we can access the properties stored on our `alert` object to make decisions about whether or not to send a notification on specific channels.

## Modeling a workflow for alerting

Now let’s look at what a workflow might look like to support this use case.

<Callout
  mt={4}
  emoji="🏗️"
  text={
    <>
      <span className="font-bold">Clone this workflow.</span> You can clone this
      workflow directly into your account from the workflow template gallery.
      The template gallery can be accessed from the "Create workflow" modal. You
      can find this workflow under the "Alerts" title under the "Monitoring"
      category.
    </>
  }
/>

A Knock workflow encapsulates _a single type of notification_ in your system and comprises the cross-channel orchestration logic and associated behavior for how a notification should be sent to a recipient.

For our alert workflow, we find it’s best to have a single workflow that has all possible channels that an alert could be sent to. We can then use trigger conditions per-channel step to have a given alert's configuration determine whether a particular channel should be used for a given recipient.

<Image
  className="rounded-md mx-auto border border-gray-200"
  src="/images/guides/alerting/alerting-workflow-diagram.png"
  alt="A workflow for alerting containing multiple branches"
  width={2029}
  height={2115}
/>

### Deciding whether to run the workflow

Since our application lets alerts subscribe to specific events, we’ll also want to ignore any events that the alert isn’t configured for.

To do that, we can use a [Trigger Step Condition](/designing-workflows/step-conditions#trigger-step-conditions) to evaluate if `data.alerts.events` contains `data.event`. If it does, then we can continue to the next step. If not, we can halt the workflow immediately.

Knock’s [conditions model](/concepts/conditions) is very expressive, so it’s also possible to represent conditions other than basic string matching. For example, if you had an alert property like `usageThreshold` you could create a greater than comparison to a piece of data in the payload.

### Deciding when to send notifications

Next, we might want to either send notifications immediately or open a batch to catch multiple notifications of the same type. We can do that with [a branch step](/designing-workflows/branch-function), where we examine whether or not there is a value for the batch window in `data.alert.batchWindow`. If there is, we’ll proceed to a batch step. If not, we’ll execute channel steps immediately.

### Deciding how to batch notifications

Let’s take a look at the batching example first. When using the batch function, Knock provides multiple ways to express when a batch window should close using [a dynamic batch window](/designing-workflows/batch-function#set-a-dynamic-batch-window-using-a-variable). All batches are automatically created on a per-recipient basis, so in the case of a fan-out like we have here, a batch will be created for each recipient subscribed to the alert.

You might also want to create a particular batch per event type. You can do that by using a [batch key](/designing-workflows/batch-function#selecting-a-batch-key), which in this case could be `data.event`. As you trigger alerting events in your app, Knock will use this key to open a batch per-recipient and per-event.

### Deciding which channels to use

Lastly, let’s look at how you would decide which channels to send notifications to. When you configured your `alert` you stored an array of `channels` on the Object. As the workflow processes each channel step you can use [a step condition](/designing-workflows/step-conditions) to evaluate whether the current channel type exists in the array of configured channels: `data.alert.channels contains "sms"`.

If that condition doesn’t evaluate to `true`, that particular channel step is skipped.

### Interacting with user preferences

Up until now, much of the configuration on when and where to send notifications has existed in the `alert` object we created. But since users have [preferences](/preferences/overview) as well, it’s possible that those preferences interact with some values configured in the `alert` itself. For example, even if the `alert` is configured to send email, if a user has opted out of the email channel, they will not get that notification.

There are a few ways to look at preferences in this context:

1. Developers control [which preferences](/preferences/overview#how-preferences-work) are exposed to the user, so it’s worth considering how you want to create a preference center and at what level of granularity you want users to be able to opt out. For example, you may just never want to expose global `channel_type` preference settings and instead expose `workflow` or `category` settings. In this case, just omitting a setting for your alerting workflow means users can’t opt out.
2. Developers can always [override user preferences](/preferences/overview#advanced-concepts) at the workflow level in the dashboard. Enabling this option means that every message sent from that particular workflow will override preferences set by the user.
3. You can always [examine the preferences](/preferences/overview#preference-evaluation-rules) Knock evaluates on a given recipient in the workflow debugger.


## Customer-facing webhooks
Learn how to use Knock to send per-customer configurable webhooks as part of your notification workflows.
---
title: Building customer-facing, configurable webhooks with Knock
description: Learn how to use Knock to send per-customer configurable webhooks as part of your notification workflows.
tags: ["webhooks", "webhooks as a service"]
section: Guides
---

In this guide, we’ll walk through how Knock can be used to send per-customer configurable webhooks as part of your notification workflows.

<Callout
  mt={4}
  emoji="👩‍💻"
  text={
    <>
      <span className="font-bold">See an example.</span> Check out{" "}
      <a
        href="https://github.com/knocklabs/customer-facing-webhooks-example"
        target="_blank"
      >
        our example app
      </a>{" "}
      to see how you can build customer-facing webhooks UI with Knock. This app
      covers configuring webhooks connections, testing webhooks, and building UI
      to allow developers to debug webhook delivery.
    </>
  }
/>
## Using objects and subscriptions to power webhooks

Let's take a hypothetical application comprised of projects that users belong to. Our customers can configure webhooks for each of their project. We can express this as “a project can have one or more configured webhooks”.

In Knock, we’ll model this as follows:

- Every customer configured webhook will be an [object](/concepts/objects) in Knock that will house the webhook configuration.
- All webhooks a customer configures will belong to a single `project` object using [object subscriptions](/concepts/subscriptions) to express the relationship between the project and the webhooks configured for that project.

First we’ll upsert the project as an object in Knock. We’re putting the project under a `projects` collection.

```js title="Upsert our project object"
const project = await knock.objects.set("projects", "project-1", {
  name: "My project",
});
```

Now, when a customer creates or updates a webhook in our system we’ll upsert a corresponding `project_webhooks` object and associate it back to the project object via a subscription.

```js title="Creating a webhook object and subscribing it to our project object"
// Generate a webhook ID
const webhookId = "some-unique-id";

// Create the webhook object with the configuration
const projectWebhook = await knock.objects.set("project_webhooks", webhookId, {
  events: ["project:created"],
  url: "https://some-url.com/incoming/webhook",
});

// Associate the webhook with the project
await knock.objects.addSubscriptions("projects", "project-1", {
  recipients: [{ collection: "project_webhooks", id: webhookId }],
});
```

If at any point we need to list all of the configured webhooks for a given project, we can do so by listing the subscriptions for the project:

```js title="List webhooks for a given project"
const { entries: webhookSubscriptions } = await knock.objects.listSubscriptions(
  "projects",
  "project-1",
);
```

## Configuring an HTTP channel

Now we’re going to configure our Webhook HTTP channel in Knock. You can learn how to configure a Webhook HTTP channel in our [webhook channel overview](/integrations/webhook/overview).

Next, we’ll configure the webhook request for our new webhook channel. For the channel URL we’re going to configure it as `{{ recipient.url }}` which tells Knock to use the URL configured on the webhook recipient object:

<Image
  className="rounded-md mx-auto border border-gray-200"
  src="/images/guides/configure-customer-webhook.png"
  alt="Configure a customer webhook"
  width={2919}
  height={1872}
/>

And for the body of the payload that we send per webhook event, we’ll use the following template:

```js title="Configure the webhook channel payload"
{
"type": "{{eventType}}",
"payload": {{payload | json}},
"createdAt": "{{timestamp}}"
}
```

If you are passing a JSON payload to the webhook, you can use the `json` filter to ensure that the payload is correctly serialized.

## Building your webhook notification workflow

Now we can build our notification workflow that sends out a webhook when the customer has a webhook configured for the object.

To get started:

1. Create a new workflow in Knock
2. Add a webhook channel step to your workflow
3. Configure the step to use your customer webhook channel
4. Save and commit your workflow

We don't need to customize any of the data sent in the webhook channel, so we can keep everything as-is with the default configuration.

## Triggering your webhook notification workflow

Now our workflow is configured, we can trigger it via the API. We’ll pass the `project` as a recipient to the workflow, which will automatically trigger our workflow to execute _for all webhooks configured_.

```js title="Trigger workflow for our project"
await knock.workflows.trigger("workflow-with-webhook-step", {
  data: {
    event_type: eventType,
    payload: eventPayloadData,
  },
  recipients: [{ collection: "projects", id: "project-1" }],
});
```

This works as Knock will automatically fan-out to all webhooks subscribed to the project as part of the execution, meaning that the workflow is invoked for the project and for each webhook as a recipient.

## Advanced topics

### Debugging failed webhook deliveries

You can use the Message logs within Knock in order to [debug messages sent](/send-notifications/debugging-workflows), where you’ll see delivery logs about the request to the customer’s webhook channel.

Since your customers won't have access to Knock, you can use the [Message delivery logs API](https://docs.knock.app/reference#get-message-delivery-logs) to create UI in your application that lets developers inspect the request/response interaction between Knock and their downstream URL.

### Reporting on failed webhook deliveries

You might want to provide a way to notify your customers that their webhooks are failing. You can do so by leveraging Knock’s [outbound webhooks](/developer-tools/outbound-webhooks/overview) features to create a webhook callback to your server that listens for `message.undelivered` events.

### Providing a dynamic signing key

You will likely want to provide a way for your customers to [verify that the webhook request is coming from Knock](/integrations/webhook/overview#securing-your-webhooks). You can do so by providing a signing key in your webhook channel's configuration that Knock will use to sign the request with an HMAC/SHA256 signature.

For customer-facing webhooks, you can provide a UI for your customers to configure a signing key; you'll want to configure this in Knock as a [dynamic signing key](/integrations/webhook/overview#using-a-dynamic-signing-key) using Liquid variables.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should different types of webhook events be sent via separate notification workflows or a single workflow?">
    The answer here really depends on how different the notifications around each event type need to be. You should consider structuring each event type as a separate workflow if the types of notifications sent in each event type differ a lot, or if the templates between event types are sufficiently different.
  </Accordion>
  <Accordion title="How do I conditionally send only to webhook objects?">
    If you need to limit the execution of the workflow steps you can add a trigger condition onto your webhook channel steps that will only send to:

    - `recipient.__typename` is equal to `Object`
    - `recipient.collection` is equal to `project_webhooks`

  </Accordion>
  <Accordion title="How do I conditionally allow certain event types on my webhooks?">
    You can store an `event_types` property on your webhook object and use a [step condition](/designing-workflows/step-conditions) to express whether or not the step should be executed (as an allow list).

    - `recipient.event_types` contains `some:event`

  </Accordion>
</AccordionGroup>


## Recurring digests
Learn how to build recurring, cross-channel digest notifications with Knock.
---
title: Powering recurring digests with Knock
description: Learn how to build recurring, cross-channel digest notifications with Knock.
tags: ["weekly", "daily", "monthly", "recurrence"]
section: Guides
---

In this guide, we'll create a simple recurring digest notification for our customers that will execute a digest every Monday at 9am to summarize information that the users might have missed in the past week.

To do so, we'll use the [schedules API](/concepts/schedules) and the [fetch function](/designing-workflows/fetch-function) to build a powerful, flexible notification workflow that is driven by dynamic data from your service.

## Creating your Knock workflow

We're going to create a Knock workflow named "Recurring digest" from the Knock dashboard. To do so, navigate to your Development environment and click the "Create workflow" button in the top right corner. We'll then be prompted to name the workflow and have a key generated, which will be autogenerated as `recurring-digest` from the name by default.

<Image
  src="/images/guides/recurring-digests/creating-a-workflow.png"
  width={3238}
  height={2112}
  alt="Creating our workflow"
/>

Next, let's configure our newly created workflow to do something. To do so we'll click the "Edit steps" button to be taken to the [workflow builder](/designing-workflows) which is where we can add steps to our workflow and configure the templates that will generate notifications.

### Fetching data for our digest

In this digesting example, we'll use the [workflow fetch function](/designing-workflows/fetch-function) to retrieve information that we wish to digest as part of the notification. The fetch step will make a call _per recipient_ to an HTTP endpoint to retrieve this information.

In our example, we'll implement this as a simple Node.JS server that returns some static digest information per recipient, but you can return any information from any HTTP endpoint to power your digest.

```javascript title="The Node.JS server we query for digest items"
const express = require("express");
const app = express();

// Some dummy digest items by the recipient id
const digestItems = {
  chris: [
    {
      title: "Left a comment on Knock product roadmap",
      timestamp: "2023-05-17T12:00:00Z",
    },
    {
      title: "Liked a comment by Sam Seely on Knock Onboarding",
      timestamp: "2023-05-17T12:00:00Z",
    },
  ],
  sam: [
    {
      title: "Left 3 new comments on Knock engineering roadmap",
      timestamp: "2023-05-17T12:00:00Z",
    },
  ],
};

// respond with the users digest
app.get("/users/:userId/digest", (req, res) => {
  const items = digestItems[req.params.userId];
  res.json(items);
});

app.listen(3000, () => console.log(`⚡️ Server running`));
```

Next, we'll add a fetch function to our workflow, and configure the fetch function to hit the endpoint. We'll do this by adding a 'Fetch function' to the workflow and clicking the 'Edit request' button.

In this example, we're going to pass the current recipient's `id` as a parameter in the endpoint URL using liquid. We'll use [ngrok](https://ngrok.com/) to hit our local endpoint, but in production, we'd point this to a deployed, hosted service that's publically accessible.

<Image
  src="/images/guides/recurring-digests/configuring-the-fetch-step.png"
  width={3238}
  height={2112}
  alt="Configuring the fetch function"
/>

When the fetch step is executed the JSON response returned from the HTTP endpoint will be merged into the **current workflow run scope** making all of that data accessible to be used in your notification templates.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note</strong>: in the future, Knock will allow Knock managed
      digest data, where the information can be summarized from triggered Knock
      workflows per recipient.
    </>
  }
/>

### Designing your notification template

The last step in building our workflow is to add a channel step to our Knock workflow to send a notification out. Here we'll send an email, but we could use any supported channel type in Knock, or even create a cross-channel digest notification if we wanted.

Once we've added our email channel step, we can edit the underlying template associated by clicking "Edit template." We'll add a markdown block to the email builder and we can copy in the template below:

```markdown title="Digest email template"
## You have {{ items | size }} new {{ items | size | pluralize: "notification", "notifications" }}

There are new notifications waiting for you to review. Please go into the app to review them.

<ul>
{%- for item in items %}
<li>
{{ item.title }} happened on {{ item.timestamp }}
</li>
{%- endfor %}
</ul>
```

<br />

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note</strong>: you'll need to configure an email channel via a
      provider in order to start sending emails with Knock. You can read more on{" "}
      <a href="/integrations/email/overview">configuring email channels here</a>
    </>
  }
/>

Here we're using the `items` array that we returned from the fetch step to render each notification. Notice how each item corresponds to the data structure we're defining above in our node service.

We can also set some preview data in Knock to help with seeing what our email template will look like. To do so, click "Edit preview data" in the left hand variable pane and add the following JSON:

```json title="Sample preview data"
{
  "items": [
    {
      "timestamp": "2023-05-17T12:00:00Z",
      "title": "A new notification"
    }
  ]
}
```

At this point, it's probably a good idea to run a test of our workflow using the test runner to execute an end-to-end workflow run for a single recipient by clicking "Run a test" in the top right corner of the workflow builder.

Finally, we'll need to **Commit our workflow** to the development environment by clicking the "Commit to development" button in the top right corner of the workflow page. We'll also need to **activate our workflow** before we can use it by marking the status as "Active."

Once we're satisfied with the email notification, we can move on to running the scheduled digest for our recipients.

## Creating digest schedules

Finally, we'll want to create a recurring schedule for our users. To do so we'll use the [Schedules API](/concepts/schedules) which lets us trigger a workflow for one or more recipients on a defined schedule.

Each schedule is defined per recipient, but the `createSchedules` method lets us create a schedule for up to 100 recipients at a time. The schedule defines which workflow to trigger, as well as the rules for when to repeat the schedule.

In our case, we'll create a weekly notification that goes out every Monday at 9am, for `chris` and `sam`.

```javascript title="Creating schedules for our recipients"
await knock.workflows.createSchedules("recurring-digest", {
  recipients: ["chris", "sam"],
  repeats: [
    {
      frequency: "weekly",
      days: ["mon"],
      hours: 9,
    },
  ],
});
```

<br />

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note</strong>: this example assumes that we've already{" "}
      <a href="/concepts/users#sending-user-data-to-knock">identified</a> the
      two users into Knock to synchronize their name and email address.
    </>
  }
/>

Once our schedules are created, they will start running on the next occurrence date. We can even see these in the Knock dashboard under **Workflows** > **Recurring digest** > **Schedules** and see when the schedules will run next for our recipients.

<Image
  src="/images/guides/recurring-digests/viewing-schedules.png"
  width={3238}
  height={2112}
  alt="Viewing schedules in the dashboard"
/>

## Wrapping up

That's it! We just created our first recurring notification for our users that will run every Monday at 9am. If you want to think about extending this example you could consider:

- **Adding more supported channel types for the notification**. You could add an in-app notification or a Slack notification for your users.
- **Making schedules configurable by your users**. Because each schedule is per-user, you can easily make schedules configurable at the user level using the [update schedule endpoint](/reference#update-schedules).
- **Adding timezone support**. Schedules [natively support timezones per recipient](/concepts/schedules#executing-schedules-in-a-recipients-timezone), so we can easily allow our recurring digests to run at a specific time in the users timezone.


## Migrate from Courier
Learn how to migrate your notifications from Courier to Knock.
---
title: Migrate from Courier to Knock
description: Learn how to migrate your notifications from Courier to Knock.
tags: ["migrate", "courier", "migration"]
section: Guides
---

Knock’s APIs and developer tools make it easy to migrate your notification templates and user data from other notifications platforms into Knock. In this guide, we will walk you through planning and executing a migration from Courier into Knock.

## Mapping Courier concepts to Knock concepts

Before migrating any data into Knock, it’s helpful to understand how the resources in your Courier account map to concepts and resources in Knock.

### Integrations

In order to deliver notifications with Courier, you installed one or more <a href="https://www.courier.com/docs/external-integrations/intro" target="_blank">Integrations</a> for downstream providers in your Courier dashboard. In Knock, we refer to these delivery platforms as [Channels](/concepts/channels).

Channels are configured under the **Integrations** tab in your Knock dashboard. You can see a full list of supported Channel types and providers [here](/integrations/overview).

In addition to first-party integrations with message delivery platforms, Knock also offers convenient connections to customer data platforms (CDPs) and reverse ETL providers to bring your data into Knock ([Sources](/integrations/sources/overview)), as well as to popular analytics and data warehousing tools to allow you to export important data out of Knock ([Extensions](/integrations/extensions/overview)).

### Automations and Notification Templates

In Courier, the content of your notifications is contained in <a href="https://www.courier.com/docs/platform/content/notification-designer/notification-designer-overview" target="_blank">templates</a> built in your dashboard, and the orchestration and logic of sending your notifications is contained in <a href="https://www.courier.com/docs/platform/automations/" target="_blank">Automations</a>.

Knock combines both of these things into a single resource called a [Workflow](/concepts/workflows), which serves as a container for all of the logic and message templates associated with a given notification in your system. You can also create [Partials](/designing-workflows/partials), which are content blocks that can be used across multiple workflows.

When you’re ready to start sending notifications, you’ll do so by [triggering](/send-notifications/triggering-workflows) your workflows.

### Users and Profiles

Courier uses the concept of <a href="https://www.courier.com/docs/platform/users/" target="_blank">Users</a> to represent the recipients of notifications, with optional <a href="https://www.courier.com/docs/reference/profiles/" target="_blank">Profile</a> records associated with each user to hold data about that user.

Knock combines these concepts under a single [User](/concepts/users) object on which you can store any number of custom properties related to your notifications’ recipients.

### Lists

Courier allows you to build <a href="https://www.courier.com/docs/reference/lists/" target="_blank">Lists</a> of users that you would like to send a given notification to. In Knock, we call this concept [Subscriptions](/concepts/subscriptions).

Subscriptions are an extension of [Objects](/concepts/objects) and express the relationship between a [Recipient](/concepts/recipients) (the subscriber) and an Object. When you trigger a notification to an Object recipient, Knock will fan out the workflow trigger to **all recipients that are subscribers**, automatically enqueuing a workflow run for each recipient subscriber on your behalf.

### Tenants and Brands

If you’re currently using <a href="https://www.courier.com/docs/reference/tenants/" target="_blank">Tenants</a> in Courier to scope your notifications to a particular workspace or organization (and optionally associating <a href="https://www.courier.com/docs/reference/brands/" target="_blank">Brands</a> with those Tenants), you can achieve similar functionality with Knock [Tenants](/concepts/tenants).

Unlike Courier, per-tenant branding attributes are stored directly on a Tenant in Knock rather than as a separate resource. Knock also does not directly associate Tenants with the recipients of a notification (no subscription logic necessary!); rather, a `tenant` is applied as context to a particular workflow trigger in order to [apply per-tenant branding](/concepts/tenants#custom-branding), [per-tenant preferences](/concepts/tenants#per-tenant-user-preferences-and-tenant-preference-defaults), and [scope in-app feed messages to particular tenants](/concepts/tenants#scoping-in-app-feeds).

<Callout
  emoji="✨"
  text={
    <>
      <strong>Note:</strong> Per-tenant branding and per-tenant preferences are
      features of our{" "}
      <a href="https://knock.app/pricing" target="_blank">
        Enterprise plan
      </a>
      . If you’d like to find out more information about Enterprise plan features
      and pricing, please contact us at <a href="mailto:sales@knock.app">
        sales@knock.app
      </a>.
    </>
  }
/>

### User Preferences

Courier’s <a href="https://www.courier.com/docs/reference/user-preferences/intro" target="_blank">User Preferences API</a> allows you to set notifications preferences for a given user by a Topic categorization and a Preference Section (a group of multiple Topics), as well as by delivery channel.

Knock’s [Preferences](/preferences/overview) model has a single high-level `category` property that can be assigned on a Workflow; because a given workflow can have more than one `category`, you can use this property to map both Topics and Preference Sections to your notifications in Knock.

Our powerful Preferences API allows your users to opt out of notifications based on the notification’s delivery `channel_type`, the `category` of the notification, the specific notification `workflow`, or a combination of these properties. You can also extend these preferences to be [tenant-specific](/preferences/tenant-preferences) or to [evaluate conditionally](/preferences/preference-conditions).

### Translations

Courier’s <a href="https://www.courier.com/docs/reference/translations/" target="_blank">Translations API</a> allows you to read and write translations to Courier in the form of `.po` files that are referenced using the handlebars templating language within a notification template.

Knock helps you to power notifications in multiple locales and languages using Knock [Translations](/concepts/translations). You can work with Translations directly in your dashboard or programmatically via API, and Knock supports both `json` and `.po` file formats.

When using the `t` tag [method](/concepts/translations#translation-methods-filter-vs-tag) of referencing translations in your message templates, Knock will automatically generate the associated translation files for each of your registered locales behind the scenes.

## Migrating your data into Knock

Now that you have a good understanding of how the resources in your Courier account map to concepts and resources in Knock, you can start planning your migration.

Knock offers APIs and developer tools that make a migration smooth and efficient:

- A [Management API](/mapi) that allows you to work programmatically with the resources that you can also create directly in your Knock dashboard (like Workflows and their associated message templates, email [Layouts](/integrations/email/layouts), and Translations).
- A command line interface ([Knock CLI](/developer-tools/knock-cli)) that wraps the Management API, allowing you to work with your dashboard resources from the command line.
- [Bulk endpoints](/reference#bulk-endpoints) that allow you to upsert large amounts of data in a single API request (more on specific endpoints below).

<Callout
  emoji="🚸"
  text={
    <>
      <strong>Inline recipient identification.</strong> While the following
      steps outline a suggested order for migrating individual resource types
      into Knock based on your existing Courier integration, it’s helpful to
      note that Knock also supports{" "}
      <a href="/managing-recipients/identifying-recipients#inline-identifying-recipients">
        inline identification
      </a>{" "}
      of recipients in order to allow you to upsert recipients as you are
      performing other actions like triggering a workflow or creating
      subscriptions. Your approach may vary depending on your specific
      requirements.
    </>
  }
/>

We recommend migrating data into Knock in the following order to ensure that certain resources which are dependencies of other resources are migrated first:

<Steps titleSize="h3">
  <Step title="Configure your integrations">
    You’ll want to configure your Channels prior to migrating any workflows so that you can set the correct delivery methods for each of your notifications.

    You can do this by navigating to **Integrations** > **Channels** in your Knock dashboard.

  </Step>
  <Step title="Build workflows">
    Next, you can begin migrating Automations and Notification Templates into Knock Workflows.

    While you cannot request Courier Automations definitions via API, you can access a JSON representation of each Automation by navigating to the <a href="https://app.courier.com/assets/automations" target="_blank">Automations</a> section of your Courier dashboard, selecting the relevant automation, then clicking the “Code” button in the top navigation bar.

    Unfortunately, you also cannot export the message content of your notification templates from Courier. However, you _can_ request the delivery routing logic for your notifications from the Courier API and use this information to reconstruct your Workflows in Knock.

    Knock’s environment model means that you’ll be upserting all of your Workflows and other dashboard resources to your Development environment, where you’ll commit and then promote changes to higher environments (like Production). Read more [here](/concepts/environments).

    You can assign one or more [categories](/concepts/workflows#workflow-categories) to your workflows. These can be used to power recipient preferences (which we will cover in more detail below) and are roughly similar to Courier’s <a href="https://www.courier.com/docs/platform/preferences/preferences-editor/#subscription-topics" target="_blank">subscription topics</a>.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/notifications/get-notifications" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/notifications" />
          </a>
          <a href="https://docs.knock.app/mapi#workflows-update" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://control.knock.app/v1/workflows/:workflow_key" />
          </a>
          <a href="https://docs.knock.app/mapi#email-layouts-upsert" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/email_layouts/:key" />
        </a>
        <a href="https://docs.knock.app/mapi#partials-upsert" target="_blank" style={{textDecoration: 'none'}}>
          <Endpoint method="PUT" path="https://control.knock.app/v1/partials/:partial_key" />
        </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Import translation files">
    Next, you can migrate any translation files that are required to power your notifications. If you're already using translations in Courier, you should be able to use the same `.po` files in Knock.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/translations/get_translation/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/translations/:domain/:locale" />
          </a>
          <a href="https://docs.knock.app/mapi#translations-upsert" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://control.knock.app/v1/translations/:locale_code" />
          </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Add tenants">
    The next step is to migrate Tenants and Brands from Courier to Knock. Remember that in Knock, tenant-specific branding is stored as a property of a Tenant rather than as a separate resource.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/tenants/get-tenants/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/tenants" />
          </a>
          <a href="https://www.courier.com/docs/reference/brands/list-brands/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/brands" />
          </a>
          <a href="https://docs.knock.app/reference#set-tenant" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://api.knock.app/v1/tenants/:id" />
          </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Migrate users">
    Migrating your users and their data will be one of the most important parts of a transition from Courier to Knock. There are a few key points to be aware of as you plan this part of your migration:
      - Courier’s <a href="https://www.courier.com/docs/reference/profiles/" target="_blank">Profiles API</a> does not include an endpoint to list all users, so you’ll need to export them one at a time.
      - Knock uses the concept of [environments](/concepts/environments) to ensure logical separation of your data between local, staging, and production environments. This means that recipients and preferences created in one environment are never accessible to another. Your data for production users should be migrated into your Production environment in Knock.
      - Knock offers several different ways of “identifying” user data into our systems, and the best approach for you may differ depending on your use case. You can read more about the various approaches [here](/managing-recipients/identifying-recipients).

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/profiles/by-id/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/profiles/:user_id" />
          </a>
          <a href="https://docs.knock.app/reference#identify-user" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://api.knock.app/v1/users/:user_id" />
          </a>
          <a href="https://docs.knock.app/reference#bulk-identify-users" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="POST" path="https://api.knock.app/v1/users/bulk/identify" />
          </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Object subscriptions">
    [Subscriptions](/concepts/subscriptions) in Knock are an extension of [Objects](/concepts/objects) (a special type of non-user notification recipient). In order to migrate your List subscriptions from Courier to Knock, you’ll need to:
      - Export all Lists and their subscribers from Courier.
      - Create a new Object in Knock for each one of these Lists. Objects are organized into [collections](/concepts/objects#sending-object-data-to-knock) that represent the category or type of resource that they’ll be notifying.
      - Subscribe the appropriate users to each of these new Objects.

    Knock offers several bulk endpoints that can be used to optimize this data upsert with only a few API calls.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/lists/list/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/lists" />
          </a>
          <a href="https://www.courier.com/docs/reference/lists/subscriptions/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/lists/:list_id/subscriptions" />
          </a>
          <a href="https://docs.knock.app/reference#set-object" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://api.knock.app/v1/objects/:collection/:id" />
          </a>
          <a href="https://docs.knock.app/reference#bulk-set-objects" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/bulk/set" />
          </a>
          <a href="https://docs.knock.app/reference#add-subscriptions" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/:id/subscriptions" />
          </a>
          <a href="https://docs.knock.app/reference#bulk-add-subscriptions" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="POST" path="https://api.knock.app/v1/objects/:collection/bulk/subscriptions/add" />
          </a>
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Preferences">
    At this point, you’re ready to migrate all of your users’ notification [preferences](/preferences/overview) to Knock. If you’re currently using User Preferences in Courier, you should be able to map your users’ settings to your new Knock resources in order to power your preference center.

    <AccordionGroup>
      <Accordion title="Relevant endpoints">
          <a href="https://www.courier.com/docs/reference/user-preferences/list-all-user-preferences/" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="GET" path="https://api.courier.com/users/:user_id/preferences" />
          </a>
          <a href="https://docs.knock.app/reference#set-preferences-user" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="PUT" path="https://api.knock.app/v1/users/:user_id/preferences/:id" />
          </a>
          <a href="https://docs.knock.app/reference#bulk-set-preferences" target="_blank" style={{textDecoration: 'none'}}>
            <Endpoint method="POST" path="https://api.knock.app/v1/users/bulk/preferences" />
          </a>
      </Accordion>
    </AccordionGroup>

  </Step>
</Steps>


## Modeling Users, Objects, and Tenants
Learn how to map your application's data model into Knock.
---
title: Modeling Users, Objects, and Tenants in Knock
description: Learn how to map your application's data model into Knock.
section: Guides
---

In this guide, we’ll cover some best practices in modeling users, tenants, and objects in Knock. Since Knock is a set of flexible abstractions, there are many possible ways to map these concepts in Knock to entities in your own application, but this guide will use examples to help you with this decision-making process.

To do this, we’ll use an example collaboration app called Collab.io that consists of users, workspaces, projects, and alerts.

<Image
  src="/images/guides/modeling-users-objects-and-tenants/app-overview-new.png"
  width="1576"
  height="2212"
  className="rounded-md mx-auto border border-gray-200"
  alt="Collab.io app overview"
/>

## Users in Knock

Users in Knock are the most straightforward concept to explain in this guide because users in your application will map directly to users in Knock. Users in Knock are identified with a unique `id`, which in most cases should be the same `id` that you use to identify them in your application.

<Image
  src="/images/guides/modeling-users-objects-and-tenants/user-modeled-new.png"
  width="2152"
  height="1848"
  className="rounded-md mx-auto border border-gray-200"
  alt="users modeled as users"
/>

Users can have any number of custom properties associated with them, and [Knock reserves a number of optional properties](/concepts/users#optional-attributes) like `email`, `name`, `phone_number`, `timezone`, and `avatar` that are used as defaults across different message delivery channels.

```javascript title="Example user modeled as an Knock User"
{
  "id": "user_1234567890",
  "name": "Dummy User",
  "email": "dummy@example.com",
  "plan_type": "professional_2024",
  "updated_at": "2021-03-07T12:00:00.000Z",
  "created_at": null,
  "__typename": "User"
}
```

You can sync these properties with Knock through a process called [identification](https://docs.knock.app/managing-recipients/identifying-recipients).

## Objects in Knock

[Objects](/concepts/objects) in Knock are a flexible abstraction that you can use to send notifications to non-user recipients. You can also represent relationships between these non-user recipients and users via [Subscriptions](/concepts/subscriptions).

Let’s look at some non-user recipient use cases first.

### Non-user recipients

These non-user recipients can include things like a Slack integration or a webhook destination. Objects are like a NoSQL data store that allows you to map resources from your application into Knock. Objects in Knock live inside of collections and are identified with an id that’s unique to that collection.

#### A webhook destination

The `alert` entities inside of Collab.io exist to send webhooks to a downstream service when certain events are triggered inside of a project. To store this entity in Knock, you can create an Object with the id of `alert_URJXQKT1` inside of the `alerts` collection.

<Image
  src="/images/guides/modeling-users-objects-and-tenants/alert-modeled-new.png"
  width="2152"
  height="1848"
  className="rounded-md mx-auto border border-gray-200"
  alt="alerts modeled as objects"
/>

Since an Object can store any number of custom properties, you can also include values for `url` and `signingKey` along with any other data you might need when sending a webhook event or listing these alerts in your application’s UI.

```javascript title="Example alert modeled as an Object"
{
   "__typename": "Object",
   "collection": "alerts",
   "created_at": null,
   "id": "alert_URJXQKT1",
   "properties": {
       "description": "Project event destination",
       "events": [
           "project:info",
           "project:alert"
       ],
       "name": "Project alerts",
       "signingKey": "1888e28c-67ce-4f4c-be74-9ab8896785e4",
       "url": "https://hkdk.events/m3vdn670twnfs7"
   },
   "updated_at": "2024-07-01T21:20:10.538Z"
}
```

When you trigger a workflow with this object as a recipient, you can use the `url` and `signingKey` properties to generate a secure webhook request. Using the `events` array, you can store event subscriptions directly on the Object and filter out webhook events using a [step condition](https://docs.knock.app/designing-workflows/step-conditions). To learn more about using Objects and webhooks, you can read [our guide on creating customer facing webhooks](https://docs.knock.app/guides/customer-webhooks).

#### A Slack integration

The `project` entities in Collab.io are the main surface areas for collaboration in the application and generate several types of notifications. Let’s assume that users can map individual projects to Slack channels in a shared workspace so that new comments get sent to a particular channel.

To map this entity to Knock, you would create an Object with the id of `project_1YQ4XR18` inside of the `projects` collection.

<Image
  src="/images/guides/modeling-users-objects-and-tenants/project-modeled-new.png"
  width="2152"
  height="1848"
  className="rounded-md mx-auto border border-gray-200"
  alt="projects modeled as objects"
/>

The Object which represents that `project` might look like this:

```javascript title="Example project modeled as an Object"
{
   "__typename": "Object",
   "collection": "projects",
   "created_at": null,
   "id": "project_1YQ4XR18",
   "properties": {
       "name": "New product launch"
   },
   "updated_at": "2024-06-20T18:37:43.500Z"
}

```

Unlike the webhook example, where we used custom properties on the Object to power a downstream notification using the webhook channel, channels like Slack look for connection information in a special property called [channel data](https://docs.knock.app/managing-recipients/setting-channel-data).

Details like the `channel_id` and `access_token` are stored on the Object’s channel data, which you can see in the example below:

```javascript title="Example channel data for a Slack channel"
{
  "__typename": "ChannelData",
  "channel_id": "e8bbc2cc-5195-4a41-a247-f44ffcdc874f",
  "data": {
    "connections": [
        {
            "access_token": "xoxo-bdade7f76ad767ad676gg6767",
            "channel_id": "C06GCKH3E68",
            "incoming_webhook": null,
            "user_id": null
        }
    ],
    "token": null
  }
}
```

When you use the `project_1YQ4XR18` object as a recipient in a workflow with a Slack channel step, Knock automatically looks for channel data on the object to provide the necessary details to deliver the notification.

```javascript title="Triggering a workflow for an object recipient"
await knock.workflows.trigger("new-comment", {
  recipients: [{ collection: "projects", id: "project_1YQ4XR18" }],
  actor: "user_FE5WFU3D"
  data: {
    comment: "Does anyone have an update on this product launch?"
  },
});
```

### Subscriptions

In addition to acting as non-user recipients, Objects also allow you to express a relationship to groups of users via [Subscriptions](https://docs.knock.app/concepts/subscriptions). Object subscriptions are great for use cases where you want to notify a group of users in bulk, like a contact list, or fan out to all the subscribers or a particular topic. In more advanced implementations, you can also [model hierarchies using objects and subscriptions](https://docs.knock.app/concepts/subscriptions#modeling-nested-subscription-hierarchies), which should give you more flexibility in fan-out operations.

Let’s look at an example of how you can subscribe a Collab.io user to updates on a `project`.

First, you need to create a subscription between the `user` and the `project`, and add any custom properties you want stored on the subscription. You can access subscription properties for recipients in your message templates using the `recipient.subscription` property:

```javascript title="Creating a subscription between a user and a project"
await knock.objects.addSubscriptions("projects", "project_1YQ4XR18", {
  recipients: ["user_JG9NGAJQ"],
  properties: {
    // Optionally set other properties on the subscription for each recipient
  },
});
```

Finally, to send a message to all recipients, you trigger a workflow using the `project_1YQ4XR18` object as a recipient:

```javascript title="Triggering a fan out to object subscribers"
await knock.workflows.trigger("new-comment", {
  recipients: [{ collection: "projects", id: "project_1YQ4XR18" }],
  actor: "user_FE5WFU3D"
  data: {
    comment: "Does anyone have an update on this product launch?"
  },
});
```

When this workflow is triggered, Knock will generate individual workflow runs for the object itself AND for each of the object’s subscribers.

If you recall from the previous step, there is also some Slack channel data stored on `project_1YQ4XR18` in Knock, and the `workflow.trigger` code snippet above is also used in that example. This is why Knock can be so powerful in simplifying notification logic.

In practice, that means the first workflow run using the `project` object can generate a Slack notification, and all of the following workflow runs can notify individual recipients on another channel like email or in-app messaging.

## Tenants in Knock

[Tenants](/concepts/tenants) in Knock are a concept that allow you to segment your users and their messages. Most SaaS applications have some concept that is similar to “accounts,” “organizations,” “workspaces,” or “groups.” Under the hood, Tenants are a system-level Object collection called `$tenants`, so you can operate on them the same way you would an Object. You can set custom properties and subscribe users to them.

In Collab.io, tenants are modeled as `workspaces`, which contain `projects` and `alerts`. You can create a corresponding Tenant in Knock using the same id that you use in your application:

<Image
  src="/images/guides/modeling-users-objects-and-tenants/tenants-modeled-new.png"
  width="2152"
  height="1848"
  className="rounded-md mx-auto border border-gray-200"
  alt="workspaces modeled as tenants"
/>

Tenants in Knock are loosely coupled to your users and objects, which means Knock does not know anything about the relationship between your users and tenants.

Instead, you need to tell Knock that a particular workflow run belongs to a particular tenant when triggering a workflow. This means that you have less data to synchronize to Knock, and the risk of drift between what's current in your system and what's reflected in Knock is reduced.

```javascript title="Tagging a workflow run with a tenant"
await knock.workflows.trigger("new-comment", {
  recipients: [{ collection: "projects", id: "project_1YQ4XR18" }],
  actor: "user_FE5WFU3D"
  data: {
    comment: "Does anyone have an update on this product launch?"
  },
 tenant: "workspace_B80E71BI"
});
```

Tagging messages with a particular tenant can help you segment your notifications and [apply per-tenant branding and preferences.](/concepts/tenants#guides-for-using-tenants)

Tenants are also useful for helping you [scope the in-app feed](/concepts/tenants#scoping-in-app-feeds) to messages about a certain workspace or organization.



---

# Integrations

## Overview


# Sources

## Overview
Learn how to power your Knock notification system with customer data platforms, reverse ETLs, and your data warehouse.
---
title: Sources in Knock
description: Learn how to power your Knock notification system with customer data platforms, reverse ETLs, and your data warehouse.
section: Integrations > Customer data platforms
layout: integrations
---

With Knock sources, you can integrate customer data platforms (CDPs) such as Segment and Rudderstack or reverse ETL platforms such as Hightouch and Census with Knock to trigger notification workflows, identify users, and automate other actions.

In general, each platform we support can do the following within Knock:

- Trigger workflows
- Identify (and update) users

Here are a few reasons why you might want to integrate a source with Knock to power your notification system, rather than making direct calls to the Knock API:

- **Minimize engineering customization.** If you already identify and track users with a customer data platform (CDP), you can import your users and events in minutes. Once your CDP is integrated with Knock, you can easily build notification workflows without needing time from engineering.
- **Ensure consistency.** CDPs make it easy to keep customer data synchronized between services, including Knock. Email, name, and other user trait updates can flow seamlessly into Knock without any engineering work.

## Concepts

### Sources

A source is any platform that can pass event and/or user data into Knock. These can be CDPs (such as [Segment](https://segment.com) and [Rudderstack](https://rudderstack.com)) or reverse ETLs (such as [Hightouch](https://hightouch.com/) and [Census](https://www.getcensus.com/).) The incoming events from these services can be used to orchestrate actions in Knock such as creating/updating users and triggering workflows.

Knock currently supports the following sources:

- [Segment](/integrations/sources/segment)
- [Rudderstack](/integrations/sources/rudderstack)
- [Jitsu](/integrations/sources/jitsu)
- [Freshpaint](/integrations/sources/freshpaint)
- [Hightouch](/integrations/sources/hightouch)
- [Census](/integrations/sources/census)
- [Polytomic](/integrations/sources/polytomic)
- [HTTP](/integrations/sources/http) (a generic HTTP endpoint for accepting events)

_Need us to support another platform? [Let us know!](mailto:support@knock.app?subject=Integration%20Source%20Request)_

You can configure sources from the **Integrations** > **Sources** page for your account. Initial creation of a source is managed at the account-level of your Knock account, though you'll configure any specific events and their workflow triggers within your Knock environments.

<Image
  src="/images/integrations/sources/sources-location.png"
  alt="A screenshot of where to find the Integrations - Sources page for your account"
  width={500}
  height={266}
  className="rounded-md mx-auto border border-gray-200"
/>

### Per-environment source configuration

Each source has a unique configuration for every Knock environment in your account.
This makes it possible to connect your Segment development environment to your Knock development environment.
If you click on a source, you will see each environment configuration for that source.

<Image
  src="/images/integrations/sources/source-env-config.png"
  alt="A view of the environment configurations for a source in a Knock account"
  width={2996}
  height={772}
  className="rounded-md mx-auto border border-gray-200"
/>

### Events

Knock tracks every event sent from a source. Although each source has its own event format,
Knock will translate the incoming events from each source into a common format that includes the following fields:

- `user_id`. The ID of the user performing a given action (may not be set if a user has not been identified yet).
- `data`. The primary contents of the event, e.g. for a Segment `track` with some associated `properties`, Knock would use those `properties` to set the `data` field for the event.
- `event`. The original event, as originally received by Knock.

### Workflow triggers

When Knock receives an event from an integration source, it will check for any workflows that have been configured to be triggered by that event in that environment.

You can have any number of workflows triggered by each event. If there is no workflow configured to be triggered by that event, the event is logged but no action is taken.

After configuring a source in Knock and in the source itself (e.g. adding Knock as a destination in your CDP), events will start to flow into your Knock environment.

You can then select an event and connect it to a workflow as its trigger.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">
        For workflow triggers, no more than 1000 recipients can be included in
        each event.
      </span>{" "}
      If you exceed this limit, Knock will not process your workflow trigger and
      instead generate an error log. <br />
      <br />
      If you need to manage a large list of recipients you might want to
      consider using our{" "}
      <a href="/concepts/subscriptions">subscriptions feature</a> to have Knock
      manage the set of recipients who need to be notified instead.
    </>
  }
/>

## Identifying users

For sources that support identifying users (such as Segment or Rudderstack with their `identify` calls), each environment configuration for that source includes a setting to enable or disable identifying users. After creating an integration source, enable identifying users for that environment.

Note that Knock will correctly map `name`, `email`, `avatar`, and `phone` properties from Segment and Rudderstack `identify` calls into Knock's user data model. All other tracked properties of a user will be stored as additional custom properties on the Knock user object, and can be used in templates and other parts of Knock that rely on user properties.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Remember:</span> if you send Knock a source
      event that includes a recipient that has not yet been identified in Knock,
      our system will not generate a workflow run for that user. <br />
      <br />
      For use cases such as new signup events, where events will often reach
      Knock before identify calls, consider{" "}
      <a href="#inline-identify-users-in-a-source-event">
        inline identification
      </a>{" "}
      of users in your source events.
    </>
  }
/>

### Inline identify users in a source event

<Callout
  emoji="☝️"
  text={
    <>
      <span className="font-bold">Note:</span> Inline identification is not
      supported by our{" "}
      <a href="/send-notifications/testing-workflows#the-workflow-test-runner">
        workflow test runner
      </a>
      , which can only trigger test runs for existing users. To test inline identification
      with a source event, you should send a test event from your configured source.
    </>
  }
/>

In cases where you send a source event to Knock with recipients that may not yet have been identified into our system, it's good practice to [inline identify](/managing-recipients/identifying-recipients#inline-identifying-recipients) your users. By inline identifying your users within your source events, you ensure that those users are identified in Knock when your event triggers a workflow.

As an example, take the user-signed-up event below. We're currently mapping the `properties.recipients` field to the `recipients` field of our workflow in Knock. If we send this event to Knock before the user with id `sam10` has been identified, the user will not be notified.

```json title="A source event without inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "source-event-test-123",
  "properties": {
    "recipients": ["sam10"],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

To ensure that the user is notified, we'd change the id reference in `recipients` to a complete user object, as in the example below. This way Knock has all the information it needs to identify the user during workflow runtime.

```json title="A source event with inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "source-event-test-123",
  "properties": {
    "recipients": [
      {
        "id": "sam10",
        "name": "Sam Seely",
        "email": "sam@example.com"
      }
    ],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

You can learn more about inline identification in [our guide on identifying recipients](/managing-recipients/identifying-recipients).

## Event idempotency

By default, Knock will process every valid event received from your source. But, you can enable idempotency checks to deduplicate events that have already been received and processed by Knock. This is useful if you know your source may send duplicate events.

<Callout
  emoji="💡"
  text={
    <>
      <strong>
        The default idempotency window for Knock Sources is 24 hours.
      </strong>{" "}
      If you're interested in configuring a different idempotency window for
      your account, please contact us at{" "}
      <a href="mailto:support@knock.app">support@knock.app</a>.
    </>
  }
/>

### Configuring idempotency checks

You can enable source event idempotency checks at any time from the "Settings" tab for your source environment configuration.

<Image
  src="/images/integrations/sources/source-event-idempotency.png"
  alt="A screenshot of where to configure idempotency for your Source."
  width={800}
  height={400}
  className="rounded-md mx-auto border border-gray-200"
/>

Once enabled, Knock will start parsing idempotency keys from your source events for use in deduplication checks. Knock will use an optional, unique attribute made available by your source provider. These attributes are:

- **Segment:** `messageId`
- **Rudderstack:** `messageId`
- **HTTP:** `messageId`

Events without an idempotency key attribute will be processed like normal.

```json title="An example source event from Segment with a valid idempotency key."
{
  "type": "track",
  "event": "user.created",
  "messageId": "some-id-from-source",
  "properties": {
    "id": "user-1",
    "email": "user-1@example.com"
  }
}
```

Your idempotency keys must be valid strings no more than 255 characters in length. If an invalid key is found, Knock will still ingest your source event, but it will not attempt to execute your event idempotently. In addition, Knock will drop the invalid idempotency key and you will not see it appear in your event logs.

### How Knock handles idempotent events

When Knock executes a source event with an idempotency key, it will first check to see if a preceding execution should be replayed. Knock will find a preceding execution if it is recorded within the idempotency window with the same:

- Idempotency key value
- Event type
- Integration source configuration
- Knock environment in your account

If no preceding execution is found, Knock will execute your event like normal and record _that_ execution for future replay by the same idempotency key. However, if Knock fails to execute your source event, it will not record the execution. Knock will only record successful event executions for idempotent replay.

If Knock replays an event via an idempotency check, you will still see an event log for that execution. However, the log will not have any actions associated and Knock will label it as idempotent.

## Logging

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">
        Data subject to retention policy enforcement.
      </span>{" "}
      See the{" "}
      <a href="/manage-your-account/data-retention">data retention docs</a> for
      more details on how Knock enforces this policy.
    </>
  }
/>

### Event logs

Event logs show the contents of each event sent into Knock.

### Action logs

Action logs describe what (if any) action was taken after an event was received. Action logs are a helpful starting point when troubleshooting workflows or auditing what actions Knock has taken for any given event.


## Segment
Learn how to connect your Segment events to Knock to power your product notifications.
---
title: How to use Segment events to power Knock
description: Learn how to connect your Segment events to Knock to power your product notifications.
section: Integrations > Sources
layout: integrations
---

This guide covers using Segment as a [Knock source](/integrations/sources/overview) to bring track and identify event data from Segment into Knock to power your notifications.

Knock also provides a separate [Segment extension](/integrations/extensions/segment) for sending Knock notification data into Segment for use in your downstream tools.

## Getting started

When using Segment as a Knock source, you also need to configure Knock as a [destination](https://segment.com/docs/connections/destinations/) within Segment. This means you can use events coming through Segment to power actions in Knock, such as triggering a workflow.

To start routing your Segment events to Knock, click the "Create Source" button in the Knock dashboard under the **Integrations** > **Sources** section and select Segment. Once created, select it from the list to navigate to the environment configuration page, where you can copy the unique webhook destination URLs for each environment you have configured in Knock.

## Configure a Knock destination in Segment

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Use webhooks to connect to Knock.</span> Knock
      does not have a first-party integration with Segment, so you will not find
      us in Segment's destination catalog. Instead, you'll configure the
      connection to Knock via a webhook destination as described below.
    </>
  }
/>

<Steps>
  <Step title="Add webhook destination in Segment">
    In your Segment workspace, navigate to the **Destinations** tab and click "Add Destination." From here, search for **Webhooks** or navigate to **Raw Data** in the sidebar and click the "Webhooks (Actions)" option. This is the destination type we'll use for Knock.
    <Image 
      src="/images/integrations/sources/configure-webhooks.png" 
      width={2188}
      height={1236}
      className="rounded-md mx-auto border border-gray-200"
      alt="Configure webhooks"
    />  
  </Step>
  <Step title="Configure webhook">
    Click the "Configure Webhooks (Actions)" button in the top right to enter the setup flow to configure your webhook:
    - Select the data source you'd like to receive events from and click "Next."
    - Give a name to the destination, like "Knock," and keep the "Fill in settings manually" option selected, then click "Create destination."
  </Step>
  <Step title="Save changes">
    Now you'll see a **Settings** page. Check the "Enable Destination" button and click "Save changes."
  </Step>
  <Step title="Add mapping">
    At the top of the page, navigate to the **Mappings** tab. Click "New Mapping," and under Actions, click "Send".

    You will then be directed to a form to configure the webhook:
    - Select the events to map and send to Knock. If you'd like to send all events to Knock, you can add the condition **Event type is Track,** a condition for **Event type is Identify,** and change the top operator to **any** instead of all:
        <Image
          src="/images/integrations/sources/webhooks-select-events.png"
          width={1698}
          height={874}
          className="rounded-md mx-auto border border-gray-200"
          alt="Select event conditions"
        />
    - You can load a test or sample event; either way, ensure it matches your trigger conditions (Segment will warn you if it doesn't).
    - Click "Test Mapping" to send the loaded or sample event from the previous step to Knock.
    - If the test is successful, click "Save" to exit the form, and then click to enable the mapping you just created.

  </Step>
</Steps>

## Viewing Segment track events in Knock

Once your Segment destination is set up, all events you trigger from the Segment source will be forwarded to Knock. Unique events will appear in your list of events under the Source so that you can set up triggers for your workflows.

From the source environment configuration page, click the "View in environment" button on one of the source environments. You'll be taken to the Segment source in the environment you selected, and you should see events sent. If you don't, try clicking the refresh button at the top of the list to refetch any incoming events.

## Triggering workflows from received events

You can add a **track event** as a trigger to your workflow directly from the workflow builder. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you'll be able to select the event and map its properties into the data the workflow needs.

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Using event data in workflow triggers.</span> When connecting an event to a workflow, you can use any data available within the event payload in the workflow's parameters. For example, if your payload looks like this:
      <div className="mt-2 mb-2">
        <pre>
          <code>{eventPayload}</code>
        </pre>
      </div>
      and you wanted the commenter from the event to appear as the{" "}
      <code>actor</code> in the workflow, then in the{" "}
      <code>actor</code> field, you would write{" "}
      <code>properties.commenter.id</code> to supply their ID as the actor.
      <br/><br/>
      If you wanted to supply the event's <code>userId</code> as the workflow's recipient,
      you'd write <code>userId</code> in the <code>Recipients</code> field.
      <br/><br/>

      <span className="font-bold">Note:</span> when you edit message templates,
      all <code>properties</code> are available to you as data variables. You can access them directly in your templates without
      the <code>properties.</code> prefix.
    </>

}
/>

[Read more on configuring workflow triggers](/integrations/sources/overview#workflow-triggers)

## Disabling a trigger

Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, you can go to the trigger page and toggle its status to "Inactive." Keep in mind that this will disable that trigger for the current environment only. When you're ready to trigger the workflow again, you can set it back to "Active."

## Enabling Identify events

When Segment sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `id`, `email`, `phone`, `avatar`, `name`, and any other custom properties.

To enable the handling of identify events, open the settings for the source in the environment. You can then enable or disable handling identify events accordingly.

<Image
  src="/images/integrations/sources/segment-identify.png"
  width={1954}
  height={442}
  className="rounded-md mx-auto border border-gray-200"
  alt="A screenshot of how to toggle Knock handling Segment identify calls"
/>

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Remember:</span> if you send Knock an event
      that includes a recipient not yet identified in Knock, our system will not
      generate a workflow run for that user. <br />
      <br />
      For use cases such as new signup events, where events often reach Knock
      before identify calls, consider{" "}
      <a href="#inline-identify-users-in-a-segment-event">
        inline identification
      </a>{" "}
      of users in your Segment events.
    </>
  }
/>

## Inline identify users in a Segment event

<Callout
  emoji="☝️"
  text={
    <>
      <span className="font-bold">Note:</span> Inline identification is not
      supported by our{" "}
      <a href="/send-notifications/testing-workflows#the-workflow-test-runner">
        workflow test runner
      </a>
      , which can only trigger test runs for existing users. To test inline identification
      with a source event, you should send a test event from Segment.
    </>
  }
/>

In cases where you send a Segment event to Knock with recipients who may not yet have been identified in our system, it's good practice to [inline identify](/managing-recipients/identifying-recipients#inline-identifying-recipients) your users. By inline identifying your users within your Segment events, you ensure that those users are identified in Knock when your event triggers a workflow.

As an example, take the user-signed-up event below. We're currently mapping the `properties.recipients` field to the `recipients` field of our workflow in Knock. If we send this event to Knock before the user with id `sam10` has been identified, the user will not be notified.

```json title="A Segment event without inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "segment-test-message-123",
  "properties": {
    "recipients": ["sam10"],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

To ensure the user is notified, we'd change the id reference in `recipients` to a complete user object, as in the example below. This way, Knock has all the information it needs to identify the user during workflow runtime.

```json title="A Segment event with inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "segment-test-message-123",
  "properties": {
    "recipients": [
      {
        "id": "sam10",
        "name": "Sam Seely",
        "email": "sam@example.com"
      }
    ],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

You can learn more about inline identification in [our guide on identifying recipients](/managing-recipients/identifying-recipients).

## Video walkthrough

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.youtube.com/embed/Fj8wl6TNbrI?si=D5Wt6etwiahGvKs3"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>

<br />

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use a single Segment event to trigger multiple workflows?">
    Yes. Under the **Developers** > **Sources** section in your Knock dashboard,
    select an event from Segment to view a list of triggers configured for that
    event. Then, in the upper right-hand corner, click the "Create workflow
    trigger" button to select the additional workflow you want this event to
    trigger, then click "Create." You can then make any changes to the schema
    mapping before saving and committing the workflow with its new trigger.
  </Accordion>
  <Accordion title="Can I use multiple different Segment events to trigger the same workflow?">
    Yes. To do so, go to the **Developers** > **Sources** section in your Knock
    dashboard, select an event, and then click the "Create workflow trigger"
    button in the upper right-hand corner. You will choose the same workflow
    from the **Create workflow trigger** modal.
  </Accordion>
</AccordionGroup>


## RudderStack
Learn how to connect your RudderStack events to Knock to power your product notifications.
---
title: How to integrate RudderStack to Knock
description: Learn how to connect your RudderStack events to Knock to power your product notifications.
section: Integrations > Sources
layout: integrations
---

## Video walkthrough

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.loom.com/embed/ef62371265bb4725a88b0607cba6da8b"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>

## Getting started

Knock is a **RudderStack Destination**, which means you can use events coming through RudderStack to power actions in Knock, such as triggering a workflow.

You can start routing your RudderStack events to Knock by creating a source of type "RudderStack" in the dashboard. From here, you'll be taken to the environment configuration page for the source which will give you unique URLs for each environment you have configured in Knock.

You'll copy this URL and use it to let RudderStack know where to send events.

## Configuring RudderStack

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Use webhooks to connect to Knock.</span> Knock
      does not have a first-party integration with RudderStack, so you will not
      find us in the list of destinations. Instead, you'll configure the
      connection to Knock via a webhook destination as described below.
    </>
  }
/>

You will need to create a RudderStack destination for each Knock environment that you want to receive events from RudderStack.

1. In your RudderStack workspace, navigate to the "Destinations" page and click "New destination." Search for and select "Webhook"
2. Give the destination a name (e.g. "Knock &lt;environment name&gt;") and click "Continue"
3. Optionally, choose the sources you want to route into this destination. Then, click "Continue"
4. Paste the URL from the Knock dashboard for the Knock environment you want to receive events from RudderStack. Make sure the "URL Method" selected is POST. No other headers or settings are required. Click "Continue"
5. Transformations may be configured as needed, but are typically not required. Click "Continue" to finalize the RudderStack destination

## Viewing RudderStack track events in Knock

Once your RudderStack destination is set up all events you trigger from the RudderStack source will be forwarded to Knock. Unique events will appear in your list of events under the Source so that you can set up triggers for your workflows.

From the source environment configuration page click the "View in environment" button on one of the source environments. You'll be taken to the RudderStack source in the environment you selected and you should see events sent. If you don't, try clicking the refresh button on the top of the list to refetch any incoming events.

## Triggering workflows from received events

You can add a **track event** as a trigger to your workflow directly from the workflow builder. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you'll be able to select the event and map its properties into the data the workflow needs.

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Using properties.</span> To use any of the
      properties fields, you can access them with dot-syntax by prefixing them
      with <code>data.</code>. For example, if your payload looks like this:
      <div className="mt-2 mb-2">
        <pre>
          <code>{eventPayload}</code>
        </pre>
      </div>
      and you wanted the commenter from the event to appear as the{" "}
      <span className="font-bold">Actor</span> in the workflow, then in the{" "}
      <span className="font-bold">Actor</span> field you would write{" "}
      <code>data.commenter.id</code> to supply their ID as the actor.
    </>
  }
/>

[Read more on configuring workflow triggers](/integrations/sources/overview#workflow-triggers)

## Disabling a trigger

Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, you can go to the trigger page and toggle its status to "Inactive." Keep in mind that this will disable that trigger for the current environment only. When you're ready to trigger the workflow again, you can set it back to "Active."

## Enabling Identify Events

When RudderStack sends identify events, Knock will create and update user information accordingly. Knock will correctly map the `id`, `email`, `phone`, `avatar`, `name`, and any other custom properties over.

To enable handling of identify events, open the settings for the source in the environment. You can then enable or disable handling identify events accordingly.

<Image
  src="/images/integrations/sources/rudderstack-identify.png"
  width={1946}
  height={432}
  className="rounded-md mx-auto border border-gray-200"
  alt="A screenshot of how to toggle Knock handling RudderStack identify calls"
/>

## Inline identify users in a RudderStack event

<Callout
  emoji="☝️"
  text={
    <>
      <span className="font-bold">Note:</span> Inline identification is not
      supported by our{" "}
      <a href="/send-notifications/testing-workflows#the-workflow-test-runner">
        workflow test runner
      </a>
      , which can only trigger test runs for existing users. To test inline identification
      with a source event, you should send a test event from RudderStack.
    </>
  }
/>

In cases where you send a RudderStack event to Knock with recipients that may not yet have been identified into our system, it's good practice to [inline identify](/managing-recipients/identifying-recipients#inline-identifying-recipients) your users. By inline identifying your users within your RudderStack events, you ensure that those users are identified in Knock when your event triggers a workflow.

As an example, take the user-signed-up event below. We're currently mapping the `properties.recipients` field to the `recipients` field of our workflow in Knock. If we send this event to Knock before the user with id `sam10` has been identified, the user will not be notified.

```json title="A RudderStack event without inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "rudderstack-test-message-123",
  "properties": {
    "recipients": ["sam10"],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

To ensure that the user is notified, we'd change the id reference in `recipients` to a complete user object, as in the example below. This way Knock has all the information it needs to identify the user during workflow runtime.

```json title="A RudderStack event with inline identify"
{
  "event": "user-signed-up",
  "email": "sam@example.com",
  "userId": "sam10",
  "type": "track",
  "messageId": "rudderstack-test-message-123",
  "properties": {
    "recipients": [
      {
        "id": "sam10",
        "name": "Sam Seely",
        "email": "sam@example.com"
      }
    ],
    "account_id": "123"
  },
  "timestamp": "2023-05-23T21:49:54Z"
}
```

You can learn more about inline identification in [our guide on identifying recipients](/managing-recipients/identifying-recipients).

## Video walkthrough

This video is Segment-specific, but you can apply any of the portions within the Knock dashboard to RudderStack as well.

<div style={{ position: "relative", paddingBottom: "56.25%", height: 0 }}>
  <iframe
    src="https://www.youtube.com/embed/Fj8wl6TNbrI?si=D5Wt6etwiahGvKs3"
    frameBorder="0"
    allowFullScreen
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
  ></iframe>
</div>


## Hightouch
Learn how to power your Knock product notifications using synced data from your data warehouse using Hightouch.
---
title: How to integrate Hightouch with Knock
description: Learn how to power your Knock product notifications using synced data from your data warehouse using Hightouch.
section: Integrations > Sources
layout: integrations
---

## Getting started

Knock integrates with [Hightouch](https://hightouch.com) as a downstream destination to sync customer and event data from your data warehouse.

## Use cases

You can use our Hightouch integration to:

1. Sync customer data into Knock from your data warehouse (identify)
2. Trigger workflows from records added, changed, or removed in your data warehouse
3. Populate [Audiences](/concepts/audiences) with data from your data warehouse. Audiences can be used to trigger workflows or power conditional logic during workflow execution.

## Syncing customer data into Knock from Hightouch

You can use the [HTTP request destination](https://hightouch.com/docs/destinations/http-request) within Hightouch to sync your customer data from your data warehouse into Knock.

For this example, we're going to make a call to the [Knock API users identify endpoint](/reference#identify-user).

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note:</strong> you can also extend this technique to make other
      calls to the Knock API from your Hightouch models to sync object data or
      trigger workflows. Please{" "}
      <a href="mailto:support@knock.app?subject=Hightouch help">get in touch</a>{" "}
      if you'd like any additional help.
    </>
  }
/>

1. Create a new HTTP request destination and select your model to query from
2. Set an `Authorization` header, with the value set to `Bearer <your Knock secret API key>`. You can find your secret API key in [your dashboard](https://dashboard.knock.app) under **Developers** > **API keys**
3. Name your destination "Knock API"
4. Create a new sync with your Knock API destination
5. Select the types of events that should trigger, the most common case here is "Rows added"
6. Set the HTTP request method to `PUT` and the URL to `https://api.knock.app/v1/users/{{ row.user_id }}` where `{{ row.user_id }}` corresponds to the user identifier in the table
7. Select a "JSON" payload and "Use the JSON editor" to craft the request
8. Add at least a `name`, `email`, or `phone_number` field from your users table
9. For the rate limit, you can specify 60 requests per second
10. You'll likely want to "backfill" all of the available rows meaning that any existing data will also be synced to Knock
11. Click "Continue"
12. Select your sync frequency
13. Click "Finish"

An example configuration for your sync may look something like this:

```json title="Example sync configuration"
{
  "add": {
    "enabled": true,
    "method": "PUT",
    "url": "https://api.knock.app/v1/users/{{ row.user_id }}",
    "timeout": 30,
    "contentType": "application/json",
    "hasRateLimit": true,
    "bodyType": "template",
    "body": "{\n \"name\": \"{{ row.first_name }} {{ row.last_name }}\",\n \"email\": \"{{ row.email_address }}\",\n \"phone_number\": \"{{ row.phone_number }}\"\n}",
    "rateLimit": 60,
    "rateLimitTime": "second",
    "onError": "retryRequest",
    "retries": 3
  },
  "change": {},
  "remove": {},
  "skipFirstRun": false
}
```

## Syncing audiences into Knock from Hightouch

<Callout
  emoji="🚧"
  text={
    <>
      Our Hightouch audience integration is currently in beta. If you'd like
      early access, or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Hightouch audience integration">
        get in touch
      </a>
      .
    </>
  }
/>


## Census
Learn how to power your Knock product notifications using synced data from your data warehouse using Census.
---
title: How to integrate Census with Knock
description: Learn how to power your Knock product notifications using synced data from your data warehouse using Census.
section: Integrations > Sources
layout: integrations
---

## Getting started

Knock integrates with [Census](https://getcensus.com) as a downstream destination to sync customer and event data from your data warehouse.

<Callout
  emoji="🚧"
  text={
    <>
      Our Census integration is currently in beta. If you'd like early access,
      or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Census integration">
        get in touch
      </a>
      .
    </>
  }
/>

## Use cases

You can use our Census integration to:

1. Sync customer data into Knock from your data warehouse (identify)
2. Trigger workflows from records added, changed, or removed in your data warehouse
3. Populate [Audiences](/concepts/audiences) with data from your data warehouse. Audiences can be used to trigger workflows or power conditional logic during workflow execution.


## Polytomic
Learn how to power your Knock product notifications using synced data from your data warehouse using Polytomic.
---
title: How to integrate Polytomic to Knock
description: Learn how to power your Knock product notifications using synced data from your data warehouse using Polytomic.
section: Integrations > Sources
layout: integrations
---

## Getting started

Knock integrates with [Polytomic](https://polytomic.com) as a downstream destination to sync customer and event data from your data warehouse.

<Callout
  emoji="🚧"
  text={
    <>
      Our Polytomic integration is currently in beta. If you'd like early
      access, or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Polytomic integration">
        get in touch
      </a>
      .
    </>
  }
/>

## Use cases

You can use our Polytomic integration to:

1. Sync customer data into Knock from your data warehouse (identify)
2. Trigger workflows from records added, changed, or removed in your data warehouse


## Jitsu
Learn how to connect your Jitsu events to Knock to power your product notifications.
---
title: How to integrate Jitsu to Knock
description: Learn how to connect your Jitsu events to Knock to power your product notifications.
section: Integrations > Sources
layout: integrations
---

## Getting started

Knock integrates with [Jitsu](https://jitsu.com) as a downstream destination to sync customer and event data.

<Callout
  emoji="🚧"
  text={
    <>
      Our Jitsu integration is currently in beta. If you'd like early access, or
      this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Jitsu integration">
        get in touch
      </a>
      .
    </>
  }
/>

## Use cases

You can use our Jitsu integration to:

1. Sync customer data into Knock
2. Trigger workflows from track events


## Freshpaint
Learn how to connect your Freshpaint events to Knock to power your product notifications.
---
title: How to integrate Freshpaint to Knock
description: Learn how to connect your Freshpaint events to Knock to power your product notifications.
section: Integrations > Sources
layout: integrations
---

## Getting started

Knock integrates with [Freshpaint](https://freshpaint.io) as a downstream destination to sync customer and event data.

<Callout
  emoji="🚧"
  text={
    <>
      Our Freshpaint integration is currently in beta. If you'd like early
      access, or this is blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Freshpaint integration">
        get in touch
      </a>
      .
    </>
  }
/>

## Use cases

You can use our Freshpaint integration to:

1. Sync customer data into Knock
2. Trigger workflows from track events


## HTTP
Learn how to stream events to Knock to power your product notifications.
---
title: How to send events to an HTTP source to power Knock
description: Learn how to stream events to Knock to power your product notifications.
section: Integrations > Sources
layout: integrations
---

The HTTP source creates a generic event ingestion endpoint that you can use to stream events from your service, or a third-party platform into Knock. The events you stream into the HTTP source can then be used to trigger Knock notification workflows.

Knock can receive any structured event data via the HTTP source, as long as you can format JSON and make an HTTP request from the service that produces or consumes events.

## Getting started

To get started you can create a new HTTP source by going to **Integrations** > **Sources** and clicking "Create source." You'll have the opportunity to name the HTTP source and give it a description.

Once your source is created, you'll have a unique ingestion endpoint per environment to send events to. You can get each environment's endpoint by clicking the "Copy webhook destination URL" button.

## Sending event data

To start sending events to Knock, you'll need to structure a JSON payload that matches the event schema to the ingestion endpoint and submit the request via a `POST` action. A well-formed event payload will be accepted with a `204` response code.

You'll also need to send the following headers with your request:

```txt title="Request headers"
Content-Type: application/json
```

**Please note**: you'll need to send a single event at a time. There's currently no batch event ingestion endpoint.

## Event schema

Your events must be structured as JSON with the following schema:

| Name         | Type              | Description                                                                                                           |
| ------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `type`       | string (required) | The type of event to send. Must be set to `track`.                                                                    |
| `event`      | string (required) | The name of the event you're sending to Knock.                                                                        |
| `properties` | map               | A set of properties associated with the event.                                                                        |
| `userId`     | string            | An optional userId to be used as the recipient or actor for the triggered workflow.                                   |
| `messageId`  | string            | An optional unique identifier for the event message, to be used as a deduplication key.                               |
| `timestamp`  | string            | An optional ISO-8601 timestamp indicating when the event occurred. If omitted, will default to the time of ingestion. |

```json title="An example event payload"
{
  "type": "track",
  "event": "My event",
  "properties": {
    "foo": "bar"
  }
}
```

## Triggering workflows from received events

Received events can be configured as workflow triggers directly in the workflow editor. Click on the workflow's trigger step and change the type from "API" to "Source Event." Then you'll be able to select the event and map its properties into the data the workflow needs.

[Read more on configuring workflow triggers](/integrations/sources/overview#workflow-triggers)

## Disabling a trigger

Triggers are automatically enabled when you create them. If you want to stop an event from triggering a workflow, you can go to the trigger page and toggle its status to "Inactive." Keep in mind that this will disable that trigger for the current environment only. When you're ready to trigger the workflow again, you can set it back to "Active."

### Mapping workflow trigger properties

When creating workflow triggers from your events, you can optionally configure the schema mapping Knock will use to map your event properties into the corresponding workflow trigger properties.

To target any items under the `properties` key, prefix the schema mapping with `data.propertyKey`. As an example, if you have a property `properties.recipientId` you would map this as `data.recipientId`.

## Debugging events

You can see a log of all of the events received per source under **Developers** > **Sources** in the Knock dashboard under the "Logs" page for your configured source. You can also see any workflow triggers that were configured as part of the event ingestion, and any workflow runs that were triggered.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I send identify events through to the HTTP source?">
    No, the HTTP source only accepts events and not user identifies. Please use
    the [user identify API](/concepts/users) instead.
  </Accordion>
  <Accordion title="Can I identify recipients inline via track events that I send to the HTTP source?">
    Yes. You can use inline identification with the source events that you send
    to Knock according to the instructions
    [here](/integrations/sources/overview#inline-identify-users-in-a-source-event).
    You'll need to ensure that the schema mapping for your event maps the
    **Recipients** of your workflow to the same field where you provide the
    recipient object.
  </Accordion>
  <Accordion title="What's the rate limit Knock supports on the events endpoint?">
    There's no rate limit for the event ingestion endpoint, but we ask that if
    you're going to be sending more than 1,000 events per second you reach out
    to us first so that we can provision additional capacity.
  </Accordion>
  <Accordion title="Do you support ingesting batches of events?">
    Currently, no; the HTTP endpoint only accepts single events at a time.
  </Accordion>
</AccordionGroup>



# Email

## Overview
Learn how to send transactional email notifications with the Knock API.
---
title: Email notifications with Knock
description: Learn how to send transactional email notifications with the Knock API.
section: Integrations > Email
layout: integrations
---

Effortlessly design and deliver email notifications to downstream providers, without the need to keep HTML templates in your backend codebase.

## Features

- **Easy to get started, and extend**: Knock email notifications look great out of the box. We include sensible, well tested, default responsive styles so you can get up and running quickly across all major email clients. Check out the [Settings](/integrations/email/settings) page to learn about available configuration options.
- **Block based visual editor**: Don't want to write HTML? No problem! You can use our drag-and-drop visual editor to get started.
- **Fully flexible templates and styling**: If you need to write custom HTML or CSS you can drop down to a raw code editor to create your email messages. You're never constrained to the templates Knock provides.
- **CSS inlining**: By default, Knock will inline all CSS included with your emails to ensure maximum compatibility across email clients.
- **Text generation**: We'll automatically generate a text version of your emails, so you never need to write both HTML and text templates.
- **Multiple layouts**: We support any number of emails layouts that can "wrap" your email templates and provide styles and shared elements like headers and footers.
- **Attachments support**: It's easy to send attachments alongside your emails, just pass through some Base64 encoded data along with your `workflow.trigger` call and you're done!
- **Link and open tracking**: Capture link-click and email-open events right within your Knock account. For more details, see the [Knock link and open tracking guide](/send-notifications/tracking).

## Supported providers

Knock currently supports sending email notifications to the following email providers:

- [AWS SES](/integrations/email/aws-ses)
- [Mailersend](/integrations/email/mailersend)
- [Mailgun](/integrations/email/mailgun)
- [Mailjet](/integrations/email/mailjet)
- [Mailtrap](/integrations/email/mailtrap)
- [Mandrill](/integrations/email/mandrill)
- [Postmark](/integrations/email/postmark)
- [Resend](/integrations/email/resend)
- [Sendgrid](/integrations/email/sendgrid)
- [SMTP](/integrations/email/smtp)
- [Sparkpost](/integrations/email/sparkpost)

If you want us to add a new provider to this list, please let us know through the feedback button at the top of this page.


## Layouts
Learn more about how to use layouts with your email templates in Knock.
---
title: Email layouts
description: Learn more about how to use layouts with your email templates in Knock.
section: Integrations
layout: integrations
tags:
  [
    "precontent",
    "css",
    "layout",
    "styles",
    "design system",
    "button",
    "preview text",
    "branding",
    "email preview text",
  ]
---

In this guide we cover how to use email layouts and templates in Knock to send great looking notifications to your users.

## An intro to email layouts and templates in Knock

When you use Knock to power your email notifications, you use two main concepts to build the notifications that will be sent to your users: layouts and templates.

The **layout** typically includes the header and footer of your email, as well as any other HTML or CSS that will be used across all (or multiple) templates. You can think of your email layout as the "frame" of your email notifications, where you define the shared structure and styles once for all your email notifications so they can look and feel consistently without having to repeat them in every template.

The **template** is the actual body and content of your email. When you add an email step to a workflow, the content that you edit within the template editor is the template that will be wrapped by the layout mentioned above. Under the hood, Knock is injecting this template into the `{{content}}` variable of the email layout.

Here's an example of a transactional email we send at Knock, complete with the template content merged into the layout. The area shaded in green is the template. The area shaded in blue is the layout.

<Image
  src="/images/integrations/email/layouts/layout-template-example.png"
  width={1132}
  height={840}
  className="rounded-md mx-auto border border-gray-200"
  alt="An example of a layout and template within an email notification"
/>

Here's a quick overview of the system-level variables Knock provides for use in your layouts.

| Variable       | Description                                                                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`      | A notification template defined in an email channel step will be inserted into this variable. **This is a required variable, and must be present somewhere in every layout.** |
| `footer_links` | A list of footer links, as configured in the layout editor, will be injected into this variable. This is an optional variable and is not required in custom layouts.          |

## The Knock default layout

Your Knock account starts with a pre-built default layout. If you navigate to **Developers** > **Layouts** in the sidebar of your Knock dashboard, you'll find this default layout. This default layout will be used by all new email templates when they're initially created, so if you want to change the default layout used by your emails, this is the one to update.

Click on the "Default" layout in your layouts list to enter the layout editor. You'll start by looking at the pre-built layout that Knock gives you out of the box. You'll find a footer design option in this visual builder where you can add footer links to this pre-built layout for HTML emails. You can update the logo, icon, and brand color of your email layout by going to **Settings** > **Branding** and updating these attributes.

If you'd rather create your own layout from scratch, you can click "Edit in code editor" in the top right corner of the layout editor to enter our custom layout editor. You can learn more about custom layouts in the [custom layouts and styling section](/integrations/email/layouts#custom-layouts-and-styling) of this guide.

Every layout includes the text layout for plaintext emails, and the concept works the same as the HTML layout where the text content of your email template will be injected into the `{{content}}` variable. Click the "Text" tab to switch to the text layout, and edit it as you see fit.

## Selecting a layout for a given email template

All new email templates created within workflows will use your `default` email layout by default. To change the layout used by a given step, go to the template editor, click the "Template settings" button in the top right corner, and select your layout from the "Email layout" dropdown in the modal that opens. Once you've selected your layout, you can navigate to the preview tab of the template editor to see how your template looks within the context of your selected layout.

If you'd like to create an email step in your workflow that contains the full HTML document at the template level (without a layout wrapper), you can select "No layout" in this dropdown.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note:</span> Email layouts follow the Knock
      environment commit model, so you'll need to commit them to your current
      environment before you'll see them appear in your email notifications.
    </>
  }
/>

## Custom layouts and styling

If you want to create your own custom email layouts, you can go into the layout editor and click "Edit in code editor" to go to an HTML and CSS editor for your email layout. The important thing to remember here is that your layout needs a `{{content}}` somewhere in its `body` tag for the email template to be injected into the layout.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note:</span> if you're providing a custom HTML
      layout for your emails, the layout must be a valid HTML document.
    </>
  }
/>

### Creating new layouts

To create a new layout, go to **Developers** > **Layouts** and click "Create layout." All new layouts start in Knock's visual layout editor, but you can override this default by clicking "Edit in code editor."

### Using custom fonts

Knock supports custom web fonts that are referenced inside your email layout's `<head>`. This should be done via a `<link>` tag, as the style `@import` rule is not supported:

```html
<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&display=swap"
  rel="stylesheet"
/>
```

Because many widely-used email clients do not support web fonts, we highly recommend choosing a web safe font as a fallback when using custom web fonts to ensure a consistent user experience.

### Using variables and brand attributes in a custom layout

It's helpful to remember that you can use variables you create at the account and environment-levels by injecting them into your layout with the `vars.*` namespace. This is a great tool for global values that will be the same across all emails you send, such as base URL for embedded links in your email notifications.

You can also use the `vars.branding.*` namespace for injecting the branding properties you set in account settings. The following branding properties are available for use in custom layouts.

- `vars.branding.logo_url`
- `vars.branding.icon_url`
- `vars.branding.primary_color`
- `vars.branding.primary_color_contrast`

If you use [per-tenant branding](/concepts/tenants#custom-branding), remember that Knock automatically evaluates these properties and shows the relevant branding elements based on the `tenant_id` associated with a given workflow run. As an example: if I trigger a workflow that includes a tenant_id with custom branding elements set on their `tenant`, the layout will use those branding elements. If no custom branding elements are set on the `tenant`, then the account default branding elements will be used.

### Injecting workflow run scope into a layout at runtime

If you have a workflow-run-scoped variable that you'd like to inject into your layouts, you can do so with normal liquid variable injection, so long as the variables come after the place in your layout where `{{content}}` is first rendered. (If you need to inject variables into your layout above your `{{content}}` variable, see the ["Defining pre-content variables" section](/integrations/email/layouts#defining-pre-content-variables) below.)

As an example, let's say my email template is using the [Liquid capture tag](https://shopify.github.io/liquid/tags/variable/) to create a variable called `formatted_price` within the email template. If I want to inject that `formatted_price` value into the footer of my layout, I can do so by using the `{{formatted_price}}` variable in the footer of my layout file.

### Defining pre-content variables

When the Knock notification engine sends an email notification, it compiles your email template with its selected layout to create a **single email template** that is sent to your recipient.

In this process, the templates that you define in your email channel steps are injected into the `{{ content }}` tag in your email layout.

In cases where you want to inject a template-level variable above the `{{ content }}` tag of your email layout, you can set **pre-content variables** to inject variables into your layout above where your `{{ content }}` tag will render.

To set pre-content variables for your template, open the email template editor, click the three-dot menu in the top right corner and select "Manage template overrides." You'll add your pre-content variables to the pre-content field using liquid syntax.

You can use pre-content variables to:

- Declare any template-specific liquid variables to control or dynamically alter parts of your email layout without needing to create separate email layouts.
- Declare any template-specific liquid variables for use _throughout_ your email template in a single, clear location.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note:</span> by default, anything you put in
      the pre-content field will be injected into both the text and HTML
      versions of your template. As such you should be careful to only use this
      space to declare variables and not actual content.
    </>
  }
/>

As an example, let's say you need to inject a custom `previewText` variable at the top of your email layout, before your `{{ content }}` is rendered. You want your `previewText` to be rendered ahead of the `{{ content }}` block so that email clients correctly show the preview text associated with your message.

To do this your email layout would look like this:

```html title="An email layout with a preview text variable"
<html>
  <body>
    <div style="display: none; max-height: 0px; overflow: hidden;">
      {{ previewText }}
    </div>
    <!-- the rest of email layout -->
    {{ content }}
  </body>
</html>
```

And then within the pre-content override of your email template you'd insert your `previewText` variable:

```markdown title="Pre-content field value"
{% assign previewText = "Hello and welcome to Knock" %}
```

At notification runtime, your layout and pre-content would be rendered into the following email notification.

```html title="An email notification with pre-content and template at runtime"
<html>
  <body>
    <span>Hello and welcome to Knock</span>
    <!-- my template code -->
  </body>
</html>
```

### Defining a blank email layout

If you're looking to create an email template in your workflow that doesn't use a layout to wrap the content of your email, you should select "No layout" in the "Email layout" dropdown within your email channel step's template settings.

## Layouts and the visual template editor

Regardless of the layout you've chosen for a given email step, you'll be able to use the [visual template editor](/send-notifications/designing-workflows/template-editor#visual-editing-with-drag-and-drop-components) to compose the `content` of your email template.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Note: </span>Since each Knock email layout
      contains{" "}
      <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
        &lt;head&gt;
      </code>{" "}
      and{" "}
      <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
        &lt;body&gt;
      </code>{" "}
      tags, these tags should not be included in your workflow's email template.
      If you are transferring email content from an outside source, you may need
      to make adjustments to remove any{" "}
      <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
        &lt;head&gt;
      </code>{" "}
      and{" "}
      <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
        &lt;body&gt;
      </code>{" "}
      tags prior to saving your email template within a Knock workflow.
      Alternatively, you can select "No layout" on your email template.
    </>
  }
/>

When you use the visual template editor to insert components such as buttons and dividers into your email, Knock auto-generates CSS using a set of base component styles. You can find these styles in the section below, where we also cover updating these styles to match your design system.

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Reminder: </span>The visual template editor
      will only render component styles when you are in preview mode. This means
      that if you update base component styling, you'll only see those updates
      in preview mode.
    </>
  }
/>

### Updating base component styles

The components used in the visual template editor use the base component styles included below by default. These styles are auto-generated by Knock and injected into the top of `<head>` of your email layout at runtime.

If you want to override and modify these base component styles to match your design system, you can do so by adding them to the `<head>` of your layout file.

Keep in mind that to override any of the base component style properties listed below you'll need to include an `!important` tag to tell Knock to override the existing base styles that we'll inject into your template at runtime. As an example, if I wanted to update the font size of the `block-button-sm` component, I'd need to update its `font-size` property to `font-size: 20px !important;`.

```css title="Base component styles"
/* Button components */
.block-row.block-row--button_set-v1 .block-button {
  display: inline-block;
  box-sizing: border-box;
  text-decoration: none;
  -webkit-text-size-adjust: none;
}
.block-row.block-row--button_set-v1 .block-button.block-button--outline {
  border-style: solid;
}
.block-row.block-row--button_set-v1 .block-button.block-button--sm {
  font-size: 14px;
  line-height: 20px;
  min-width: 32px;
  padding-top: 4px;
  padding-bottom: 4px;
  padding-left: 8px;
  padding-right: 8px;
}

/* Divider component */
.block-row.block-row--divider-v1 .block-divider {
  border-bottom: 1px solid #dddee1;
}

/* Markdown components */
.block-row.block-row--markdown-v1 .block-markdown > :first-child {
  margin-top: 0;
}
.block-row.block-row--markdown-v1 .block-markdown > :last-child {
  margin-bottom: 0;
}
```

## Automate layout management with the Knock CLI

In addition to working with layouts in the Knock dashboard, you can programmatically create and update layouts using the [Knock CLI](/developer-tools/knock-cli) or our [Management API](/developer-tools/management-api).

If you manage your own email layout files within your application, you can automate the creation and management of Knock layouts so that they always reflect the state of the layout files you keep in your application code.

The Knock CLI can also be used to commit changes and promote them to production, which means you can automate Knock email layout management as [part of your CI/CD workflow](/developer-tools/integrating-into-cicd).

### Layout files structure

When email layouts are pulled from Knock, they are stored in directories named by their layout key.

```txt title="Local layout files structure"
layouts/
├── default/
│   ├── html_layout.html
│   ├── layout.json
│   └── text_layout.txt
└── custom-layout/
    ├── html_layout.html
    ├── layout.json
    └── text_layout.txt
```

If you're migrating your local layout files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using [`knock layout push --all`](/cli#email-layout-push). Each `layout.json` file should follow the example shown below; additional information on the Layout structure is defined [here](/mapi#email-layouts-object).

```json title="Local layout file example JSON"
{
  "key": "custom-layout",
  "name": "Custom Layout",
  "html_layout@": "html_layout.html",
  "text_layout@": "text_layout.txt",
  "footer_links": [{ "text": "My link", "url": "https://example.com" }]
}
```

You can learn more about automating layout management in the [Knock CLI reference](/cli). Feel free to <a href="mailto:support@knock.app">contact us</a> if you have questions.


## Settings and overrides
Learn more about how to configure your email channels in Knock.
---
title: Email settings and overrides
description: Learn more about how to configure your email channels in Knock.
section: Integrations
layout: integrations
tags: ["bcc", "cc", "JSON overrides", "email settings", "email overrides"]
---

Knock email channel configurations support a number of settings. These include email-specific fields (such as `cc`, `bcc`, and `reply-to`) as well as JSON overrides to be passed in API calls to the configured provider's API endpoints.

When you configure a setting in a channel's configuration, it will be used on all instances of that channel across all workflows.

## Configuring email settings

You can override email settings on a per-channel basis, or on a per-template basis.

- **At the channel level**. The `to`, `cc`, `bcc`, and `reply-to` fields can be found in the "Overrides" section of the channel's "Settings" tab.
- **At the template level**. You'll find the email settings under the "Template settings" button.

All email configuration fields support Liquid usage. You will be able to use any variables available in your workflow trigger payloads, as well as system variables such as the current workflow, activities, and any other variables you have access to when building templates.

As an example, if you wanted to conditionally change the "From name" on an email depending on whether one is configured on the actor that triggered the notification, you'd use the following liquid in the "From name" field of your email configuration.

```js title="A From name email configuration using Liquid"
{{ actor.from_name | default: "no-reply@knock.app" }}
```

## Overriding the default `to` address

By default Knock will send your emails to the `email` property stored on the `recipient` for the workflow run. If you need to override this, you can do so by setting the `to` field in your email configuration either at the channel or the template level.

As an example, if you wanted to send all emails to a single address, you could set the `to` field at the channel level to either a static value (like `hello@example.com`) or a dynamic value (like `{{ data.email_to_override }}`).

## Setting `cc` and `bcc` addresses

The `cc` and `bcc` fields can be used to support a single or multiple addresses. In order to use several addresses on any of these fields, make sure to separate them with a comma.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Liquid support.</span> You can pass multiple
      cc and bcc addresses using workflow trigger variables, and configure these
      fields to use them.
    </>
  }
/>

## Provider JSON overrides

Sometimes you may want to customize the API call Knock sends to your email provider.
A good example of this is passing custom arguments as part of the API payload.
Take an example where we're using SendGrid as our email provider. SendGrid allows sending custom arguments under the
`custom_args` key of the JSON payload of their API. By default, Knock sends some arguments using that key, such
the Knock message id. If you want to add more arguments, you can check the following image on how to add them as
JSON overrides:

<figure>
  <Image
    src="/images/integrations/email/email-channel-json-overrides.png"
    width={1920}
    height={976}
    className="rounded-md mx-auto border border-gray-200"
    alt="Channel JSON overrides"
  />
  <figcaption>Configuring email channel JSON overrides.</figcaption>
</figure>

In this example, we want to add two arguments to the `custom_args` attribute of the
API call we send to SendGrid. In this case, the first argument will be hardcoded,
and the second argument's value will be the value of `workflow_variable`, which we
expect to be passed in the payload of the workflow trigger call.


## Sending attachments
Learn more about how to send emails with attachments in Knock.
---
title: Email attachments
description: Learn more about how to send emails with attachments in Knock.
section: Integrations
layout: integrations
---

## How attachments work in Knock

1. Set an attachment key in your email template to tell Knock how to resolve attachments you send in the data payload of your trigger call. To set an attachment key, click the "Template settings" button in the top right corner of the email template editor and set it under the "Attachment key" field.
2. Include one or more attachment objects in the `data` payload of your trigger call. Each attachment object should have the content of the file to be attached as a base64 encoded value.
3. Knock automatically adds any attachments included in the attachment key of your trigger call to the emails sent by your email provider 🎉.

## The attachment object

Every attachment you send to Knock in your `data` payload should include the following properties (those marked with an `*` are required):

| Property         | Description                                                                                                                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`\*         | The name of the file                                                                                                                                                                                                             |
| `content_type`\* | A mime type for the file                                                                                                                                                                                                         |
| `content`\*      | The base64 encoded file content (up to 10mb)                                                                                                                                                                                     |
| `content_id`     | An optional unique `Content-ID` for the attachment, which will automatically set the attachment as `inline`. Currently only supported for [SendGrid](/integrations/email/sendgrid) and [Postmark](/integrations/email/postmark). |

```js title="An example attachment object"
{
  name: "my-file.txt",
  content: myFileContent,
  content_type: "text/plain"
}
```

**Note**: each attachment object must be less than 10mb, but you should confirm whether your email provider has a lower limit.

## Sending attachments in your trigger call

Once you've specified your attachment key in your email template, the last step is to send the data along to Knock. Remember that you need to base64 encode the contents of the file.

<MultiLangCodeBlock
  title="Sending attachment data"
  snippet="workflows.trigger-with-attachment"
/>

**Note**: you can send multiple attachments for an email by including an array of attachment objects under the attachment key in your data payload.

## Sending a different attachment per recipient

If you need to send a different attachment per recipient in a workflow then you'll need to make one trigger call per recipient, such that the data payload is unique to that recipient.

```js title="Unique attachments per recipient"
import { Knock } from "@knocklabs/node";
const knock = new Knock(process.env.KNOCK_API_KEY);

const filesAndRecipients = [
  { id: "user-1", file: user1FileContents },
  { id: "user-2", file: user2FileContents },
];

filesAndRecipients.forEach(({ id, file }) => {
  knock.workflows.trigger("my-workflow", {
    recipients: [id],
    data: {
      attachment: {
        name: "Invoice.pdf",
        content_type: "application/pdf",
        content: file,
      },
    },
  });
});
```


## AWS SES
How to send transactional email notifications to AWS SES with Knock.
---
title: How to send email with AWS SES
description: How to send transactional email notifications to AWS SES with Knock.
tags: ["simple email service"]
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://aws.amazon.com/ses/" target="_blank">AWS Simple Email Service (SES)</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with SES through Knock. We also cover provider configuration and additional data you can pass through to SES.

## Features

- Attachments support
- Knock link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new AWS SES channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to take some steps in AWS before you can configure your SES channel within Knock.

<Steps titleSize="h3">
  <Step title='Verify a "From" address within AWS SES'>
    You'll need to verify the **"From" email address** you plan on using to send emails with AWS if you haven't already. To do so, follow the steps outlined in AWS's guide to <a href="https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#verify-email-addresses-procedure" target="_blank">creating and verifying an email address identity</a>.
  </Step>
  <Step title="Choose an AWS Authentication Scheme">
    Knock supports two authentication schemes with AWS SES:
  
    <AccordionGroup>
      <Accordion title="Option 1: Create an AWS IAM User with security credentials">
        To send notifications via AWS SES using an IAM User, Knock requires the **access key ID** and a **secret access key** of an AWS user with SES send permissions. (Specifically, the `ses:SendEmail` and `ses:SendRawEmail` permissions.)

        If you don't already have a user with send permissions, you can create an IAM user in AWS to use with the Knock API. You can learn more about creating IAM users in AWS <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html" target="_blank">here</a>.

        Once you've created your new IAM user, you'll need to provision them with the policy below.

        ```json title="IAM user policy"
        {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": ["ses:SendEmail", "ses:SendRawEmail"],
              "Resource": "*"
            }
          ]
        }
        ```

        Now that you have an AWS user created and provisioned with SES send access, grab the **access key ID** and a **secret access key** of the user—we'll use these later when configuring the SES channel within Knock.
      </Accordion>
      <Accordion title="Option 2: Create an AWS IAM Role with a trust policy for Knock">
        To send notifications via AWS SES by <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html" target="_blank">delegating an IAM Role</a> in your AWS account to Knock, <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html" target="_blank">secured with an External ID</a>:

        1. Create a new AWS Role:

          - For "Trusted Entity Type" choose "AWS Account."
          - Select "Another AWS account" and put "496685847699" in the Account ID.
          - Check "Require external ID" and enter the ID of the SES channel you created in your Knock dashboard.

          <Image
            src="/images/integrations/email/ses-arn-configuration.png"
            width={1898}
            height={1650}
            className="rounded-md mx-auto border border-gray-200"
            alt="How Knock works diagram"
          />

        2. Attach the following permission policy to that role.

          ```json title="IAM user policy"
          {
            "Version": "2012-10-17",
            "Statement": [
              {
                "Effect": "Allow",
                "Action": ["ses:SendEmail", "ses:SendRawEmail"],
                "Resource": "*"
              }
            ]
          }
          ```

        3. Use that role's ARN when configuring your AWS SES channel in Knock.
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Configuring SES in Knock">
    Now that you have a verified "From" address and either an AWS User's credentials or an AWS IAM Role to delegate to Knock, you're ready to [configure your SES channel](#channel-configuration) in the Knock dashboard under the **Integrations** {">"} **Channels** section.

  </Step>
</Steps>

Here are a few other things to keep in mind once you have your SES channel configured in Knock:

- **SES sandbox mode.** By default, AWS places all new accounts in the SES sandbox. While your account is in the sandbox, you can only send emails to verified email address—keep this in mind if you're testing in development before you've moved your account out of the SES sandbox. For more information on the SES sandbox and how to move your account out of it, see the [SES sandbox documentation](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html).
- **Deliverability tracking.** We cannot currently track deliverability through SES channels. This means that all notifications sent through SES will show up as "Sent" in the Knock messages log, but not "Delivered."

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your AWS SES [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your SES channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for AWS SES**
    <Attributes>
      <Attribute
        name="AWS region"
        type="enum*"
        description="The region your AWS account is in."
      />
      <Attribute
        name="Authentication scheme"
        type="enum*"
        description="The authentication scheme (Access Key or External ID) to use for your SES channel."
      />
      <Attribute
        name="Access key ID"
        type="string*"
        description="The access key ID from your AWS account. Required when using Access Key authentication."
      />
      <Attribute
        name="Secret access key"
        type="string*"
        description="The secret access key from your AWS account. Required when using Access Key authentication."
      />
      <Attribute
        name="AWS IAM Role ARN to assume"
        type="string*"
        description="The ARN of the role in your AWS Account that this channel will use. Required when using External ID authentication."
      />
      <Attribute
        name="External ID"
        type="string*"
        description="The external ID for your AWS IAM Role. Required when using External ID authentication."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails (all as `Tags`):

- `Sender`: always set to `knock.app`
- `knock_message_id`: the ID of the message this email is associated with
- `knock_workflow`: the key of the workflow this message was generated from
- `knock_recipient_id`: the Knock ID of the recipient this email is being sent to

You can learn about the role of these SES attributes in the <a href="https://docs.aws.amazon.com/ses/latest/dg/Welcome.html" target="_blank">AWS Simple Email Service (SES) API documentation</a>.

<Callout
  emoji="🔦"
  text={
    <>
      Keep in mind that AWS SES tags can be up to 256 characters long of only
      ASCII letters (a-z, A-Z), numbers (0-9), underscores (_), or dashes (-).
      If your <span className="font-bold">knock_recipient_id</span> does not
      meet these requirements, Knock will truncate{" "}
      <span className="font-bold">knock_recipient_id</span> to 256 characters
      and remove any prohibited characters.
      <br />
      Check out the{" "}
      <a
        href="https://docs.aws.amazon.com/ses/latest/APIReference/API_MessageTag.html"
        target="_blank"
      >
        AWS Docs
      </a>{" "}
      for more information.
    </>
  }
/>

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.


## MailerSend
How to send transactional email notifications to MailerSend with Knock.
---
title: How to send email with MailerSend
description: How to send transactional email notifications to MailerSend with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://mailersend.com/" target="_blank">MailerSend</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with MailerSend through Knock.

## Features

- Attachments support
- Delivery tracking
- Bounce Support
- Knock link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new MailerSend channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your MailerSend [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your MailerSend channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for MailerSend**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your MailerSend account."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.

## Delivery tracking

Delivery tracking for MailerSend can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered due to bad recipient(s) and Knock updates the message to `bounced`


## Mailgun
How to send transactional email notifications to Mailgun with Knock.
---
title: How to send email with Mailgun
description: How to send transactional email notifications to Mailgun with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://mailgun.com/" target="_blank">Mailgun</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with Mailgun through Knock. We also cover provider configuration and additional data you can pass through to Mailgun.

## Features

- Attachments support
- Delivery tracking
- Bounce Support
- Knock link and open tracking
- Mailgun link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Mailgun channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Mailgun [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Mailgun channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Mailgun**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The private API key for your Mailgun account."
      />
      <Attribute
        name="Domain"
        type="string*"
        description="The domain verified with Mailgun for sending emails."
      />
      <Attribute
        name="Mailgun region"
        type="enum*"
        description="The sending region (US or EU) for your Mailgun account."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable Mailgun email-open tracking."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable Mailgun link-click tracking."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider. "
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes to Mailgun along with your emails:

- `v:sender`: always set to `knock.app`
- `v:knock_message_id`: the ID of the message this email is associated with
- `v:knock_recipient_id`: the Knock ID of the recipient this email is being sent to
- `o:tag`: the workflow key for the workflow being invoked

You can learn about the role of these Mailgun attributes in the <a href="https://documentation.mailgun.com/en/latest/quickstart.html" target="_blank">Mailgun API documentation</a>.

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.

## Delivery tracking

Delivery tracking for Mailgun can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered and Knock updates the message to `undelivered`
- The message was not delivered due to bad recipient(s) and Knock updates the message to `bounced`

## Passing additional tags to Mailgun

It's possible to pass additional tags to Mailgun by setting the "JSON overrides" attribute in the channel configuration or at the message template level.

To pass one or more tags, you can set the `o:tag` attribute to an array of tag names:

```json
{
  "o:tag": ["tag1", "{{ workflow.key }}"]
}
```


## Mailjet
How to send transactional email notifications to Mailjet with Knock.
---
title: How to send email with Mailjet
description: How to send transactional email notifications to Mailjet with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://mailjet.com/" target="_blank">Mailjet</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with Mailjet through Knock. We also cover provider configuration and additional data you can pass through to Mailjet.

## Features

- Attachments support
- Delivery tracking
- Knock link and open tracking
- Mailjet link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Mailjet channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Mailjet [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Mailjet channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Mailjet**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The public API key for your Mailjet account."
      />
      <Attribute
        name="API secret key"
        type="string*"
        description="The secret API key for your Mailjet account."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable Mailjet email-open tracking."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable Mailjet link-click tracking."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `CustomID`: the Knock `message_id` associated with this email.

You can learn about the role of this Mailjet attribute in the <a href="https://dev.mailjet.com/email/guides/send-api-v31/" target="_blank">Mailjet API documentation</a>.

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.

## JSON overrides behavior

For this provider, we will merge the JSON overrides with the first object under the `"Messages"` attribute.


## Mailtrap
How to send transactional email notifications to Mailtrap with Knock.
---
title: How to send email with Mailtrap
description: How to send transactional email notifications to Mailtrap with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://mailtrap.io/" target="_blank">Mailtrap</a> to send email notifications to your users.

In this guide, you'll learn how to get started sending transactional email notifications with Mailtrap through Knock. We also cover provider configuration and additional data you can pass through to Mailtrap.

## Features

- Attachments support
- Delivery tracking
- Knock link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Mailtrap channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Mailtrap [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Mailtrap channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Mailtrap**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your Mailtrap account."
      />
      <Attribute
        name="API"
        type="enum*"
        description="Which Mailtrap API (Sending or Testing) to use."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `custom_variables.knock_message_id`: the ID of the message this email is associated with
- `custom_variables.knock_recipient_id`: the Knock ID of the recipient this email is being sent to

## Recipient data requirements

To send an email notification you'll need a valid `email` property set on your recipient.


## Mandrill
How to send transactional email notifications to Mandrill with Knock.
---
title: How to send email with Mandrill
description: How to send transactional email notifications to Mandrill with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://mandrillapp.com/" target="_blank">Mandrill</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with Mandrill through Knock. We also cover provider configuration and additional data you can pass through to Mandrill.

## Features

- Attachments support
- Delivery tracking
- Knock link and open tracking
- Mandrill link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Mandrill channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Mandrill [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Mandrill channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Mandrill**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your Mandrill account."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable Mandrill email-open tracking."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable Mandrill link-click tracking."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `metadata.knock_message_id`: the ID of the message this email is associated with
- `metadata.knock_recipient_id`: the Knock ID of the recipient this email is being sent to

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.


## Postmark
How to send transactional email notifications to Postmark with Knock.
---
title: How to send email with Postmark
description: How to send transactional email notifications to Postmark with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://postmarkapp.com/" target="_blank">Postmark</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with Postmark through Knock. We also cover provider configuration and additional data you can pass through to Postmark.

## Features

- Attachments support
- Delivery tracking
- Bounce Support
- Knock link and open tracking
- Postmark link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Postmark channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Postmark [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Postmark channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Postmark**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your Postmark server."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable Postmark email-open tracking."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable Postmark link-click tracking."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `Metadata.sender`: always set to `knock.app`
- `Metadata.knock_message_id`: the ID of the message this email is associated with
- `Metadata.knock_recipient_id`: the Knock ID of the recipient this email is being sent to
- `Tag`: the key of the workflow this message was generated from

You can learn about the role of these Postmark attributes in the <a href="https://postmarkapp.com/developer" target="_blank">Postmark API documentation</a>.

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.

## Delivery tracking

Delivery tracking for Postmark can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered due to bad recipient(s) and Knock updates the message to `bounced`


## Resend
How to send transactional email notifications to Resend with Knock.
---
title: How to send email with Resend
description: How to send transactional email notifications to Resend with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://resend.com/" target="_blank">Resend</a> to send email notifications to your users. Note: you will need an existing Resend account to set up this integration.

In this guide you'll learn how to get started sending transactional email notifications with Resend through Knock. We also cover provider configuration details.

## Features

- Attachments support
- Delivery tracking
- Bounce support
- Knock link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Resend channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Resend [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Resend channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Resend**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your Resend account, available from your Resend dashboard."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

To send an email notification you'll need a valid `email` property set on your recipient.

## Debugging common errors

### `Identity not found`

If you see an `Identity not found` error in your delivery logs this is because you need to verify your sending domain with Resend (the `From email address`).

## Delivery tracking

Delivery tracking for Resend can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered due to a bounce and Knock updates the message to `bounced`


## SendGrid
How to send transactional email notifications to SendGrid with Knock.
---
title: How to send email with SendGrid
description: How to send transactional email notifications to SendGrid with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://sendgrid.com" target="_blank">SendGrid</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with SendGrid through Knock. We also cover provider configuration and additional data you can pass through to SendGrid.

## Features

- Attachments support
- Delivery tracking
  - Only supported for SendGrid accounts with Email Activity.
- Bounce support
  - Only supported for SendGrid accounts with Email Activity.
  - Currently, only synchronous bounce updates are reflected.
- Knock link and open tracking
- SendGrid link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

### Connect SendGrid to Knock

You can create a new SendGrid channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

Here are a few things to note as you configure your SendGrid provider:

- **API key.** At a minimum, Knock needs an API key with full access to the **Mail Send** permission. If you're looking to support delivery tracking, you'll need to provide Knock with a SendGrid API key that includes read access to the **Email Activity** permission. (Note: email activity requires <a href="https://sendgrid.com/solutions/add-ons/30-days-additional-email-activity-history/" target="_blank">a SendGrid paid add-on</a>.)
- **Check delivery status.** If enabled, you can go to the email activity page in SendGrid to check the delivery status of a given email.
- **Enable email open tracking.** If enabled, you can go to the email activity page in SendGrid to check the open status of a given email.
- **Enable email link tracking.** If enabled, you can go to the email activity page in SendGrid to check the link open status of a given email.

If you choose to enable open and link tracking, please keep user privacy top of mind and follow the privacy guidelines outlined in <a href="https://docs.sendgrid.com/ui/account-and-settings/tracking" target="_blank">SendGrid's documentation</a>.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your SendGrid [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your SendGrid channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for SendGrid**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your SendGrid account."
      />
      <Attribute
        name="Check delivery status"
        type="boolean"
        description="When set will attempt to check for the delivery status of a message. Only available with SendGrid's Email Activity add-on."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable SendGrid email-open tracking. Only available with SendGrid's Email Activity add-on."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable SendGrid link-click tracking. Only available with SendGrid's Email Activity add-on."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `custom_args.sender`: always set to `knock.app`
- `custom_args.knock_message_id`: the ID of the message this email is associated with
- `custom_args.knock_recipient_id`: the Knock ID of the recipient this email is being sent to
- `tags[0]`: the key of the workflow this message was generated from

You can learn about the role of these SendGrid attributes in the <a href="https://docs.sendgrid.com/" target="_blank">SendGrid API documentation</a>.

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.

## Delivery tracking

Delivery tracking for SendGrid can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered and Knock updates the message to `undelivered`
- The message was not delivered due to a synchronous bounce and Knock updates the message to `bounced`

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Note:</span> Asynchronous bounces that occur
      after initial delivery are not currently reflected in Knock's delivery
      status.
    </>
  }
/>


## SMTP
How to send transactional email notifications using SMTP with Knock.
---
title: How to send email with SMTP
description: How to send transactional email notifications using SMTP with Knock.
section: Integrations > Email
layout: integrations
---

Knock supports sending email notifications to your users via the Simple Mail Transfer Protocol (SMTP). In this configuration, Knock will act as an SMTP client and send email notifications to a specified SMTP server.

In this guide, we'll cover how to get started sending email notifications using SMTP with Knock.

## Features

- Attachments support
- Knock link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new SMTP Relay channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

The following information is required to configure an SMTP Relay channel:

- SMTP server host
- SMTP server port
- Username
- Password

Please note the following:

- **Knock only supports authenticated SMTP connections.**
- **The port must support TLS.** Email providers commonly use port 587 for TLS, but check your provider's documentation to confirm.
- **We cannot currently track deliverability through SMTP Relay channels.** This means that all notifications sent via SMTP will show up as "Sent" in the Knock messages log, but not "Delivered."

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your SMTP [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your SMTP channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for SMTP Relay**
    <Attributes>
      <Attribute
        name="SMTP host"
        type="string*"
        description="The SMTP server host."
      />
      <Attribute
        name="Username"
        type="string*"
        description="The username to use when authenticating with the SMTP server."
      />
      <Attribute
        name="Password"
        type="string*"
        description="The password to use when authenticating with the SMTP server."
      />
      <Attribute
        name="Port"
        type="number*"
        description="The SMTP server port. This port must support TLS."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="#setting-smtp-headers"
        type="JSON (string) | liquid"
        description="For SMTP Relay channels, only header overrides are supported. See 'Setting SMTP headers' below for more details."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Setting SMTP headers

For SMTP Relay channels, the JSON overrides field can be used to set SMTP headers. Overrides can be set in either the environment settings or per template.

Knock supports overriding existing SMTP headers and adding custom headers.

```json title="Adding a custom SMTP header via JSON overrides"
{
  "headers": {
    "X-SMTPAPI": "{\"category\": \"transactional\"}"
  }
}
```

Headers must be nested under the `headers` key. Other keys will be ignored.

<Callout
  emoji="🔦"
  text={
    <>
      <b>SMTP headers are sent as strings.</b> If one of your header overrides
      is not already a string, Knock will automatically convert it to a string
      before sending.
    </>
  }
/>

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.


## SparkPost
How to send transactional email notifications to SparkPost with Knock.
---
title: How to send email with SparkPost
description: How to send transactional email notifications to SparkPost with Knock.
section: Integrations > Email
layout: integrations
---

Knock integrates with <a href="https://support.sparkpost.com/docs/getting-started/getting-started-sparkpost" target="_blank">SparkPost</a> to send email notifications to your users.

In this guide you'll learn how to get started sending transactional email notifications with SparkPost through Knock. We also cover provider configuration and additional data you can pass through to SparkPost.

## Features

- Attachments support
- Delivery tracking
- Knock link and open tracking
- SparkPost link and open tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new SparkPost channel in the dashboard under the **Integrations** {">"} **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your SparkPost [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your SparkPost channel."
      />
      <Attribute
        name="Knock open tracking"
        nameSlug="/send-notifications/tracking#email-open-tracking"
        type="boolean"
        description="Whether to enable Knock email-open tracking."
      />
      <Attribute
        name="Knock link tracking"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        type="boolean"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for SparkPost**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key for your SparkPost account."
      />
      <Attribute
        name="SparkPost region"
        type="enum*"
        description="The region that your SparkPost account is in, either US or EU."
      />
      <Attribute
        name="Open tracking"
        type="boolean"
        description="Whether to enable SparkPost email-open tracking."
      />
      <Attribute
        name="Link tracking"
        type="boolean"
        description="Whether to enable SparkPost link-click tracking."
      />
      <Attribute
        name="From email address"
        type="string | liquid*"
        description="The default sender email address (can use Liquid tags)."
      />
      <Attribute
        name="From name"
        type="string | liquid"
        description="The default sender name (can use Liquid tags)."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Overrides">
    When configured, these optional overrides will apply to all emails sent from this channel in the configured environment. Learn more about email channel overrides [here](/integrations/email/settings).
    
    <Attributes>
      <Attribute
        name="To"
        type="string | liquid"
        description="The To email address that email notifications will be sent to (can use Liquid tags). This value will override the designated recipient's email address."
      />
      <Attribute
        name="Cc"
        type="string | liquid"
        description="The CC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Bcc"
        type="string | liquid"
        description="The BCC email address that email notifications will be sent to (can use Liquid tags)."
      />
      <Attribute
        name="Reply-to"
        type="string | liquid"
        description="The reply-to email address that will be included on email notifications (can use Liquid tags)."
      />
      <Attribute
        name="Payload overrides"
        nameSlug="/integrations/email/settings#provider-json-overrides"
        type="JSON (string) | liquid"
        description="Provide a JSON object to merge into the API payload that is sent to the downstream provider."
      />
    </Attributes>
  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Additional data sent

Knock sends the following attributes along with your emails:

- `metadata.knock_message_id`: the ID of the message this email is associated with
- `metadata.knock_recipient_id`: the Knock ID of the recipient this email is being sent to

## Recipient data requirements

In order to send an email notification you'll need a valid `email` property set on your recipient.



# Chat

## Overview
Learn how to use Knock to send notifications to chat apps such as Slack, Microsoft Teams, and Discord.
---
title: Chat notifications with Knock
description: Learn how to use Knock to send notifications to chat apps such as Slack, Microsoft Teams, and Discord.
section: Integrations > Chat
layout: integrations
---

We make it effortless to send notifications to chat providers like Slack, Microsoft Teams, and Discord. Meet your users in the tools they use daily.

## Features

- **Markdown template builder**: use our markdown editor to create templates for each platform and let us take care of sending the platform-specific markup.
- **Use JSON to build interactive messages**: if you need to, it's easy to go to a fully customizable JSON template to power your chat notifications.
- **Cross-provider, single template**: you can send the same chat templated message across all chat providers to reduce the amount of templates to maintain.
- **Link tracking**: capture link-click events right within your Knock account. For more details, see the [Knock link tracking guide](/send-notifications/tracking).

## Supported providers

Knock currently has support for the following chat providers:

- [Slack](/integrations/chat/slack)
- [Discord](/integrations/chat/discord)
- [Microsoft Teams](/integrations/chat/microsoft-teams)
- [WhatsApp](/integrations/chat/whatsapp)

If you want us to add a new provider to this list, please let us know through the feedback button at the top of this page.


## Slack

## Overview
Learn how to use Knock to send Slack notifications to your users.
---
title: Slack notifications with Knock
description: Learn how to use Knock to send Slack notifications to your users.
section: Integrations > Slack
layout: integrations
---

In this guide you'll learn how to use Knock to send notifications to Slack. Depending on your use case, there are a few different ways to approach this integration. This guide serves as a starting point and will cover the basics of setting up a Slack integration with Knock regardless of your use case.

Here's what we'll cover in this guide.

- Building a Slack app for your integration
- How to store Slack connection data in Knock using channel data
- How to compose templates for Slack notifications using markdown and block kit UI

## How to connect Slack to Knock

Knock supports multiples ways to create a Slack integration depending on your technical requirements:

- Using Knock's managed approach with our [SlackKit components](/in-app-ui/react/slack-kit)
- Using Knock's [Slack-related React hooks](https://docs.knock.app/in-app-ui/react/slack-kit#using-slackkit-headless) with your own components
- Building the UI and OAuth flow entirely yourself

Regardless of your approach, you'll need a Slack app to send notifications from Knock to a Slack workspace. If you haven’t built a Slack app yet, you can get started in <a href="https://api.slack.com/start/quickstart#creating" target="_blank">Slack’s app documentation</a>.

Once you create your Slack app, you’ll be routed to its app management page within the Slack dashboard. It looks like this.

<Image
  src="/images/slack-app-management-page.png"
  width={3248}
  height={1942}
  alt="Slack app management page"
/>

If you are new to Slack apps, there are a few key concepts to understand:

- A <a href="https://api.slack.com/scopes" target="_blank">scope</a> is a permission granted to your Slack app when it joins a Slack workspace. You configure which scopes your app asks for in the **OAuth & Permissions** sidebar of your <a href="https://api.slack.com/apps" target="_blank">app management page</a>.
- Your Slack app is installed to a customer's workspace through the <a href="https://api.slack.com/authentication/oauth-v2" target="_blank">Slack OAuth flow</a>. In this flow, your app requests scopes and the user installing the app confirms which scopes to grant. You’ll need to surface this OAuth flow to your users wherever you want them to install your Slack app. Knock's [`SlackAuthButton` component](/in-app-ui/react/slack-kit#slackauthbutton--container) can help you with this.
- A Slack app can have bot token scopes and user token scopes. For almost all use cases, you’ll be using bot token scopes (<a href="https://api.slack.com/authentication/basics" target="_blank">this Slack doc explains why</a>). When you add bot token scopes to an app, you will **also** need to make sure your app has its display information configured. You can do this under the **App Home** sidebar on the <a href="https://api.slack.com/apps" target="_blank">app management page</a>.

In this section we'll complete the steps for setting up your Knock account and Slack app.

<Steps titleSize="h3">
  <Step title="Set up Slack app">
    First, you'll need to create the bot that you'll use to post notifications.

    <Callout
      emoji="🤖"
      text={
        <>
          <strong>Prepare existing Slackbot</strong>
          <br />
          <br />
          If you already have a Slackbot you want to use, you'll just need to
          make sure it has its redirect URL set and that it's publicly distributed, which
          is described below.
        </>
      }
    />

    The following steps will be completed in the **OAuth & Permissions** sidebar of your Slack app's <a href="https://api.slack.com/apps" target="_blank">management page</a>:

    <AccordionGroup>
      <Accordion title="Add a scope">
        When using an `access_token` stored in Knock to power your Slack integration, that token will need to contain the correct scopes to use the Slack API. Although If you're using SlackKit, the components can help you manage your scopes, but you have to add one in your Slack application's settings to start with so that it exposes the form for you to add a redirect URL.

        Here is the list of scopes we recommend adding to your app and the reasons they're required:

        - `chat:write`: This scope allows your bot to send messages to channels that the bot has been explicitly invited to, including private channels. It doesn't grant the ability to send messages to public channels without an invite.
        - `chat:write.public`: This scope extends the bot's capabilities to send messages to public channels without needing a specific invitation to those channels. It's an addition to the chat:write scope, offering broader access for the bot to interact within the workspace.
        - `channels:read`: This scope allows your bot to list all channels in a workspace and view details about specific channels (like name, topic, purpose, members), but does not grant access to private channels.
        - `groups:read`: This scope allows your app to list all private channels that the bot or user is a member of and to view details about those channels.
        - `users:read`: This scope allows your app to view all people in a workspace and is required if you want to query a user's Slack ID by email. **This scope is required to use [Knock's email-based user ID resolution](/integrations/chat/slack/sending-a-direct-message#enabling-email-based-user-id-resolution).**
        - `users:read.email`: This scope allows your app to view the email addresses of people in a workspace and is required if you want to query a user's Slack ID by email. **This scope is required to use [Knock's email-based user ID resolution](/integrations/chat/slack/sending-a-direct-message#enabling-email-based-user-id-resolution).**

      </Accordion>
      <Accordion title="Add redirect URL">
        Under **OAuth & Permissions** in the **Features** sidebar, you need to add a redirect URL so that Slack knows where to redirect users after they complete the OAuth handshake.

        If you plan on using SlackKit, copy and paste this redirect URL:

        <CopyableText
          label="https://api.knock.app/providers/slack/authenticate"
          content="https://api.knock.app/providers/slack/authenticate"
        />

        If you are building your own OAuth flow, you'll need to use a URL in your frontend application. You can reference this guide on [building a Slack OAuth flow](https://knock.app/blog/how-to-authenticate-users-in-slack-using-oauth) from scratch.
      </Accordion>
      <Accordion title="Set up public distribution">
        Under **Manage Distribution**, click the "Distribute app" button which will show you a list of items to complete to activate public distribution. If you've built the app from scratch and completed the previous steps, you should see all of these complete except for "Remove hard coded information."

        Check the box and then click "Activate Public Distribution."
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Add Slack app to Knock Slack integration">
    Now that your Slack app is set up, you'll want to reference three attributes in the **Basic Information** section:

    1. App ID
    2. Client ID
    3. Client secret

    You need to add this data to a new or existing Slack integration in the Knock dashboard to link your app to Knock. From the dashboard, you can [create a Slack integration](/concepts/channels#managing-channels) in the **Integrations** tab.
    <Image
    src="/images/integrations/chat/slack/create-slack-channel.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="A Slack message"
    width={2000}
    height={1186}
    />
    Once the channel exists, you can click "Manage configuration" to access the "Provider settings" section. This is where you'll paste the three strings referenced above.
    <Image
    src="/images/integrations/chat/slack/edit-slack-channel-config.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="A Slack message"
    width={2000}
    height={1208}
    />

    Click "Update settings" to save.

  </Step>
  <Step title="Use Slack channel in a workflow">
    In order to test this flow, you'll want to set up a workflow with a Slack channel step. Later on we'll discuss how you can [design your notification templates for Slack](/integrations/chat/slack/overview#designing-notification-templates-for-slack), but for now you can just add the channel step to a workflow. To actually send a notification to Slack, you'll need to add channel data to a user or object in Knock. We'll cover that in the next section.
    <Image
  src="/images/integrations/chat/slack/workflow-with-slack-step.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="workflow with a Slack step"
  width={2000}
  height={1450}
/>
  </Step>
</Steps>

## How to set channel data for a Slack integration in Knock

In Knock, the [`ChannelData`](/managing-recipients/setting-channel-data) concept provides you a way of storing recipient-specific connection data for a given integration. If you reference the [channel data requirements for Slack](/managing-recipients/setting-channel-data#chat-app-channels), you'll see that there are two different schemas for a `SlackConnection` stored on a [`User`](/concepts/users) or an [`Object`](/concepts/objects) in Knock.

Here's an example of setting channel data on an `Object` in Knock.

<MultiLangCodeBlock
  snippet="objects.setChannelData.slack"
  title="Store Slack connection on object"
/>

<br />

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Potential confusion alert.</span> In the
      example above, the <code>KNOCK_SLACK_CHANNEL_ID</code> variable is the id
      of the Knock channel you've created to represent your Slack app within the
      Knock dashboard. You can find it by going to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard and
      then copying the ID of your Slack app channel.
    </>
  }
/>

### Recipient channel data requirements

Here's an overview of the data requirements for [setting recipient channel data](/send-notifications/setting-channel-data) for either an incoming webhook or an access token Slack connection. Both will need to live under the `connections` key.

| Property    | Type                | Description                      |
| ----------- | ------------------- | -------------------------------- |
| connections | `SlackConnection[]` | One or more connections to Slack |

    A `SlackConnection` can have one of two schemas, depending on whether you're using standard Slack OAuth scopes or an incoming webhook.
    We cover Slack app scopes in detail in our [Slack scopes guide](/integrations/chat/slack-diy/slack-apps-and-scopes).

<AccordionGroup>
  <Accordion title="SlackConnection with an access token" description="For self-serve customer integrations">
      If you're using standard Slack OAuth with access token scopes, your `SlackConnection` schema looks like this. You'll use
    either a `channel_id` or `user_id` depending on whether you're storing connection data to message a channel or user in Slack:

    | Property     | Type     | Description        |
    | ------------ | -------- | ------------------ |
    | access_token | `string` | A bot access token |
    | channel_id   | `string` | A Slack channel ID |
    | user_id      | `string` | A Slack user ID    |

    ```json title="Slack channel_data with an access token"
    {
      "connections": [
        {
          "access_token": "ACCESS_TOKEN",
          "channel_id": "CHANNEL_ID",
          "user_id": "USER_ID"
        }
      ]
    }
    ```

  </Accordion>
  <Accordion title="SlackConnection with an incoming webhook url" description="For internal or one-off integrations">
     If you're using a Slack app with the `incoming-webhook` scope your `SlackConnection` schema is quite simple:

    | Property             | Type     | Description                                                                 |
    | -------------------- | -------- | --------------------------------------------------------------------------- |
    | incoming_webhook.url | `string` | The Slack incoming webhook URL (to be used instead of the properties above) |


    ```json title="Slack channel_data with an incoming webhook URL"
    {
      "connections": [
        {
          "incoming_webhook": { "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" }
        }
      ]
    }
    ```

  </Accordion>
</AccordionGroup>

### Tenant channel data requirements

When you [map a Slack workspace to a tenant](/integrations/chat/slack/sending-a-message-to-channels#key-concepts) in Knock (as our [SlackKit](/in-app-ui/react/slack-kit) components do), you'll store the access token for that workspace as `channel_data` on the tenant. Then, when you apply the `tenant` to your workflow triggers Knock will [combine that access token with the recipient's](/integrations/chat/slack/sending-a-message-to-channels#merging-channel-data) `channel_data` to send notifications to the correct Slack workspace and channel. For this implementation method, the `access_token` on the recipient's `SlackConnection[]` data above is not required.

Here's an overview of the data requirements for setting channel data when storing an access token on a tenant.

| Property           | Type     | Description                                                 |
| ------------------ | -------- | ----------------------------------------------------------- |
| token              | `object` | An object containing the `access_token` obtained from Slack |
| token.access_token | `string` | The `access_token` obtained from Slack                      |

```json title="Slack channel_data on a tenant"
{
  "token": { "access_token": "ACCESS_TOKEN" }
}
```

### Choosing where to store channel data: users vs. objects

Depending on the Slack integration you build into your product, you’ll store the connection data you receive from Slack as `channel_data` on either a `User` or an `Object` in Knock.

<AccordionGroup>
  <Accordion title="Users" description="For notifying users via direct message">
    If your integration involves a user opting in to receive DMs from your Slack bot, you’ll be storing the channel data [on that user](/reference#set-user-channel-data) in Knock. When you want to notify this user, you'll include them as a recipient in a Knock workflow trigger.

    For this integration, you'll store a user's Slack `user_id` in the `SlackConnection` object. You can [enable email-based user ID resolution](/integrations/chat/slack/sending-a-direct-message#enabling-email-based-user-id-resolution) if you'd like Knock to automatically resolve these IDs on your behalf.

    Alternatively, you can manually find the correct `user_id` by querying Slack's API:
    - by [a given user's email address](https://api.slack.com/methods/users.lookupByEmail)
    - for [a list of all of a workspace's users](https://api.slack.com/methods/users.list)

    You'll need to be sure that you request the appropriate [`scopes`](/integrations/chat/slack/overview#set-up-slack-app) for these methods during the auth process.

  </Accordion>
  <Accordion title="Objects" description="For notifying Slack channels about non-user resources">
    If your integration involves a customer connecting a _non-user resource_ in their product (such as a project or a page) to a Slack channel, you’ll want to store that channel data [on an object](/reference#set-object-channel-data) in Knock, as it’s not specific to any single user.

    You can find the correct `channel_id` and display a list of channels for your user to select from by querying the Slack API:
    - for [a list of all of a workspace's channels](https://api.slack.com/methods/conversations.list)

    The [`SlackChannelCombobox`](/in-app-ui/react/slack-kit#slackchannelcombobox) component of Knock's SlackKit can help you with this.

    You can learn more about the Knock object model and see an example how to use it to power Slack notifications in our [Objects concept guide](/concepts/objects).

  </Accordion>
</AccordionGroup>
<br />

## Designing notification templates for Slack

When you add a new Slack channel step to a workflow in Knock, you'll need to configure a template for that step so Knock knows how to format the message to Slack.

### Markdown templates

Editing a markdown template for Slack is just like editing any other markdown-based template in Knock. You can use [Liquid](https://shopify.github.io/liquid/) to inject variables and add control tags (e.g. if-then, for-loop) into your template.

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Knock fun fact.</span> Slack uses a
      markdown-variant syntax called{" "}
      <a href="https://api.slack.com/reference/surfaces/formatting#basics">
        mrkdwn
      </a>
      , but Knock handles this for you automatically, so you can write your templates
      in good old <a href="https://daringfireball.net/projects/markdown/">
        {" "}
        markdown{" "}
      </a>.
    </>
  }
/>

Here's an example Slack template written in Knock using markdown.

```markdown title="A markdown-based Slack template with for-loop iteration"
Hi **{{ recipient.name | split:" " | first }}**,

There are {{ total_activities }} comments left on {{ page_name }}.

{% for activity in activities %}

- From **{{activity.actor.name}}**: "{{activity.comment.body}}""
  {% endfor %}

[**View page**]({{vars.base_url}}/{{account_id}}/pages/{{ page_id }})
```

In the example above we're using [Liquid's for-loop tag](https://shopify.github.io/liquid/tags/iteration/) to iterate over the activities array produced by a Knock batch function. You can learn more about Knock batch functions and the state they produce in our [batch function guide](/send-notifications/designing-workflows/batch-function).

### Block-based templates

For more advanced layouts in your Slack messages, including images and buttons, you'll need to use Slack's [block kit UI framework](https://api.slack.com/block-kit) to build your notification templates. The block kit framework is a set of different JSON objects you can use together and arrange to create Slack app and notification layouts.

#### Designing block kit templates

To start you'll want to design your block-based Slack message template. The best way to do this today is to use [Slack's block kit builder](https://app.slack.com/block-kit-builder/). It gives you a drag-and-drop interface for building out your Slack templates, and outputs the JSON you'll need to bring into your Knock template.

<Callout
  emoji="🛣"
  text={
    <>
      <span className="font-bold">Knock roadmap alert.</span> In the future
      you'll be able to use a visual, drag-and-drop editor within Knock to build
      these block-based Slack templates without having to leave the Knock
      product. <br />
      <br /> If you're interested in trying this functionality, please shoot us a
      note at <a href="mailto:support@knock.app">support@knock.app</a> or use the
      feedback button at the top of this page.
    </>
  }
/>

Once you've designed your Slack template, copy the JSON from the block kit builder and bring it into your Knock notification template. You'll use the "Switch to JSON editor" button at the bottom right of the Knock template editor page to switch to our JSON editor, and then paste in the JSON you copied from the block kit builder.

#### Knock's JSON template editor

You can use liquid in the Knock JSON template editor just as you would in the markdown editor. This is helpful for both injecting variables into the text of your Slack UI blocks, as well as for for using liquid control tags to control when certain blocks should be displayed and for iterating through an array and mapping its items into a list of Slack blocks.

Here's an example of a block kit UI template with liquid syntax added to iterate through a list of items.

```json title="A block kit UI template in Knock with for-loop iteration"
{
	"blocks": [
		{
			"type": "header",
			"text": {
				"type": "plain_text",
				"text": "Users marked for onboarding",
				"emoji": true
			}
		},
		{
			"type": "section",
			"text": {
				"type": "mrkdwn",
				"text": "Hi John,\n\n The following users have been assigned to you for onboarding today:"
			}
		},
		{% for activity in activities %}
		{
			"type": "section",
			"text": {
				"type": "mrkdwn",
				"text": "*{{activity.assigned_user.name}}* \n {{activity.assigned_user.email}} \n _{{activity.assigned_user.title}}_"
			},
			"accessory": {
				"type": "image",
				"image_url": "{{activity.assigned_user.avatar_url}}",
				"alt_text": "avatar image"
			}
		},
		{
			"type": "divider"
		},
		{% endfor %}
		{
			"type": "actions",
			"elements": [
				{
					"type": "button",
					"text": {
						"type": "plain_text",
						"text": "View in dashboard",
						"emoji": true
					},
					"value": "{{dashboard_url}}"
				}
			]
		}
	]
}
```

In the template above, we're using the `activities` array produced by a [batch function](/send-notifications/designing-workflows/batch-function) to iterate over a number of items that we want to display in our Slack message. For each one of those items, we're producing a `section` that includes both `text` and `image` blocks which reference variables from the `activity` from our `activities` array.

Here's an example of a Slack message produced with this template. **Note:** this template was produced by three separate workflow trigger calls to the Knock API, all of which were batched into a single message automatically using our batch function.

<Image
  src="/images/integrations/chat/slack/slack-json-block-example.png"
  width={600}
  height={467}
  className="rounded-md mx-auto border border-gray-200"
  alt="An example Slack message built with block kit UI"
/>


## Sending an internal message
How to send a message to an internal Slack workspace using Knock.
---
title: Sending a message to an internal Slack workspace
description: How to send a message to an internal Slack workspace using Knock.
tags: ["slack", "chat"]
section: Integrations > Slack
layout: integrations
---

In this guide we'll cover how to send a message to an internal Slack workspace using Knock. It assumes that you have already created a Slack app and created a Slack channel in Knock as outlined in the [Slack integration overview](/integrations/chat/slack/overview) guide.

Here's what we'll cover in this guide:

- Retrieving an incoming webhook URL from your Slack app
- Setting channel data for an `Object` in Knock
- Triggering a workflow with an object recipient to send a message to a Slack channel

## Slack channels are connections on Objects

In Knock, we model channels in a Slack workspace as connections on Objects. [Objects](/concepts/objects) allow you to model any resource in your system within Knock, and while their primary purpose is to act as non-user recipients, they are very flexible abstractions.

### An overview of Objects

Individual Objects exist within [a collection](/concepts/objects#collection-naming) and always have [a unique ID](/concepts/objects#the-object-identifier) or key within that collection. The Object itself can store any number and type of properties as key-value pairs. You can see some examples of possible Object structures in [the official documentation on setting Object data](/concepts/objects#sending-object-data-to-knock).

Let’s say you are building a devtool product like GitHub and want to set up Slack notifications whenever someone comments on an issue within a repository. First, you’ll want to create an Object to model your repository as part of the `repositories` collection:

```javascript
import { Knock } from "@knocklabs/node";
const knockClient = new Knock(process.env.KNOCK_API_KEY);

await knockClient.objects.set("repositories", "repo-1", {
  name: "My repo",
});
```

Once you have a repository object created, you can add the channel data for Slack as a connection on the object.

## Objects as workflow recipients

To add channel data, we’ll set up an [incoming webhook in Slack](https://api.slack.com/messaging/webhooks). To get this URL from Slack, you can go to “Incoming Webhooks” within your dashboard and toggle the "Activate Incoming Webhooks" feature. If you’ve already installed your app into a workspace, you will be asked to reinstall it and select a channel the app will post messages to.

<Image
  src="/images/integrations/chat/slack/activate-incoming-webhooks.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="activating incoming webhooks in Slack"
  width={2000}
  height={1130}
/>
To generate a new webhook, scroll to the bottom of the page where you see the “Add
New Webhook to Workspace” button. If you connected an initial channel, you can copy
your webhook, or you can connect another channel and then copy the webhook URL:

<Image
  src="/images/integrations/chat/slack/copy-webhook.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="creating a Slack channel in Knock dashboard"
  width={2000}
  height={1734}
/>

### Set the webhook as channel data

Now that you have the webhook URL, we’ll store that webhook as a special property on the repository Object called channel data. [Channel data is both channel and recipient-specific data](https://docs.knock.app/managing-recipients/setting-channel-data) stored for use with particular channels, like a token used for push notifications or webhooks stored for chat apps like Slack, Teams, and Discord. Both Users and Objects can store channel data.

In the code example below, we’ll use the `knockClient.objects.setChannelData` method to update the channel data for our repository Object.

```javascript
import { Knock } from "@knocklabs/node";
const knockClient = new Knock(process.env.KNOCK_API_KEY);

await knockClient.objects.setChannelData(
  "repositories",
  repository.id,
  process.env.KNOCK_SLACK_CHANNEL_ID,
  {
    connections: [
      {
        incoming_webhook: { url: "url-from-slack" },
      },
    ],
  },
);
```

Here, you’ll also need your `KNOCK_SLACK_CHANNEL_ID` as the third parameter, which is the channel ID of your Slack integration within Knock, so that Knock can reference that channel when it processes workflows that use it. The last parameter is an object of a specific format that varies based on [the type of message provider](/managing-recipients/setting-channel-data#provider-data-requirements). In this case, it is a `SlackConnection` object with an `incoming_webhook` property that contains the URL you copied from Slack.

### Trigger a workflow with an object recipient

With the channel data in place, you can add Slack as a workflow step in any workflow. For this example, we’ll create a `new-issue` workflow that pings users in our connected Slack channel whenever someone adds a new issue.

<Image
  src="/images/integrations/chat/slack/workflow-with-slack-step-new.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="workflow with a Slack step"
  width={2202}
  height={1922}
/>

As you create your message template, remember that in this case the repository Object is the recipient of your workflow. That means any properties you reference on your Liquid template tags need to exist as properties of the Object as well:

```markdown
There was an issue opened on the following repo: **{{ recipient.name }}**
```

Finally, we’ll add the workflow trigger to our code with the repository Object as a recipient.

```javascript
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

await knock.workflows.trigger("new-issue", {
  recipients: [{ collection: "repositories", id: "repo-1" }],
});
```

With that, you should see a message in your selected Slack channel:

<Image
  src="/images/integrations/chat/slack/slack-message.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="A Slack message"
  width={2000}
  height={552}
/>


## Sending a direct message
How to configure and send direct messages to Slack users.
---
title: Sending a direct message to a user in Slack
description: "How to configure and send direct messages to Slack users."
tags: ["slack", "chat"]
section: Integrations > Slack
layout: integrations
---

In this guide we'll cover how to create a self-serve Slack integration for a multi-tenant application using Knock. It assumes that you have already created a Slack app and created a Slack channel in Knock as outlined in the [Slack integration overview](/integrations/chat/slack/overview) guide.

In this implementation, your application's users will connect their Slack workspace to Knock and be able to send messages to individual users via DM. To make this easier to implement, we'll use Knock's [SlackKit components](/in-app-ui/react/slack-kit) to facilitate the OAuth flow.

Here's what we'll cover in this guide:

- Modeling a multi-tenant application in Knock using `Tenants`
- Implementing a Slack OAuth flow using Knock's `SlackAuthButton` component
- Using the `access_token` stored in Knock to request a user's Slack ID
- Triggering a workflow with a user recipient to send a message to a DM

## Key concepts

SlackKit connects multiple concepts in Knock to make it easier for your application's users to create a Slack integration. `Tenants` are a concept you'll see throughout the following docs that are foundational to how SlackKit works, but might not be used in every implementation of Knock.

### About tenants

[Tenants](/concepts/tenants) in Knock are meant to represent groups of users who typically share the same resources. You might call these "accounts," "organizations," "workspaces," or something similar. In a standard SlackKit implementation, you'll store a Slack workspace's `access_token` on a corresponding tenant in Knock.

If you already use Knock's tenant concept to power other 'account-based' features, you likely create tenants in Knock when an account or organization is created in your application. If you don't already use tenants in Knock, SlackKit can create tenants for you on the fly if they don't already exist.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      Our best-practice recommendation is that tenants in Knock should map one-to-one
      to whatever abstraction you use to model accounts, organizations, or workspaces.
      You can think of tenants as the top-level container within your data model
      that you use to power multi-tenancy in your application.
    </>
  }
/>

### Merging channel data

In this implementation, we'll actually store [the required channel data](/integrations/chat/slack/overview#channel-data-requirements) for a `SlackConnection` across two different entities in Knock: a `Tenant` and an `User`. This is because we want to store the `access_token` for the Slack workspace on the `Tenant` and the `user_id` for the Slack user on the `User`.

When you trigger a workflow using this recipient and tenant, Knock will merge the channel data from the `Tenant` and the `User` to send the message to the correct Slack DM channel. By storing the `access_token` on the `Tenant`, your customers only need to complete the OAuth flow once to connect their Slack workspace to Knock. From there, you can create UI that allows users to link their Slack user ID to their Knock user ID or automate this process during user registration.

## Implementing SlackKit

To facilitate the OAuth flow and channel selection process, we'll use Knock's [SlackKit components](/in-app-ui/react/slack-kit). SlackKit is a set of React components that make it easier to build Slack integrations in Knock. You can use SlackKit to build a self-serve Slack integration that allows your users to connect their Slack workspace to Knock.

### Signing a user token

The only access you'll need to manage when using SlackKit are grants for your users to interact with their [Tenant](/concepts/tenants) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

You'll need to generate a token for your user that includes access to the tenant storing the Slack access token as well as any recipient objects storing Slack channel data described in this reference on [SlackKit resource access grants](/in-app-ui/react/slack-kit#resources-access-grants).

Using the below example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

const token = await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "org_3sh72ds78" }, [
      Grants.SlackChannelsRead,
    ]),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockSlackProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Adding provider components

In order to give your components the data they need, they must be wrapped in the `KnockSlackProvider`. We recommend putting this high in your component tree so that any Slack components that you use will be rendered within it. The Slack provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockSlackProvider
        knockSlackChannelId="Knock Slack channel ID"
        tenant="Tenant ID"
    >
        {child components}
    </KnockSlackProvider>
</KnockProvider>
```

The `KnockSlackProvider` gives your components access to the status of the connection to your Slack app, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Implementing the OAuth flow with `SlackAuthButton`

Your users will give your Slack app access to their own Slack workspaces via the `SlackAuthButton`. This button can be used on its own, or nested in the `SlackAuthContainer` for a bigger visual footprint.

<figure>
  <Image
    src="/images/integrations/chat/slack/slackauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The SlackAuthButton component with SlackAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>The SlackAuthButton component with SlackAuthContainer</figcaption>
</figure>

Since we'll also be using this `access_token` to resolve a user's email address to their Slack ID, we'll need to add some additional scopes to this OAuth request. We can do that by adding the `users:read` and `users:read.email` scopes to the `SlackAuthButton` component with the `additionalScopes` parameters.

Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with SlackAuthButton"
// Without container
<SlackAuthButton
    slackClientId="Slack app client ID"
    redirectUrl="The URL of your application to return to once Slack authorization is complete"
    additionalScopes={["users:read", "users:read.email"]}
/>

// With container
<SlackAuthContainer
    actionButton={
        <SlackAuthButton
            slackClientId="Slack app client ID"
            redirectUrl="The URL of your application to return to once Slack authorization is complete"
            additionalScopes={["users:read", "users:read.email"]}
        />
    }
/>
```

The `SlackAuthButton` maps a tenant in your product to a customer's Slack workspace. This means in most cases you'll just need a single instance of the `SlackAuthButton`.

Remember to consider which roles in your application can access the `SlackAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button and container in the settings area of your product.

### Resolving a user's Slack ID

To send a direct message to a user in Slack, you'll need to resolve their email address to their Slack ID. You can do this one of two ways: automatically using Knock's email-based user ID resolution, or manually by making a request to the Slack API with the `access_token` stored in Knock.

#### Enabling email-based user ID resolution

Knock's email-based user ID resolution handles the complexity of resolving a user's Slack ID for you. Here's how it works.

When the email-based user ID resolution setting is enabled and a workflow is triggered for a user recipient, Knock will automatically make a request to the <a href="https://api.slack.com/methods/users.lookupByEmail" target="_blank">`users.lookupByEmail` endpoint of the Slack API</a> to resolve the user's Slack ID before sending the message. When this Slack API request succeeds, Knock will automatically add the Slack user ID to the user's channel data so that the API request does not need to be repeated in the future. Note that this API request will only be made when the user has a [valid email attribute](/concepts/users#optional-attributes).

To use this feature, you must request the <a href="https://api.slack.com/scopes/users:read" target="_blank">`users:read`</a> and <a href="https://api.slack.com/scopes/users:read.email" target="_blank">`users:read.email`</a> scopes during the OAuth flow. See [How to connect Slack to Knock](/integrations/chat/slack/overview#how-to-connect-slack-to-knock) for more information about Slack scopes. If you're using SlackKit's `SlackAuthButton` component to manage the OAuth flow, you can use the `additionalScopes` prop to request these scopes.

```javascript title="Requesting the users:read and users:read.email scopes with SlackAuthButton"
// Without container
<SlackAuthButton
  slackClientId="Slack app client ID"
  redirectUrl="The URL of your application to return to once Slack authorization is complete"
  additionalScopes={["users:read", "users:read.email"]}
/>
```

<br />

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Important:</strong> If you enable the email-based user ID
      resolution setting but you haven't already been requesting the{" "}
      <code>users:read</code> and <code>users:read.email</code> scopes, any of
      your application's tenants who have already connected their Slack
      workspace to Knock will need to complete the OAuth flow again to
      re-authorize your app.{" "}
      <strong>Otherwise, the Slack API request will fail.</strong>
    </>
  }
/>

Once you're confident that all of your application's tenants have granted authorization with the required scopes, you can enable this setting on either a Slack channel or a step in a workflow.

<AccordionGroup>
  <Accordion title="Enabling email-based user ID resolution on a Slack channel">
    <Steps>
      <Step title="Open your Slack channel configuration">
        In the dashboard, navigate to the **Integrations** tab and select your
        Slack integration. Click the “Manage configuration” button for one of
        your environments to open the channel configuration dialog.
      </Step>
      <Step title="Enable the email-based user ID resolution setting">
        Locate the toggle labeled “Enable email-based user ID resolution” and
        toggle it on.

        <Image
          src="/images/integrations/chat/slack/enable-email-based-user-id-resolution-in-channel-config.png"
          width={1480}
          height={1536}
          alt="Channel configuration dialog with email-based user ID resolution setting"
          className="rounded-md mx-auto border border-gray-200"
        />
      </Step>
      <Step title="Save changes">
        Click the “Update settings” button to save your changes.
      </Step>
    </Steps>

  </Accordion>
  <Accordion title="Enabling email-based user ID resolution on a step in a workflow">
    <Steps>
      <Step title="Open your workflow">
        In the dashboard, navigate to the **Workflows** tab and select your
        workflow. Click on an existing Slack step in the workflow.
      </Step>
      <Step title="Enable the email-based user ID resolution setting">
        Under “Channel settings” in the right panel, locate the toggle labeled
        “Enable email-based user ID resolution” and toggle it on.

        <Image
          src="/images/integrations/chat/slack/enable-email-based-user-id-resolution-in-workflow-step.png"
          width={1333}
          height={1528}
          alt="Chat step configuration with email-based user ID resolution setting"
          className="rounded-md mx-auto border border-gray-200"
        />
      </Step>
    </Steps>

  </Accordion>
</AccordionGroup>

#### Manually resolving a user's Slack ID

If you wish to manually resolve a user's Slack ID from their email address, you can do so from your application's backend by making a request to the Slack API with the `access_token` stored in Knock. Here's an example of how you might create a `fetchUserId` function to do this using the Knock Node SDK:

```javascript
export async function fetchUserId(email: string): Promise<string> {
  // First, get the access token from Knock for the user's tenant
  const channelData = await knock.objects.getChannelData(
      "$tenants",
      'knocklabs',
      process.env.NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID as string,
    );
  // Next, use that access to to make a request to the Slack API
  const response = await fetch(
    `https://slack.com/api/users.lookupByEmail?email=${email}`,
    {
      headers: {
        Authorization: `Bearer ${channelData.data.token.access_token}`,
      },
    },
  );
  const data = await response.json();
  if (data.ok) {
    // If the request is successful, save the user's Slack ID as channel data on the user
    await knock.users.setChannelData(
      userId,
      process.env.NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID as string,
      {
        connections: [{ user_id: slackUserId }],
      },
    );
  }
  return data;
}
```

We'll break this function down step-by-step:

<Steps titleSize="h4">
  <Step title="Get the `access_token` stored in Knock for the user's tenant">
    Since your users have already connected their Slack workspace to Knock, you can use the `knockClient.objects.getChannelData` method to get the `access_token` for the user's tenant. Tenants in Knock are stored in a system-reserved object collection called `$tenants`.

    ```javascript
    await knock.objects.getChannelData(
        "$tenants",
        'knocklabs',
        process.env.NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID as string,
    );
    ```

  </Step>
  <Step title="Make a request to the Slack API">
    Once you have the tenant's `access_token`, you can use it to make a request to the Slack API to resolve the user's email address to their Slack ID using the `users.lookupByEmail` endpoint.

    ```javascript
    const response = await fetch(
      `https://slack.com/api/users.lookupByEmail?email=${email}`,
      {
        headers: {
          Authorization: `Bearer ${channelData.data.token.access_token}`,
        },
      },
    );
    ```

  </Step>
  <Step title="Save the user's Slack ID as channel data on the user">
    Assuming the request to the Slack API is successful, you can save the user's Slack ID as channel data on the user in Knock. This will allow you to send messages to the user's Slack DM channel.

    ```javascript
    await knock.users.setChannelData(
        userId,
        process.env.NEXT_PUBLIC_KNOCK_SLACK_CHANNEL_ID as string,
        {
            connections: [{ user_id: slackUserId }],
        },
    );
    ```

  </Step>
</Steps>

## Triggering a workflow

Once you have saved the user's Slack ID as channel data, you can trigger a workflow to send a message to that user's DM channel. Here's an example of how to trigger a workflow using the Knock Node SDK:

```javascript
const workflow_run_id = await knockClient.workflows.trigger("new-issue", {
  recipients: ["user_1n38knd"],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```


## Sending a message to channels
How to configure and send notifications to Slack channels.
---
title: Sending a message to public and private channels
description: "How to configure and send notifications to Slack channels."
tags: ["slack", "chat"]
section: Integrations > Slack
layout: integrations
---

In this guide we'll cover how to create a self-serve Slack integration for a multi-tenant application using Knock. It assumes that you have already created a Slack app and created a Slack channel in Knock as outlined in the [Slack integration overview](/integrations/chat/slack/overview) guide.

In this implementation, your application's users will connect their Slack workspace to Knock and be able to send messages to public and private channels. To make this easier to implement, we'll use Knock's [SlackKit components](/in-app-ui/react/slack-kit) to facilitate the OAuth flow and channel selection process.

Here's what we'll cover in this guide:

- Modeling a multi-tenant application in Knock using `Tenants` and `Objects`
- Implementing a Slack OAuth flow using Knock's `SlackAuthButton` component
- Choosing channels to send messages to using Knock's `SlackChannelCombobox` component
- Triggering a workflow with an object recipient to send a message to a Slack channel

## Key concepts

SlackKit connects multiple concepts in Knock to make it easier for your users to create a Slack integration. There are two key concepts you'll see throughout the following docs that are foundational to how SlackKit works, but might not be used in every implementation of Knock: tenants and objects.

### About tenants

[Tenants](/concepts/tenants) in Knock are meant to represent groups of users who typically share the same resources. You might call these "accounts," "organizations," "workspaces," or something similar. In a standard SlackKit implementation, you'll store a Slack workspace's `access_token` on a corresponding tenant in Knock.

If you already use Knock's tenant concept to power other 'account-based' features, you likely create tenants in Knock when an account or organization is created in your application. If you don't already use tenants in Knock, SlackKit can create tenants for you on the fly if they don't already exist.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      Our best-practice recommendation is that tenants in Knock should map one-to-one
      to whatever abstraction you use to model accounts, organizations, or workspaces.
      You can think of tenants as the top-level container within your data model
      that you use to power multi-tenancy in your application.
    </>
  }
/>

### About objects

[Objects](/concepts/objects) in Knock are flexible abstractions meant to map to a resource in your system. Each individual object in Knock exists within a `collection` and requires an `id` unique to that collection.

In the context of SlackKit, objects serve two purposes. First, they store the Slack channel or channels you want to notify. Second, they act as the recipient of the workflow that sends a message to Slack.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      You can think of collections as the different tables within your database that
      represent resources in your application. Objects are the rows within those
      tables.
    </>
  }
/>
#### Example

Let's say we're building an example source control application like GitHub, where teams can collaborate and share code repositories. In this context, each GitHub organization would map to a tenant in Knock, and each repository would become an object inside of a `repositories` collection.

If we want to be notified in Slack each time an issue is opened against a repository, we would store a Slack channel on each repository object and then trigger a `new-issue` workflow. Knock will use the data stored on the object and tenant to route a message to the correct Slack channel:

```javascript
await knockClient.workflows.trigger("new-issue", {
  recipients: [
    {
      collection: "repositories",
      id: "knocklabs/javascript",
    },
  ],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```

### Merging channel data

In this implementation, we'll actually store [the required channel data](/in-app-ui/react/slack-kit#channel-data-requirements) for a `SlackConnection` across two different entities in Knock: a `Tenant` and an `Object`. This is because we want to store the `access_token` for the Slack workspace on the `Tenant` and the `channel_id` for the Slack channel on the `Object`.

When you trigger a workflow using this recipient and tenant, Knock will merge the channel data from the `Tenant` and the `Object` to send the message to the correct Slack channel. By storing the `access_token` on the `Tenant`, your customers only need to complete the OAuth flow once to connect their Slack workspace to Knock.

## Implementing SlackKit

To facilitate the OAuth flow and channel selection process, we'll use Knock's [SlackKit components](/in-app-ui/react/slack-kit). SlackKit is a set of React components that make it easier to build Slack integrations in Knock. You can use SlackKit to build a self-serve Slack integration that allows your application's users to connect their Slack workspace to Knock and send messages to public and private channels.

### Signing a user token

The only access you'll need to manage when using SlackKit are grants for your users to interact with their [Tenants](/concepts/tenants) and [Objects](/concepts/objects) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

You'll need to generate a token for your user that includes access to the tenant storing the Slack access token as well as any recipient objects storing Slack channel data described in this reference on [SlackKit resource access grants](/in-app-ui/react/slack-kit#resources-access-grants).

Using the below example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

const token = await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "org_3sh72ds78" }, [
      Grants.SlackChannelsRead,
    ]),
    Knock.buildUserTokenGrant(
      { type: "object", id: "repo-1", collection: "repositories" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockSlackProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Adding provider components

In order to give your components the data they need, they must be wrapped in the `KnockSlackProvider`. We recommend putting this high in your component tree so that any Slack components that you use will be rendered within it. The Slack provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockSlackProvider
        knockSlackChannelId="Knock Slack channel ID"
        tenant="Tenant ID"
    >
        {child components}
    </KnockSlackProvider>
</KnockProvider>
```

The `KnockSlackProvider` gives your components access to the status of the connection to your Slack app, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Implementing the OAuth flow with `SlackAuthButton`

Your users will give your Slack app access to their own Slack workspaces via the `SlackAuthButton`. This button can be used on its own, or nested in the `SlackAuthContainer` for a bigger visual footprint.

<figure>
  <Image
    src="/images/integrations/chat/slack/slackauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The SlackAuthButton component with SlackAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>The SlackAuthButton component with SlackAuthContainer</figcaption>
</figure>

Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with SlackAuthButton"
// Without container
<SlackAuthButton
    slackClientId="Slack app client ID"
    redirectUrl="The URL of your application to return to once Slack authorization is complete"
/>

// With container
<SlackAuthContainer
    actionButton={
        <SlackAuthButton
            slackClientId="Slack app client ID"
            redirectUrl="The URL of your application to return to once Slack authorization is complete"
        />
    }
/>
```

The `SlackAuthButton` maps a tenant in your product to a customer's Slack workspace. This means in most cases you'll just need a single instance of the `SlackAuthButton`.

Remember to consider which roles in your application can access the `SlackAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button and container in the settings area of your product.

### Choosing channels with `SlackChannelCombobox`

This combobox contains the list of channels in the connected Slack workspace. You users will use this combobox to search and select a channel (or more than one channel) to be notified when an event in your application occurs, for example a comment on a video. They can also use this combobox to deselect a connected channel.

The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well.

<figure>
  <Image
    src="/images/integrations/chat/slack/slackchannelcombobox.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The SlackChannelCombobox component showing connected channels"
    width={1880}
    height={701}
  />
  <figcaption>
    The SlackChannelCombobox component showing connected channels
  </figcaption>
</figure>

Add your combobox to your application where you'd like the user to select channels to notify:

```javascript title="The SlackChannelCombobox connects an object to one or more channels"
<SlackChannelCombobox
  slackChannelsRecipientObject={{
    id: "object id",
    collection: "object collection",
  }}
/>
```

<br />
<Callout
  emoji="🚨"
  text={
    <>
      <strong>Limitations</strong>
      <ul>
        <li>
          The combobox will only show channels for Slack workspaces with fewer
          than 1000 channels (public and private; not including archived). If
          there are more, the combobox will turn into a text input that accepts
          a channel ID to connect.
        </li>
        <li>
          The combobox will only show private channels from your users' Slack
          workspaces if your Slack app has been invited to those channels.
        </li>
        <li>
          The combobox does not show individual users for Slack direct messages.
        </li>
      </ul>
    </>
  }
/>

## Triggering a workflow

Once you have used the `SlackChannelCombobox` to connect an object to one or more channels, you can trigger a workflow to send a message to those channels. Here's an example of how to trigger a workflow using the Knock Node SDK:

```javascript
const workflow_run_id = await knockClient.workflows.trigger("new-issue", {
  recipients: [
    {
      collection: "repositories",
      id: "knocklabs/javascript",
    },
  ],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```


## Microsoft Teams

## Overview
Learn how to use Knock to send Microsoft Teams notifications to your users.
---
title: Microsoft Teams notifications with Knock
description: Learn how to use Knock to send Microsoft Teams notifications to your users.
tags: ["msteams", "teams", "chat"]
section: Integrations > Microsoft Teams
layout: integrations
---

In this guide you'll learn how to use Knock to send notifications to Microsoft Teams. Depending on your use case, there are a few different ways to approach this integration. This guide serves as a starting point and will cover the basics of setting up a Microsoft Teams integration with Knock regardless of your use case.

Here's what we'll cover in this guide.

- The different methods of sending notifications to Microsoft Teams
- How to add a Microsoft Teams channel to your Knock instance
- How to store Microsoft Teams connection data in Knock using channel data
- How to design notification templates for Teams

## Supported notification methods

Today, Knock supports sending notifications to Microsoft Teams using two different methods:

- Using an incoming webhook URL. This is suitable for [internal or one-off integrations](/integrations/chat/microsoft-teams/sending-an-internal-message).
- As a Microsoft Teams bot, via Microsoft Bot Framework. This is suitable for multi-tenant integrations, and supports both [sending notifications to channels](/integrations/chat/microsoft-teams/sending-a-message-to-channels) and [sending direct messages to users](/integrations/chat/microsoft-teams/sending-a-direct-message).

How you configure your Microsoft Teams channel in Knock depends on the method you choose.

## How to connect to Teams with Knock

### Prerequisites

If you're using an incoming webhook URL, there are no prerequisites.

If you're using a Microsoft Teams bot, make sure your bot has been registered with <a href="https://dev.botframework.com/" target="_blank">Microsoft Bot Framework</a> and is deployed to Azure. Knock does not manage deploying and configuring your bot. To set up Knock to send notifications as your bot, you'll need your bot's ID and password. These are sometimes called the App ID and App Password, and were provided to you when you registered your bot with Microsoft Bot Framework.

Additionally, if you intend to use [TeamsKit](/in-app-ui/react/teams-kit) or Knock's [Microsoft Teams-related React hooks](/in-app-ui/react/teams-kit#using-teamskit-headless), you'll need to [configure your bot in the Microsoft Entra admin center](#configuring-your-bot-in-microsoft-entra).

### Add Teams to Knock as a channel

First you'll need to add Teams as a channel in Knock. Navigate to the “Channels” page within Knock and click “Create channel” to add Microsoft Teams.

If you're using an incoming webhook URL, no additional environment configuration is required.

If you're using a Microsoft Teams bot, click “Manage configuration”, scroll down to “Provider settings”, and enter the ID and password associated with your bot.

### Add a Teams channel step to a workflow

Next, navigate to a workflow in Knock that you want to notify Teams and add a chat channel step. Select the Teams channel you just configured and create a notification template for the channel.

You can learn more about how to write basic and advanced templates for Teams in the [designing notifications templates section](#designing-notification-templates-for-teams) of this guide.

### Trigger the workflow

Now you're ready to notify Teams. [Trigger the workflow](/send-notifications/triggering-workflows) that you added your Teams channel to. You'll need to include the user or object that has your Teams channel data as a `recipient` on the workflow trigger call.

<MultiLangCodeBlock
  snippet="workflows.trigger-with-object-as-recipient"
  title="Trigger a workflow with an object recipient"
/>

Your Teams channel should have received a notification. If you need to debug your integration, you can view the logs page in the Knock dashboard.

## Configuring your bot in Microsoft Entra

To use TeamsKit, you'll need to configure the API permissions and OAuth redirect URL associated with your Microsoft Teams bot in the Microsoft Entra admin center.

<Steps titleSize="h3">
  <Step title="Find your bot in the Microsoft Entra admin center">
    Log in to the <a href="https://entra.microsoft.com/" target="_blank">Microsoft Entra admin center</a>. In the sidebar, navigate to **Identity** > **Applications** > **App registrations**, and locate your bot.
  </Step>
  <Step title="Add a redirect URL">
    On your bot's app registration page, click **Authentication**. Under **Platform configurations**, click **Add a platform** and select **Web**.

    Copy and paste the following URL into the **Redirect URI** text field:

    <CopyableText
      label="https://api.knock.app/providers/ms-teams/authenticate"
      content="https://api.knock.app/providers/ms-teams/authenticate"
    />

    This will allow Knock to handle the OAuth redirect on behalf of your bot, and manage connecting a Microsoft Entra tenant to a Knock tenant.

    Leave the **Front-channel logout URL** text field empty. Click **Configure** to save your changes.

  </Step>
  <Step title="Add API permissions">
    In the top-level sidebar, navigate to **API permissions** and click **Add a permission**. Select **Microsoft Graph** > **Application permissions**.

    Under **Select permissions**, add the following permissions:

    - `Team.ReadBasic.All`: This permission allows your bot to read a list of all teams within a Microsoft Entra tenant.
    - `Channel.ReadBasic.All`: This permission allows your bot to read a list of all channels within a team.
    - `AppCatalog.Read.All`: This permission allows your bot to locate itself in the Microsoft Teams app catalog.
    - `TeamsAppInstallation.ReadWriteSelfForTeam.All`: This permission allows your bot to install itself into a team.
    - `TeamsAppInstallation.ReadWriteSelfForUser.All`: This permission allows your bot to install itself into a user's personal scope.

    Click **Add permissions** to save your changes.

  </Step>
</Steps>

## How to set channel data for a Microsoft Teams integration in Knock

In Knock, the [`ChannelData`](/managing-recipients/setting-channel-data) concept provides you a way of storing recipient-specific connection data for a given integration. If you reference the [channel data requirements for Microsoft Teams](/managing-recipients/setting-channel-data#chat-app-channels), you'll see that there are two different schemas for an `MsTeamsConnection` stored on a [`User`](/concepts/users) or an [`Object`](/concepts/objects) in Knock.

Here's an example of setting channel data on an `Object` in Knock.

<MultiLangCodeBlock
  snippet="objects.setChannelData.msTeams"
  title="Store Microsoft Teams connection on object"
/>

<br />

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Potential confusion alert.</span> In the
      example above, the <code>KNOCK_TEAMS_CHANNEL_ID</code> variable is the id
      of the Knock channel you've created to represent your Microsoft Teams
      integration within the Knock dashboard. You can find it by going to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard and
      then copying the ID of your Microsoft Teams channel.
    </>
  }
/>

### Recipient channel data requirements

Here's an overview of the data requirements for [setting recipient channel data](/send-notifications/setting-channel-data) for either an incoming webhook URL or a Microsoft Teams bot connection. Both will need to live under the `connections` key.

| Property    | Type                  | Description                                |
| ----------- | --------------------- | ------------------------------------------ |
| connections | `MsTeamsConnection[]` | One or more connections to Microsoft Teams |

An `MsTeamsConnection` can have one of two schemas, depending on whether you're using a Microsoft Teams bot or an incoming webhook.

<AccordionGroup>
  <Accordion title="MsTeamsConnection as a bot" description="For self-serve customer integrations">
    If you're using a Microsoft Teams bot, your `MsTeamsConnection` schema looks like this. You'll use
    either `ms_teams_channel_id` or `ms_teams_user_id` depending on whether you're storing connection data to message a channel or user in Microsoft Teams:

    | Property            | Type     | Description                    |
    | ------------------- | -------- | ------------------------------ |
    | ms_teams_tenant_id  | `string` | A Microsoft Entra tenant ID    |
    | ms_teams_team_id    | `string` | A Microsoft Teams team ID      |
    | ms_teams_channel_id | `string` | A Microsoft Teams channel ID   |
    | ms_teams_user_id    | `string` | A Microsoft Teams user ID      |

  </Accordion>
  <Accordion title="MsTeamsConnection with an incoming webhook url" description="For internal or one-off integrations">
     If you're using an incoming webhook, your `MsTeamsConnection` schema is quite simple:

    | Property             | Type     | Description                                                                 |
    | -------------------- | -------- | --------------------------------------------------------------------------- |
    | incoming_webhook.url | `string` | The Microsoft Teams incoming webhook URL (to be used instead of the properties above) |

  </Accordion>
</AccordionGroup>

### Tenant channel data requirements

When you [map a Microsoft Entra tenant to a Knock tenant](/integrations/chat/microsoft-teams/sending-a-message-to-channels#key-concepts), you'll store the ID of the Microsoft Entra tenant as `channel_data` on the Knock tenant. Then, when you apply the Knock `tenant` to your workflow triggers, Knock will [combine that Microsoft Entra tenant ID with the recipient's](/integrations/chat/microsoft-teams/sending-a-message-to-channels#merging-channel-data) `channel_data` to send notifications to the correct Microsoft Teams channel within a Microsoft Entra tenant. For this implementation method, the `ms_teams_tenant_id` on the recipient's `MsTeamsConnection[]` data above is not required.

Here's an overview of the data requirements for setting channel data when storing a Microsoft Entra tenant ID on a Knock tenant.

| Property           | Type     | Description                 |
| ------------------ | -------- | --------------------------- |
| ms_teams_tenant_id | `string` | A Microsoft Entra tenant ID |

```json title="Microsoft Teams channel_data on a tenant"
{
  "ms_teams_tenant_id": "MS_TEAMS_TENANT_ID"
}
```

### Setting channel data: users vs. objects

Depending on the Microsoft Teams integration you build into your product, you'll store the connection data you receive from Microsoft Teams as `channel_data` on either a `User` or an `Object` in Knock.

<AccordionGroup>
  <Accordion title="Users" description="For notifying users via direct message">
    If your integration involves a user opting in to receive direct messages from your Microsoft Teams integration, you’ll be storing the channel data [on that user](/reference#set-user-channel-data) in Knock. When you want to notify this user, you'll include them as a recipient in a Knock workflow trigger.

    For this integration, you'll store a user's Microsoft Teams `ms_teams_user_id` in the `MsTeamsConnection` object.

  </Accordion>
  <Accordion title="Objects" description="For notifying Microsoft Teams channels about non-user resources">
    If your integration involves a customer connecting a _non-user resource_ in their product (such as a project or a page) to a Microsoft Teams channel, you’ll want to store that channel data [on an object](/reference#set-object-channel-data) in Knock, as it’s not specific to any single user.

    For this integration, you'll store a Microsoft Teams `ms_teams_channel_id` in the `MsTeamsConnection` object. The [`MsTeamsChannelCombobox`](/in-app-ui/react/teams-kit#msteamschannelcombobox) component of Knock's TeamsKit can help you with this.

  </Accordion>
</AccordionGroup>

## Designing notification templates for Teams

When you add a new Teams channel step to a workflow in Knock, you'll need to configure a template for that step so Knock knows how to format the message to Teams.

By default, we provide a basic markdown editor that you can use for sending simple messages to Teams. Just write in Markdown and we'll handle the rest. (Note: As of February 2022, Teams only supports the following markdown styles: bold, italic, unordered lists, ordered lists, hyperlinks. All other markdown styles are not supported.)

### Advanced Teams notifications

If you find yourself wanting to send notifications that include more advanced formatting and interactivity, such as buttons, data layouts, and so on, you'll need to use Microsoft's [adaptive card format](https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#adaptive-card) to build your notification templates in Knock. This is essentially a JSON block language you use to lay out your Teams message.

To switch to the JSON editor in the Knock template designer, look for the "Switch to JSON editor" button at the bottom of the template editor page. When you're in JSON editing mode, you can provide adaptive card JSON and we'll pass it to Teams on your behalf.

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note:</strong> We do not support adaptive card previews in Knock
      at this time.
    </>
  }
/>

---

What did you think of this guide? Did we miss any key steps? Did you run into a blocker? Let us know using the feedback component at the top of this page. 🙏


## Sending an internal message
How to send a message to an internal Microsoft Teams workspace using Knock.
---
title: Sending a message to an internal Microsoft Teams workspace
description: How to send a message to an internal Microsoft Teams workspace using Knock.
tags: ["msteams", "teams", "chat"]
section: Integrations > Microsoft Teams
layout: integrations
---

In this guide we'll cover how to send a message to an internal Microsoft Teams workspace using Knock. It assumes that you have already created a Microsoft Teams channel in Knock as outlined in the [Microsoft Teams integration overview](/integrations/chat/microsoft-teams/overview) guide.

Here's what we'll cover in this guide:

- Retrieving an incoming webhook URL from Microsoft Teams
- Setting channel data for an `Object` in Knock
- Triggering a workflow with an object recipient to send a message to a Microsoft Teams channel

## Microsoft Teams channels are connections on Objects

In Knock, we model channels in a Microsoft Teams workspace as connections on Objects. [Objects](/concepts/objects) allow you to model any resource in your system within Knock, and while their primary purpose is to act as non-user recipients, they are very flexible abstractions.

### An overview of Objects

Individual Objects exist within [a collection](/concepts/objects#collection-naming) and always have [a unique ID](/concepts/objects#the-object-identifier) or key within that collection. The Object itself can store any number and type of properties as key-value pairs. You can see some examples of possible Object structures in [the official documentation on setting Object data](/concepts/objects#sending-object-data-to-knock).

Let’s say you are building a devtool product like GitHub and want to set up Microsoft Teams notifications whenever someone comments on an issue within a repository. First, you’ll want to create an Object to model your repository as part of the `repositories` collection:

```javascript
import { Knock } from "@knocklabs/node";
const knockClient = new Knock(process.env.KNOCK_API_KEY);

await knockClient.objects.set("repositories", "repo-1", {
  name: "My repo",
});
```

Once you have a repository object created, you can add the channel data for Microsoft Teams as a connection on the object.

## Objects as workflow recipients

To add channel data, we’ll set up an incoming webhook in Microsoft Teams. There are two ways to generate an incoming webhook URL for a Teams channel:

1. Your customer can [create an incoming webhook](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) and send it to you.
2. You can [build a Microsoft 365 Connector](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-creating) that your customers will install in Teams and add to their channels. When a customer adds your Connector to a channel, you receive an incoming webhook URL.

Whichever method you choose, the end result is the same: an incoming webhook URL.

### Set the webhook as channel data

Now that you have the webhook URL, we’ll store that webhook as a special property on the repository Object called channel data. [Channel data is both channel and recipient-specific data](https://docs.knock.app/managing-recipients/setting-channel-data) stored for use with particular channels, like a token used for push notifications or webhooks stored for chat apps like Slack, Teams, and Discord. Both Users and Objects can store channel data.

In the code example below, we’ll use the `knockClient.objects.setChannelData` method to update the channel data for our repository Object.

```javascript
import { Knock } from "@knocklabs/node";
const knockClient = new Knock(process.env.KNOCK_API_KEY);

await knockClient.objects.setChannelData(
  "repositories",
  repository.id,
  process.env.KNOCK_MS_TEAMS_CHANNEL_ID,
  {
    connections: [
      {
        incoming_webhook: { url: "url-from-ms-teams" },
      },
    ],
  },
);
```

Here, you’ll also need your `KNOCK_MS_TEAMS_CHANNEL_ID` as the third parameter, which is the channel ID of your Microsoft Teams integration within Knock, so that Knock can reference that channel when it processes workflows that use it. The last parameter is an object of a specific format that varies based on [the type of message provider](/managing-recipients/setting-channel-data#provider-data-requirements). In this case, it is an `MsTeamsConnection` object with an `incoming_webhook` property that contains the URL of an incoming webhook in Microsoft Teams.

### Trigger a workflow with an object recipient

With the channel data in place, you can add Microsoft Teams as a workflow step in any workflow. For this example, we’ll create a `new-issue` workflow that pings users in our connected Microsoft Teams channel whenever someone adds a new issue.

<Image
  src="/images/integrations/chat/microsoft-teams/workflow-with-microsoft-teams-step.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="A workflow with a Microsoft Teams step"
  width={2202}
  height={1922}
/>

As you create your message template, remember that in this case the repository Object is the recipient of your workflow. That means any properties you reference on your Liquid template tags need to exist as properties of the Object as well:

```markdown
There was an issue opened on the following repo: **{{ recipient.name }}**
```

Finally, we’ll add the workflow trigger to our code with the repository Object as a recipient.

```javascript
const { Knock } = require("@knocklabs/node");
const knock = new Knock(process.env.KNOCK_API_KEY);

await knock.workflows.trigger("new-issue", {
  recipients: [{ collection: "repositories", id: "repo-1" }],
});
```

With that, you should see a message in your selected Microsoft Teams channel:

<Image
  src="/images/integrations/chat/microsoft-teams/microsoft-teams-message.png"
  className="rounded-md mx-auto border border-gray-200"
  alt="A Microsoft Teams message"
  width={2000}
  height={552}
/>


## Sending a direct message
How to send a message to a user in Microsoft Teams using Knock.
---
title: Sending a direct message to a user in Microsoft Teams
description: How to send a message to a user in Microsoft Teams using Knock.
tags: ["msteams", "teams", "chat"]
section: Integrations > Microsoft Teams
layout: integrations
---

In this guide, we'll cover how to update a multi-tenant Microsoft Teams bot to send direct messages to Teams users using Knock. It assumes that you have already created a Microsoft Teams channel in Knock as outlined in the [Microsoft Teams integration overview](/integrations/chat/microsoft-teams/overview) guide.

In this implementation, your application's users will connect their Microsoft Entra tenant to Knock and be able to send messages to individual users via direct message. To make this easier to implement, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit) to facilitate the OAuth flow.

Here's what we'll cover in this guide:

- Modeling a multi-tenant application in Knock using `Tenants`
- Adding required scopes to your Microsoft Teams app's manifest
- Implementing a Microsoft OAuth flow using Knock's `MsTeamsAuthButton` component
- Setting required User channel data when a Microsoft Teams bot is installed in a user's personal scope
- Triggering a workflow with a user recipient to send a direct message to a Teams user

## Prerequisites

Make sure your bot has been registered with <a href="https://dev.botframework.com/" target="_blank">Microsoft Bot Framework</a> and is deployed to Azure. Knock does not manage deploying and configuring your bot. To set up Knock to send notifications as your bot, see [How to connect to Teams with Knock](/integrations/chat/microsoft-teams/overview#how-to-connect-to-teams-with-knock).

## Key concepts

TeamsKit connects multiple concepts in Knock to make it easier for your application's users to start using your Microsoft Teams integration. `Tenants` are a concept you'll see throughout the following docs that are foundational to how TeamsKit works, but might not be used in every implementation of Knock.

### About tenants

[Tenants](/concepts/tenants) in Knock are meant to represent groups of users who typically share the same resources. You might call these "accounts," "organizations," "workspaces," or something similar. In a typical implementation using TeamsKit, you'll store <a href="https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant" target="_blank">the ID of a Microsoft Entra tenant</a> on a corresponding tenant in Knock.

If you already use Knock's tenant concept to power other 'account-based' features, you likely create tenants in Knock when an account or organization is created in your application. If you don't already use tenants in Knock, TeamsKit can create tenants for you on the fly if they don't already exist.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      Our best-practice recommendation is that tenants in Knock should map one-to-one
      to whatever abstraction you use to model accounts, organizations, or workspaces.
      You can think of tenants as the top-level container within your data model
      that you use to power multi-tenancy in your application.
    </>
  }
/>

### Merging channel data

In this implementation, we'll actually store [the required channel data](/integrations/chat/microsoft-teams/overview#how-to-set-channel-data-for-a-microsoft-teams-integration-in-knock) for an `MsTeamsConnection` across two different entities in Knock: a `Tenant` and an `User`. This is because we want to store the `ms_teams_tenant_id` for the Microsoft Entra tenant on the Knock `Tenant` and the `ms_teams_user_id` for the Microsoft Teams user on the Knock `User`.

When you trigger a workflow using this recipient and tenant, Knock will merge the channel data from the `Tenant` and the `User` to send the message to the correct Microsoft Teams user. By storing the `ms_teams_tenant_id` on the Knock `Tenant`, your customers only need to complete the OAuth flow once to connect their Microsoft Teams instances to Knock. From there, you can create UI that allows users to link their Microsoft Teams user ID to their Knock user ID or automate this process during user registration.

## Adding required scopes to your app's manifest

In order for your bot to send direct messages to users in Microsoft Teams, you'll need to update your <a href="https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema" target="_blank">Microsoft Teams app's manifest</a> so that it includes the `personal` scope for your bot.

In your `manifest.json` file, add `personal` to your bot's array of scopes:

```json
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "version": "1.0.0",
  "id": "{{YOUR_TEAMS_APP_ID}}",
  "bots": [
    {
      "botId": "{{YOUR_BOT_ID}}",
      "scopes": ["personal"]
    }
  ]
}
```

## Implementing TeamsKit

To facilitate the OAuth flow and channel selection process, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit). TeamsKit is a set of React components that make it easier to build Microsoft Teams integrations in Knock. You can use TeamsKit to build a self-serve Microsoft Teams integration that allows your users to connect their Microsoft Teams instances to Knock.

### Signing a user token

The only access you'll need to manage when using TeamsKit are grants for your users to interact with their [Tenant](/concepts/tenants) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

You'll need to generate a token for your user that includes access to the Knock tenant storing the Microsoft Entra tenant ID as well as any recipient objects storing Microsoft Teams channel data described in this reference on [TeamsKit resource access grants](/in-app-ui/react/teams-kit#resource-access-grants).

Using the below example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

const token = await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "org_3sh72ds78" }, [
      Grants.MsTeamsChannelsRead,
    ]),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockMsTeamsProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Adding provider components

In order to give your components the data they need, they must be wrapped in the `KnockMsTeamsProvider`. We recommend putting this high in your component tree so that any TeamsKit components that you use will be rendered within it. The Microsoft Teams provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockMsTeamsProvider
        knockMsTeamsChannelId="Knock Microsoft Teams channel ID"
        tenantId="Knock tenant ID"
    >
        {child components}
    </KnockMsTeamsProvider>
</KnockProvider>
```

The `KnockMsTeamsProvider` gives your components access to the status of the connection to your Microsoft Teams bot, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Implementing the OAuth flow with `MsTeamsAuthButton`

<figure>
  <Image
    src="/images/integrations/chat/microsoft-teams/msteamsauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The MsTeamsAuthButton component with MsTeamsAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>
    The MsTeamsAuthButton component with MsTeamsAuthContainer
  </figcaption>
</figure>

Your users will give your Microsoft Teams bot access to their own Microsoft Entra tenants via the `MsTeamsAuthButton`. This button can be used on its own, or nested in the `MsTeamsAuthContainer` for a bigger visual footprint. Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with MsTeamsAuthButton"
// Without container
<MsTeamsAuthButton
    msTeamsBotId="Microsoft Teams bot ID"
    redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
/>

// With container
<MsTeamsAuthContainer
    actionButton={
        <MsTeamsAuthButton
            msTeamsBotId="Microsoft Teams bot ID"
            redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
        />
    }
/>
```

The `MsTeamsAuthButton` maps a tenant in your product to a customer's Microsoft Entra tenant. This means in most cases you'll just need a single instance of the `MsTeamsAuthButton`.

Remember to consider which roles in your application can access the `MsTeamsAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button/container in the settings area of your product.

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note:</strong> The <code>MsTeamsAuthButton</code> component does
      not automatically install your Microsoft Teams bot into a user's personal
      scope. Your users will need to{" "}
      <a
        href="https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77"
        target="_blank"
      >
        manually install your bot into their personal scope
      </a>{" "}
      before you can send direct messages to them. Alternatively, provide
      instructions to your app's admins to{" "}
      <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps"
        target="_blank"
      >
        preinstall your bot for all Microsoft Teams users in their organization
      </a>
      .
    </>
  }
/>

## Setting User channel data

Once your Microsoft Teams bot is installed in a user's personal scope, your bot's messaging endpoint will receive <a href="https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/subscribe-to-conversation-events#installation-update-event" target="_blank">an installation update event</a>. You can use this event to update the channel data associated with the Knock `User`.

In order to determine the user ID of the Knock `User`, you'll likely want to query your application's database based on the attributes of the Microsoft Teams user who installed your bot. The <a href="https://learn.microsoft.com/en-us/graph/api/user-get" target="_blank">get user API of the Microsoft Graph API</a> provides a convenient way to look up the email address of the user who installed your bot.

If you're using the <a href="https://github.com/microsoft/botbuilder-js" target="_blank">Bot Framework SDK for JavaScript</a> and the <a href="https://github.com/microsoftgraph/msgraph-sdk-javascript" target="_blank">Microsoft Graph JavaScript client library</a> with the Knock Node SDK, your code will look something like this:

```javascript
import { Knock } from "@knocklabs/node";
import { Client } from "@microsoft/microsoft-graph-client";

const knockClient = new Knock(process.env.KNOCK_API_KEY);

const graphApiClient = Client.initWithMiddleware({
  // Initialize your Microsoft Graph API client here
});

export class TeamsBot extends TeamsActivityHandler {
  constructor() {
    super();
    this.onInstallationUpdateAdd(async (context, next) => {
      const { activity } = context;

      // Bot was installed into a user's personal scope
      if (activity.conversation.conversationType === "personal") {
        // The unique ID of the Microsoft user in Entra
        const { aadObjectId } = activity.from;

        // Get the user's email address via the Microsoft Graph API
        const userDetails = await graphApiClient
          .api(`/users/${aadObjectId}`)
          .get();
        const emailAddress = userDetails.mail;

        const knockUserId = getKnockUserIdFromEmailAddress(emailAddress);

        // This user ID is unique to the Microsoft Teams user AND your bot
        const msTeamsUserId = activity.from.id;

        knockClient.users
          .setChannelData(knockUserId, process.env.KNOCK_MS_TEAMS_CHANNEL_ID, {
            connections: [{ ms_teams_user_id: msTeamsUserId }],
          })
          .catch(console.error);
      }

      await next();
    });
  }
}
```

Here, `KNOCK_MS_TEAMS_CHANNEL_ID` is the channel ID of your Microsoft Teams integration within Knock. `getKnockUserIdFromEmailAddress` is a function that you'll need to implement to look up a Knock `User` ID in your application's database for a given email address. How you get this ID depends upon your specific application.

Please keep in mind that if you intend to use the Microsoft Graph API in this fashion, you'll need to add the `User.Read.All` API permission when [configuring your bot in Microsoft Entra](/integrations/chat/microsoft-teams/overview#configuring-your-bot-in-microsoft-entra).

## Triggering a workflow

Once you have saved the user's Microsoft Teams user ID as channel data, you can trigger a workflow to send a message to that user's DM channel. Here's an example of how to trigger a workflow using the Knock Node SDK:

```javascript
const workflow_run_id = await knockClient.workflows.trigger("new-issue", {
  recipients: ["user_1n38knd"],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```


## Sending a message to channels
How to send a message to public channels in Microsoft Teams using Knock.
---
title: Sending a message to public channels
description: How to send a message to public channels in Microsoft Teams using Knock.
tags: ["msteams", "teams", "chat"]
section: Integrations > Microsoft Teams
layout: integrations
---

In this guide, we'll cover how to update a multi-tenant Microsoft Teams bot to send messages to channels in Microsoft Teams using Knock. It assumes that you have already created a Microsoft Teams channel in Knock as outlined in the [Microsoft Teams integration overview](/integrations/chat/microsoft-teams/overview) guide.

In this implementation, your application's users will connect their Microsoft Entra tenant to Knock and be able to send messages to public channels. To make this easier to implement, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit) to facilitate the OAuth flow and channel selection process.

Here's what we'll cover in this guide:

- Modeling a multi-tenant application in Knock using `Tenants`
- Adding required scopes to your Microsoft Teams app's manifest
- Implementing a Microsoft OAuth flow using Knock's `MsTeamsAuthButton` component
- Choosing public channels to send messages to using Knock's `MsTeamsChannelCombobox` component
- Triggering a workflow with an object recipient to send a message to a Microsoft Teams channel

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note:</strong> Microsoft Teams bots do not support sending
      messages to private channels.
    </>
  }
/>

## Prerequisites

Make sure your bot has been registered with <a href="https://dev.botframework.com/" target="_blank">Microsoft Bot Framework</a> and is deployed to Azure. Knock does not manage deploying and configuring your bot. To set up Knock to send notifications as your bot, see [How to connect to Teams with Knock](/integrations/chat/microsoft-teams/overview#how-to-connect-to-teams-with-knock).

## Key concepts

TeamsKit connects multiple concepts in Knock to make it easier for your users to create a Microsoft Teams integration. There are two key concepts you'll see throughout the following docs that are foundational to how TeamsKit works, but might not be used in every implementation of Knock: tenants and objects.

### About tenants

[Tenants](/concepts/tenants) in Knock are meant to represent groups of users who typically share the same resources. You might call these "accounts," "organizations," "workspaces," or something similar. In a typical implementation using TeamsKit, you'll store <a href="https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant" target="_blank">the ID of a Microsoft Entra tenant</a> on a corresponding tenant in Knock.

If you already use Knock's tenant concept to power other 'account-based' features, you likely create tenants in Knock when an account or organization is created in your application. If you don't already use tenants in Knock, TeamsKit can create tenants for you on the fly if they don't already exist.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      Our best-practice recommendation is that tenants in Knock should map one-to-one
      to whatever abstraction you use to model accounts, organizations, or workspaces.
      You can think of tenants as the top-level container within your data model
      that you use to power multi-tenancy in your application.
    </>
  }
/>

### About objects

[Objects](/concepts/objects) in Knock are flexible abstractions meant to map to a resource in your system. Each individual object in Knock exists within a `collection` and requires an `id` unique to that collection.

In the context of TeamsKit, objects serve two purposes. First, they store the Microsoft Teams channel or channels you want to notify. Second, they act as the recipient of the workflow used to send a message to Microsoft Teams.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note: </strong>
      You can think of collections as the different tables within your database that
      represent resources in your application. Objects are the rows within those
      tables.
    </>
  }
/>

#### Example

Let's say we're building a source control application like GitHub, where teams can collaborate and share code repositories. In this context, each GitHub organization would map to a tenant in Knock, and each repository would become an object inside of a `repositories` collection.

If we want to be notified in Microsoft Teams each time an issue is opened against a repository, we would store a Microsoft Teams channel on each repository object and then trigger a `new-issue` workflow. Knock will use the data stored on the object and tenant to route a message to the correct Microsoft Teams channel:

```javascript
await knockClient.workflows.trigger("new-issue", {
  recipients: [
    {
      collection: "repositories",
      id: "knocklabs/javascript",
    },
  ],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```

### Merging channel data

In this implementation, we'll actually store [the required channel data](/integrations/chat/microsoft-teams/overview#how-to-set-channel-data-for-a-microsoft-teams-integration-in-knock) for an `MsTeamsConnection` across two different entities in Knock: a `Tenant` and an `Object`. This is because we want to store the `ms_teams_tenant_id` for the Microsoft Entra tenant on the Knock `Tenant` and the `ms_teams_channel_id` for the Microsoft Teams channel on the Knock `Object`.

When you trigger a workflow using this recipient and tenant, Knock will merge the channel data from the `Tenant` and the `Object` to send the message to the correct Microsoft Teams channel. By storing the `ms_teams_tenant_id` on the Knock `Tenant`, your customers only need to complete the OAuth flow once to connect their Microsoft Teams instances to Knock.

## Adding required scopes to your app's manifest

In order for your bot to send messages to channels in Microsoft Teams, you'll need to update your <a href="https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema" target="_blank">Microsoft Teams app's manifest</a> so that it includes the `team` scope for your bot.

In your `manifest.json` file, add `team` to your bot's array of scopes:

```json
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "version": "1.0.0",
  "id": "{{YOUR_TEAMS_APP_ID}}",
  "bots": [
    {
      "botId": "{{YOUR_BOT_ID}}",
      "scopes": ["team"]
    }
  ]
}
```

## Implementing TeamsKit

To facilitate the OAuth flow and channel selection process, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit). TeamsKit is a set of React components that make it easier to build Microsoft Teams integrations in Knock. You can use TeamsKit to build a self-serve Microsoft Teams integration that allows your users to connect their Microsoft Teams instances to Knock and send messages to public channels.

### Signing a user token

The only access you'll need to manage when using TeamsKit are grants for your users to interact with their [Tenants](/concepts/tenants) and [Objects](/concepts/objects) in Knock. 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](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API.

We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages.

You'll need to generate a token for your user that includes access to the Knock tenant storing the Microsoft Entra tenant ID as well as any recipient objects storing Microsoft Teams channel data described in this reference on [TeamsKit resource access grants](/in-app-ui/react/teams-kit#resource-access-grants).

Using the below example, you can quickly generate a token with the [Node SDK](https://github.com/knocklabs/knock-node#signing-jwts).

```javascript
import { Knock } from "@knocklabs/node";
import { Grants } from "@knocklabs/node/dist/src/common/userTokens";

const token = await Knock.signUserToken("user-1", {
  grants: [
    Knock.buildUserTokenGrant({ type: "tenant", id: "org_3sh72ds78" }, [
      Grants.MsTeamsChannelsRead,
    ]),
    Knock.buildUserTokenGrant(
      { type: "object", id: "repo-1", collection: "repositories" },
      [Grants.ChannelDataRead, Grants.ChannelDataWrite],
    ),
  ],
});
```

You'll need to pass this token along with the public API key to the `KnockProvider` that wraps `KnockMsTeamsProvider` and the rest of your components. We recommend storing the generated user token in local storage so that your client application has easy access to it.

### Adding provider components

In order to give your components the data they need, they must be wrapped in the `KnockMsTeamsProvider`. We recommend putting this high in your component tree so that any TeamsKit components that you use will be rendered within it. The Microsoft Teams provider goes inside of the `KnockProvider`. Your hierarchy will look like this:

```javascript title="Wrap your UI components in data providers"
<KnockProvider
    apiKey="Public API key"
    userId="User ID"
    userToken="Generated user token with resource grants"
>
    <KnockMsTeamsProvider
        knockMsTeamsChannelId="Knock Microsoft Teams channel ID"
        tenantId="Knock tenant ID"
    >
        {child components}
    </KnockMsTeamsProvider>
</KnockProvider>
```

The `KnockMsTeamsProvider` gives your components access to the status of the connection to your Microsoft Teams bot, so that they can all be in sync when a user is connecting, disconnecting, or experiencing a connection error.

### Implementing the OAuth flow with `MsTeamsAuthButton`

<figure>
  <Image
    src="/images/integrations/chat/microsoft-teams/msteamsauthbutton.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The MsTeamsAuthButton component with MsTeamsAuthContainer"
    width={1310}
    height={564}
  />
  <figcaption>
    The MsTeamsAuthButton component with MsTeamsAuthContainer
  </figcaption>
</figure>

Your users will give your Microsoft Teams bot access to their own Microsoft Entra tenants via the `MsTeamsAuthButton`. This button can be used on its own, or nested in the `MsTeamsAuthContainer` for a bigger visual footprint. Here's an example of how to use them:

```javascript title="Initiate OAuth and display auth state with MsTeamsAuthButton"
// Without container
<MsTeamsAuthButton
    msTeamsBotId="Microsoft Teams bot ID"
    redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
/>

// With container
<MsTeamsAuthContainer
    actionButton={
        <MsTeamsAuthButton
            msTeamsBotId="Microsoft Teams bot ID"
            redirectUrl="The URL of your application to return to once Microsoft Teams authorization is complete"
        />
    }
/>
```

The `MsTeamsAuthButton` maps a tenant in your product to a customer's Microsoft Entra tenant. This means in most cases you'll just need a single instance of the `MsTeamsAuthButton`.

Remember to consider which roles in your application can access the `MsTeamsAuthButton` component. Knock does not control access to the component. In most cases, you'll add this connect button/container in the settings area of your product.

<Callout
  emoji="⚠️"
  text={
    <>
      <strong>Note:</strong> The <code>MsTeamsAuthButton</code> component does
      not automatically install your Microsoft Teams bot into a team. Your users
      will need to{" "}
      <a
        href="https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77"
        target="_blank"
      >
        manually add your bot to their teams
      </a>{" "}
      before you can send messages to channels within those teams.
      Alternatively, provide instructions to your app's admins to{" "}
      <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps#install-apps-in-an-existing-team"
        target="_blank"
      >
        install your bot into existing teams
      </a>{" "}
      and{" "}
      <a
        href="https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps#preinstall-apps-in-a-new-team-using-team-creation-template"
        target="_blank"
      >
        preinstall your bot when new teams are created
      </a>
      .
    </>
  }
/>

### Choosing channels with `MsTeamsChannelCombobox`

This combobox contains the list of teams and channels belonging to the connected Microsoft Entra tenant. Users will use this combobox to search and select a channel (or more than one channel) to be notified when an event in your application occurs, for example a comment on a video. They can also use this combobox to deselect a connected channel.

The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well.

<figure>
  <Image
    src="/images/integrations/chat/microsoft-teams/msteamschannelcombobox.png"
    className="rounded-md mx-auto border border-gray-200"
    alt="The MsTeamsChannelCombobox component showing connected channels"
    width={1088}
    height={584}
  />
  <figcaption>
    The MsTeamsChannelCombobox component showing connected channels
  </figcaption>
</figure>

Add your combobox to your application where you'd like the user to select channels to notify:

```javascript title="The MsTeamsChannelCombobox connects an object to one or more channels"
<MsTeamsChannelCombobox
  msTeamsChannelsRecipientObject={{
    objectId: "object id",
    collection: "object collection",
  }}
/>
```

<br />
<Callout
  emoji="💡"
  text={
    <>
      <strong>Limitations</strong>
      <ul>
        <li>
          The combobox will only show public channels. Microsoft Teams bots do
          not support sending messages to private channels.
        </li>
        <li>
          The combobox does not show individual users for Microsoft Teams direct
          messages.
        </li>
      </ul>
    </>
  }
/>

## Triggering a workflow

Once you have saved the Microsoft Teams channel ID as channel data on an object, you can trigger a workflow to send a message to that channel. Here's an example of how to trigger a workflow using the Knock Node SDK:

```javascript
const workflow_run_id = await knockClient.workflows.trigger("new-issue", {
  recipients: [
    {
      collection: "repositories",
      id: "knocklabs/javascript",
    },
  ],
  tenant: "knocklabs",
  data: {
    message: formData.get("newIssue"),
  },
});
```


## Discord
Setup guide with examples to show you how to send Discord notifications with Knock.
---
title: How to send Discord notifications with Knock
description: Setup guide with examples to show you how to send Discord notifications with Knock.
tags: ["discord", "chat"]
section: Integrations
layout: integrations
---

In this guide you’ll learn how to use Knock to send notifications to Discord.

We’ll cover:

- Methods for sending notifications to Discord
- Incoming webhooks configuration
- Bot configuration
- Triggering the notification to your Discord channel

## Methods for sending notifications to Discord

We support two main methods for sending notifications to Discord:

1. Discord incoming webhooks
2. Discord bots

Incoming webhooks are simpler in terms of configuration and will probably serve best for most cases but
if that's not enough, using bots should provide enough flexibility for all use cases.

The main difference with both approaches is that for incoming webhooks, you need to create one per Discord channel. If you are planning to notify just a few Discord channels, this is probably the easiest, but if you need to notify multiple Discord channels the bot approach will work best. Additionally, [Message Components](https://discord.com/developers/docs/interactions/message-components) cannot be used with the incoming webhook approach, so if you're planning on leveraging those you should create a bot.

Next we'll walk through how to configure each of these methods to send Discord notifications using Knock.

## Method 1: Incoming webhooks

### Configuring Discord

To create an incoming webhook for a Discord channel, hover over the channel name and you'll see a gear icon appear. Click the gear and you'll be taken to the channel's edit screen. Click on "Integrations."

Next, click on "Create Webhook," provide a name, image and a channel and copy the webhook url by clicking on "Copy Webhook URL." The channel you have just selected will be the one notified when a Knock workflow gets triggered. We'll use the URL you copied to set that data in Knock.

Here's an animation of where to find these details in Discord:

![Channel integrations screen](/images/integrations/chat/discord/create-discord-webhook.gif)

### Configuring Knock

Set a new Object in Knock that will contain the Discord channel data ([Object documentation here](/reference#set-object)). For this example, let's call our object "My project" and give it an id of `project-1`. Its collection will be `projects`. Then we set that in Knock:

<MultiLangCodeBlock snippet="objects.set" title="Set project object in Knock" />

If we check the Objects tab in our Knock dashboard, we can see the project exists there. Now we can give it specific channel information so it knows where to post in Discord.

Take the URL you copied from the Discord webhook and set channel data on the Object we just set:

<MultiLangCodeBlock
  snippet="objects.setChannelData.discord.webhook"
  title="Store Discord connection on object"
/>

<br />

<Callout
  emoji="🚨"
  text={
    <>
      <span className="font-bold">Potential confusion alert.</span> In the
      example above, the <code>KNOCK_DISCORD_CHANNEL_ID</code> variable is the
      id of the Knock channel you've created to represent your Discord
      integration within the Knock dashboard. You can find it by going to{" "}
      <span className="font-bold">Integrations</span> {">"}{" "}
      <span className="font-bold">Channels</span> in the Knock dashboard and
      then copying the ID of your Discord channel.
    </>
  }
/>

You can navigate back to your Objects dashboard and verify that `project-1` has the appropriate data set.

Now you're ready to send notifications to Discord via incoming webhook! Jump to the [Triggering the workflow](/integrations/chat/discord#triggering-the-workflow) section to do so.

## Method 2: Bots

### Configuring Discord

#### 1. Create an app and bot

You'll need to set up a bot and app to handle incoming messages from Knock. You can learn more in the documentation for [creating Discord apps](https://discord.com/developers/applications) and [creating Discord bots](https://discord.com/developers/docs/topics/oauth2#bots) (note: you'll need to be logged in to access the applications docs).

#### 2. Set OAuth permissions for the bot

Once you have a bot created for your app in Discord, you can set permissions and authorize it to join your Discord server.

Within the Application you've created on Discord, find the URL Generator under `OAuth2`. You can access the URL generator using the URL below:
`https://discord.com/developers/applications/<your application id>/oauth2/url-generator`.

<Callout
  emoji="🌠"
  text={
    <>
      <div className="font-bold"> Discord terminology clarification</div>
      <div>
        There are two types of permissions you'll be working with when using the
        Discord API: Scopes and Bot permissions.
      </div>
      <ul>
        <li>
          A{" "}
          <a href="https://discord.com/developers/docs/game-sdk/applications#data-models">
            scope
          </a>{" "}
          is a permission granted to a Discord app when it joins a Discord
          server.
        </li>
        <li>
          <a href="https://discord.com/developers/docs/topics/oauth2#bot-authorization-flow">
            Bot permissions
          </a>{" "}
          dictate what the bot can do in the server.
        </li>
      </ul>
    </>
  }
/>

The URL Generator will build our bot invitation link for us. Under `Scopes` check "bot" and under `Bot permissions` check "Send Messages." If you have more advanced use cases, here's where you can set various permissions for your bot, but this is the minimum we need to give it the ability to pass along messages from Knock.

<Image
  src="/images/integrations/chat/discord/discord-oauth1.png"
  width={3015}
  height={1679}
  className="rounded-md mx-auto border border-gray-200"
  alt="Accessing OAuth in Discord"
/>

<Image
  src="/images/integrations/chat/discord/discord-oauth2.png"
  width={3016}
  height={1680}
  className="rounded-md mx-auto border border-gray-200"
  alt="Accessing OAuth in Discord 2"
/>

Scroll down and copy the generated URL, and **paste it into your browser**. You will see a prompt to allow it access to the Discord servers you are an administrator of. Select your desired server and proceed to authorize it.

<Image
  src="/images/integrations/chat/discord/copy-url.png"
  width={3016}
  height={1631}
  className="rounded-md mx-auto border border-gray-200"
  alt="Accessing OAuth in Discord 2"
/>

Now you should see your new bot enter your Discord server! We can move on to configuring your channel in Knock.

### Configuring Knock

#### 1. Add your Discord channel to Knock

For this, you'll need your bot's token. In your Discord account in the browser, navigate back to your bot's settings: `https://discord.com/developers/applications/<your application id>/bot`

If you don't see a token, click "Reset token" and copy the result.

<Image
  src="/images/integrations/chat/discord/reset-token.png"
  width={3015}
  height={1640}
  className="rounded-md mx-auto border border-gray-200"
  alt="Getting a token from the Discord bot"
/>

Now you can go to your Knock channels and create a new `Chat` channel, selecting Discord as the type.

Once it's created, click "Edit configuration" and paste in the Discord bot token you just created/copied above.

#### 2. Set a Discord channel's data on a Knock Object

Set a new Object in Knock that will contain the Discord channel data ([Object documentation here](/reference#objects)). For this example, let's call our object "My project" and give it an id of `project-1`. Its collection will be `projects`. Then we set that in Knock:

<MultiLangCodeBlock snippet="objects.set" title="Set project object in Knock" />

For Knock to know what Discord channel should post when "My project" is a recipient of a workflow trigger action, we need to set that information on "My project"'s channel data.

To do this we need the channel ID from Discord. Open Discord, navigate to `Preferences` in the main menu, and go to the `Advanced` tab under `App Settings`. From here you'll see a toggle for Developer Mode. Make sure that's turned on, then navigate back to your Discord server. Now if you right-click on a channel, you'll see "Copy ID" as an option in the list. Copy the ID for the channel you want to post to. For clarity, we'll call this the `Discord channel ID`.

![Get discord channel ID](/images/integrations/chat/discord/discord-channel-id.gif)

<Callout
  emoji="🌠"
  text={
    <>
      <div className="font-bold">Selecting Discord channels for publishing</div>
      <div>
        When you're ready to go to production with your integration you'll need
        a way for your customers to select which Discord channel they want your
        integration to publish to. You can learn more about{" "}
        <a
          href="https://discord.com/developers/docs/resources/guild#get-guild-channels"
          target="_blank"
        >
          fetching Discord channels for display in your app here.
        </a>
      </div>
    </>
  }
/>

We'll also need the ID for the Knock chat channel we set up in step 3. We'll refer to this as the `Knock chat channel ID`, which you can get in the channels tab of your Knock dashboard. Now we can set channel data for our project:

<MultiLangCodeBlock
  snippet="objects.setChannelData.discord.bot"
  title="Set channel data"
/>

You can navigate back to your Objects dashboard and verify that Project 1 has the appropriate data set.

We've finished the Knock and Discord configurations and it's time to test triggering a workflow!

## Triggering the workflow

We'll navigate back to our example app which will notify Discord users when a new comment is made.
We just need to make sure we include our project as one of the recipients for this notification by including its ID and collection, like in the example below:

<MultiLangCodeBlock
  snippet="workflows.trigger-with-object-as-recipient"
  title="Trigger your workflow"
/>

Depending on how you have configured your integration you should be seeing either your Discord bot or an incoming webhook ping the appropriate Discord channel.

## Channel data requirements

In order to send a message to a recipient, you'll need to have the following [channel data](/managing-recipients/setting-channel-data) set for the recipient.

<Attributes>
  <Attribute
    name="connections"
    type="DiscordConnection[]*"
    description="One or more connections to Discord"
  />
</Attributes>

### `DiscordConnection` with incoming webhook URL

<Attributes>
  <Attribute
    name="incoming_webhook.url"
    type="string*"
    description="The incoming webhook URL"
  />
</Attributes>

### `DiscordConnection` with a bot token

<Attributes>
  <Attribute
    name="channel_id"
    type="string*"
    description="A Discord channel ID"
  />
</Attributes>


## WhatsApp
Setup guide for sending notifications with WhatsApp and Knock.
---
title: How to send WhatsApp notifications with Knock
description: Setup guide for sending notifications with WhatsApp and Knock.
section: Integrations > Chat
layout: integrations
---

Knock integrates with [WhatsApp](https://www.whatsapp.com/) to send notifications to your recipients.

## Features

- Per environment configuration
- Sandbox mode

## Getting started

Before you set up your WhatsApp chat channel in Knock, you'll need to take the following steps in WhatsApp.

### 1. Create a business app on Facebook

Login to your [Facebook developer account](https://developers.facebook.com/) and click on the ["Create app"](https://developers.facebook.com/apps/create/) button,
then choose the first "Business" type app and complete the details with your personal information.

<Image
  src="/images/integrations/chat/whatsapp/create_business_app.jpg"
  width={2060}
  height={1418}
  className="rounded-md mx-auto border border-gray-200"
  alt="Create business app"
/>

### 2. Add WhatsApp as a product

Now that your app is created you need to add a product, scroll down to find the "WhatsApp" product and click "Set up."
After this you will be redirected to the WhatsApp get started page, here you can "create a business account" or use an existing one.

<Image
  src="/images/integrations/chat/whatsapp/app_dashboard.jpg"
  width={2724}
  height={1064}
  className="rounded-md mx-auto border border-gray-200"
  alt="Dashboard app"
/>

### 3. Send a test message

In case you want to [send a test message](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/#sent-test-message), you can go to _WhatsApp/first steps_, where you will find the **temporary access token**, **phone number id** and a **curl of send messages**.

<Image
  src="/images/integrations/chat/whatsapp/first_steps.jpg"
  width={1768}
  height={1348}
  className="rounded-md mx-auto border border-gray-200"
  alt="Send test message"
/>

**Note: The `phone_number_id` is from a Facebook test phone number which cannot be used in production.**

Then you need to add your personal number in the **recipient phone number field** and click "Send message"

<Callout
  emoji="🔦"
  text={
    <>
      Keep in mind that to configure Knock, you are looking for your{" "}
      <strong>WhatsApp Access Token</strong> and your{" "}
      <strong>Phone Number Id</strong> (not your phone number). <br></br>
    </>
  }
/>

### 4. Add a valid business phone number

[Add a business phone number](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/add-a-phone-number)
to send messages from. You can do this using the _Add Phone Number_ button which is below
the current page.

<Image
  src="/images/integrations/chat/whatsapp/add_business_phone_number.jpg"
  width={1710}
  height={1308}
  className="rounded-md mx-auto border border-gray-200"
  alt="Add business phone number"
/>

### 5. Generate an access token

Because the testing access token only last 24 hours, we need to create a token that can last forever:

1. Create an admin user. To do this you need to go to the [business settings page](https://business.facebook.com/settings).
   You will see the [system users](https://business.facebook.com/settings) under the section of Users on the left sidebar.
   After you have created your new user click on _Add Assets_ and choose _App>Select App Name>Full control option_ and save changes.

<Image
  src="/images/integrations/chat/whatsapp/whatsapp-creation-user-1.jpg"
  width={2026}
  height={1526}
  className="rounded-md mx-auto border border-gray-200"
  alt="Create user with full control"
/>

2. Click on _WhatsApp Accounts_ on the left sidebar and then select the WhatsApp business app and click the _Add people_ button.
   Then choose the recently created system user and check the **full control option** and click the "Assign" button.

<Image
  src="/images/integrations/chat/whatsapp/whatsapp-creation-user-2.jpg"
  width={1680}
  height={1268}
  className="rounded-md mx-auto border border-gray-200"
  alt="Add user to WhatsApp account"
/>

3. Go back to the system users page and select the recently created system user from the list. Then click the **Generate new token** button.
   Choose your app from the dropdown and make sure the `whatsapp_business_management` and `whatsapp_business_messaging` options are checked.

<Image
  src="/images/integrations/chat/whatsapp/whatsapp-creation-user-3.jpg"
  width={1680}
  height={1268}
  className="rounded-md mx-auto border border-gray-200"
  alt="Generate token"
/>

<Image
  src="/images/integrations/chat/whatsapp/whatsapp-creation-user-4.jpg"
  width={1676}
  height={1526}
  className="rounded-md mx-auto border border-gray-200"
  alt="Generate token"
/>

### 6. Add a message template

The only way of starting a business conversation with a client is using [message templates](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/).
In order to use this you must go to your [message templates dashboard](https://business.facebook.com/wa/manage/message-templates/) and click "Create template"

Then you must choose a **category**, **name** and **language** for your template and click "Continue."

<Image
  src="/images/integrations/chat/whatsapp/new_template_configuration.jpg"
  width={1648}
  height={1250}
  className="rounded-md mx-auto border border-gray-200"
  alt="New template configuration"
/>

After creating your template you will gain access to your editor, where you must add a **Body** for your message (you can also add a _Header_, _Footer_ or a _Button_ if you want)

<Callout
  emoji="🔦"
  text={
    <>
      Here you can use parameters like <strong>{"{{1}}"}</strong>, which are
      dynamically incorporated into the message. These are going to be
      overridden with the parameters you send in your template object with Knock
    </>
  }
/>

<Image
  src="/images/integrations/chat/whatsapp/whatsapp_template_editor.jpg"
  width={2364}
  height={1294}
  className="rounded-md mx-auto border border-gray-200"
  alt="Whatsapp Template editor"
/>

Once you have finished you must click on "Submit," then you have to wait for WhatsApp to [approve your template](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/) in order to start using it.

## Configuring WhatsApp in Knock

Now that you have a business **phone number id**, an **access token** and a **template message** you're ready to configure your WhatsApp channel within Knock.

### 1. Create a WhatsApp channel

You can create a new WhatsApp channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have
using your **access token** and **phone number id**.

### 2. Send a template object

In order to use a WhatsApp template message, you must send a template object.
For this you must specify this object in your message body using your template editor and JSON (with Liquid if you want), following the next format:

```
{
  "template": {
    "name": "{{template_name}}",
    "language": {
      "code": "{{template_language}}"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{{parameter}}"
          }
        ]
      }
    ]
  }
}
```

<br />

<Callout
  emoji="🔦"
  text={
    <>
      Keep in mind that your <strong>{"{{template_name}}"}</strong> and{" "}
      <strong>{"{{template_language}}"}</strong> must be your WhatsApp message
      template name and language respectively.
      <br />
      Notice how the <strong> {"{{parameter}}"}</strong> is going to override
      the parameter from your WhatsApp template, and the amount of parameters
      you send here must the same you have in your WhatsApp template too.
    </>
  }
/>

## Additional information

Here are a few other things to keep in mind once you have your WhatsApp channel configured in Knock:

- **Deliverability tracking.** We cannot currently track deliverability through WhatsApp channels. This means that all notifications sent through WhatsApp will show up as "Sent" in the Knock messages log, but not "Delivered."

## Provider configuration

<Attributes>
  <Attribute
    name="Authentication token"
    type="string*"
    description="The authentication token from your WhatsApp app"
  />
  <Attribute
    name="Phone Number ID"
    type="string*"
    description="The phone number ID associated with your business phone number"
  />
</Attributes>

## Recipient data requirements

In order to send a notification you'll need a valid `phone_number` property set on your recipient in E.164 format.



# In-app

## Overview
Learn how to build in-app notifications like feeds and inboxes with Knock.
---
title: In-app notifications with Knock
description: "Learn how to build in-app notifications like feeds and inboxes with Knock."
tags: ["inbox", "feeds", "toasts", "in app", "in-app"]
section: Integrations > In-app
layout: integrations
---

In addition to delivering to out-of-app channels such as email, push, SMS, and chat apps like Slack, you can also use Knock to build great in-app notifications experiences too.

You can use our in-app feed channel to build stateful, in-app notifications experiences like floating feeds, inboxes, toasts and banners, and you can use our preferences API to build powerful user-facing preference controls. You can also use [Knock link tracking](/send-notifications/tracking) to capture link-click events right within your Knock account.

For a complete guide on powering in-app notifications with Knock, see our [building in-app UI docs](/in-app-ui/overview).

[See a live demo ->](https://in-app-demo.knock.app/)

## Supported providers

- [Knock in-app](/integrations/in-app/knock)

If you want us to add a new provider to this list, please let us know through the feedback button at the top of this page.


## Knock
Learn how to build in-app notifications using Knock's notification system.
---
title: Knock in-app notifications
description: "Learn how to build in-app notifications using Knock's notification system."
tags: ["inbox", "feeds", "toasts"]
section: Integrations > In-app
layout: integrations
---

The Knock in-app notification channel provides an easy way to bring in-app notifications into your application. You can use our [pre-built components](/in-app-ui/react/overview) to get up and running quickly with feeds, toasts, or inboxes embedded into your application, or you can build custom UI on top of our [in-app API](/reference#feeds).

**Related resources**:

- [Building in-app experiences with Knock](/in-app-ui/overview)
- [Integrating the Knock feed into your application](/in-app-ui/react/feed)

## Understanding message statuses

Every in-app feed notification sent by Knock has a status of `unseen`, `seen`, or `read`. You can use these statuses to power notification badge counts, filtering, and mark-as-read functionality.

Here's more context on each status:

- **Unseen.** The notification has not been rendered in the user's in-app feed, meaning the user hasn't seen the notification yet.
- **Seen.** The notification has been rendered in the user's in-app feed, meaning the user opened the feed and saw the notification. If a notification has a status of `seen` it means that it has not yet been marked as read by the user.
- **Read.** The notification has been marked as read by the user. There are a few ways notifications can be marked as read by users depending on the behavior you'd like to provide. We cover how this works in our own feed in the section below.

### How the Knock in-app feed uses status

Message status is used to power a number of different features in the in-app feed.

- **Badge counting.** By default, the Knock in-app feed badge counter will show users a count of how many `unseen` messages they have waiting for them in the feed. This means that as soon as they open the feed and see them the messages will be marked as `seen` and the badge count will go back to zero. Some apps prefer to show a count of `unread` messages on their badge counter; we default to `unseen` as it results in less noise and disruption for the user.
- **Mark as read.** The Knock in-app feed lets users mark notifications as read in one of two ways. They can mark an individual item as read by clicking on it (which takes them to the URL assigned to that notification) or they can click "mark all as read" to mark all notifications in the feed as `read`.
- **Filtering.** You can use the filter button at the top of the feed to filter messages based on their status. This helps users quickly access notifications they've read or haven't read so that they can quickly get to the high priority items in their feed.

Note that the functionality above is just the default for what we've provided in our in-app feed. If you'd like to use our message statuses in a different way, you can fork the Knock in-app feed and customize its behavior as you need to.

## Archiving messages

Sometimes a user wants to remove a notification from their feed altogether. This is where notification archiving comes in. When a notification is archived, it is removed from the feed and is no longer visible to the end user.

In the Knock in-app feed, a message can be archived by clicking the "x" in the top-right corner of a given notification. The in-app feed component doesn't give users a way to see their archived notifications out-of-the-box, but if you'd like to incorporate this into your own in-app feed you can use the `archived: only` parameter on the [GET feed request](/reference#get-feed).

## Customizing API response content

By default, the [in-app feed API](/reference#get-feed) will return:

- One or more actors associated with each in-app notification (when set), including all custom properties under each actor
- All of the public variables (note: secret variables are never returned)
- The entire workflow trigger data associated with each in-app notification
- The recipient associated with each notification, including all custom properties set

In some situations, you may need control over exactly what the in-app feed API returns. This is where our API response filter can be used to completely customize the keys returned for the entities in your in-app feed responses.

| Property  | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| vars      | Apply a filter to the environment variables returned                           |
| actor     | Apply a filter to all actors returned from the feed endpoint                   |
| recipient | Apply a filter to the recipient returned from the feed endpoint                |
| data      | Apply a filter to workflow trigger data returned from the in-app feed endpoint |

Each property accepts the following:

- A boolean to indicate whether this entity should be omitted or included, entirely (defaults to `true`).
- An object with either `except` or `only` key paths for keys to exclude or include. Note: a nested keypath can be given using a `.`.

To add the JSON filter for your in-app feed, navigate to **Integrations** > **Channels** and select your in-app channel. Then, under each set of environment settings, enter the JSON filter before clicking "Update settings."

### Example: customizing the actor data

As an example, if you want to customize the properties returned under an actor to only include `id`, `name`, and `avatar` you can set a response filter such as:

```json
{
  "actor": {
    "only": ["id", "name", "avatar"]
  }
}
```

If you want to omit certain keys from the actor you can use the `except` keyword:

```json
{
  "actor": {
    "except": ["email", "phone_number", "credit_card.last4"]
  }
}
```

Or, if you want to exclude the actor from rendering you can set:

```json
{
  "actor": false
}
```



# Push

## Overview
Learn how to send mobile push notifications with Knock.
---
title: Push notifications with Knock
description: Learn how to send mobile push notifications with Knock.
tags: ["push", "android", "ios", "react native"]
section: Integrations > Push
layout: integrations
---

Knock supports sending push notifications directly to native services such as Apple Push Notifications service (APNs) (for iOS notifications) and Firebase Cloud Messaging (for Android push notifications). We also support delivery of notifications through push intermediary services such as Expo.

## Features

- **No stateful connections to manage**: we take care of all of the complexity of managing and maintaining stateful connections to your push providers, just simply send us notifications and we'll get them delivered!
- **Cross-provider, single template**: you can send the same templated message across multiple providers to reduce the amount of templates to maintain.
- **Token deregistration**: if a recipient's token(s) is invalid resulting in a `bounced` message when attempting to send, remove the token.

## Channel groups

When you create your first push channel in Knock, you'll notice that we offer a channel group that combines both Apple Push Notifications service (APNs) and Firebase Cloud Messaging. If you are sending notifications directly to each of these services today, consider using a channel group in Knock.

A **channel group** can send to multiple providers at once from a single channel step within a workflow. Here's why that's powerful.

Without a channel group in place, any workflows that send push notifications will need two channel steps in place, one for Apple and one for Firebase. This can be valuable when you want to take advantage of provider-specific functionality, but in cases where you want to send identical notifications to both providers, it means duplicating (and maintaining) the notification design across both channel steps.

With a channel group in place, you can send identical notifications to Apple and Firebase, from the same channel step. This means you can design the notification once, and move on.

<Image
  src="/images/integrations/push/channel-group-example.png"
  width={2252}
  height={928}
  className="rounded-md mx-auto border border-gray-200"
  alt="Workflow with push channel group. One step with a single notification design to update and manage."
/>

Channel groups are currently enabled on an on-demand basis. If you'd like it enabled for your account, you can request access in the dashboard or send us a note using the feedback button at the top of this page.

## Push overrides

For push-specific sending needs, a set of overrides can be set per template from the "Template settings" button on the push message template page. The overrides provided are merged into the push payload sent to the underlying provider and can be used to set badge counts, custom sound files, and any other provider-specific settings.

By default, all overrides are applied with a `merge` strategy, which can be customized by adding a `__strategy__` key to the top level of the JSON payload and setting as `replace`. When the strategy is set to replace, all existing properties will be overridden with what's included in the overrides JSON.

## Supported providers

- [Apple Push Notifications service (APNs)](/integrations/push/apns)
- [Expo (React Native)](/integrations/push/expo)
- [Firebase Cloud Messaging (Android)](/integrations/push/firebase)
- [OneSignal](/integrations/push/one-signal)

If you want us to add a new provider to this list, please let us know through the feedback button at the top of this page.


## Token deregistration
How to use Knock token deregistration to manage recipient tokens by removing invalid tokens.
---
title: Token deregistration
description: How to use Knock token deregistration to manage recipient tokens by removing invalid tokens.
tags: ["token deregistration", "channel data", "bounced"]
section: Integrations > Push
layout: integrations
---

For push providers only, Knock provides an opt-in, provider-agnostic token management capability known as token deregistration. Knock removes invalid tokens from a recipient's corresponding channel data if that token results in a `bounced` message on send.

This feature is available for all push providers, except OneSignal when the recipient mode is set to `external_id`. In this case, Knock only has access to the user's ID and therefore cannot deregister the associated external token.

Workflow overrides are **not** available for token deregistration. This capability can only be configured at the provider level.

## Availability

<table>
  <thead>
    <tr>
      <th>Provider</th>
      <th>Token deregistration available?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>APNs</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>FCM</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>Expo</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>OneSignal (`player_id`)</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>OneSignal (`external_id`)</td>
      <td>❌</td>
    </tr>
  </tbody>
</table>

## Configuring Knock token deregistration

You can configure Knock tracking on a per-environment basis using your channel's [per-environment configurations](/integrations/overview#per-environment-configurations). Token deregistration will default to `ON` when you first create a channel.

<Image
  src="/images/integrations/push/knock-token-deregistration-channel-config.png"
  alt="An image of a preference set"
  width={1356}
  height={1452}
  className="rounded-md mx-auto border border-gray-200"
/>

## How it works

When Knock attempts to deliver a message through a supported push provider, any errors caused by invalid or expired tokens result in a bounce. This generates a `message.bounced` event containing the invalid token.

Knock will remove the invalid token from the list of tokens present in the recipient's channel data. This allows for an automated audit of the tokens present for recipients.

## Working with Knock token deregistration

### Outbound webhooks

If you use Knock's outbound webhooks, you can view the invalid token in the `message.bounced` events captured. If token deregistration is `ON`, no further intervention is needed for token removal. See the [outbound webhooks guide](/developer-tools/outbound-webhooks/overview) for more details.


## Apple (APNS)
How to send iOS push notifications with Apple Push Notification service (APNs) and Knock.
---
title: How to send push notifications to Apple Push Notifications service
description: How to send iOS push notifications with Apple Push Notification service (APNs) and Knock.
tags: ["apns", "ios", "push", "silent push"]
section: Integrations
layout: integrations
---

In this guide we'll walk through how to configure an Apple Push Notifications service (APNs) provider in Knock to send iOS push notifications. This guide assumes that you've already created an APNs channel in the Knock dashboard.

## How to configure Apple Push Notifications service with Knock

There are two ways to configure APNs with Knock. You can use a token-based authentication scheme or a certificate-based authentication scheme. Depending on which you choose, you'll need to get different information from Xcode and your Apple developer account.

### Token-based authentication configuration

**Note**: Knock recommends token-based authentication for all APNs channel connections.

You can read about how to set up a token connection to APNs [in the documentation](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_token-based_connection_to_apns). For your Knock channel configuration, you will need:

1. A provider token signing key (a private key)
2. The key identifier (a 10 digit identifier from your Apple developer account)
3. The team identifier (a 10 digit identifier from your Apple developer account)

### Certificate-based authentication configuration

You can read about how to set up a certificate connection to APNs [in the documentation](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns). For your Knock channel configuration, you will need:

1. A provider certificate (from your Apple developer account)
2. A private key (generated in the process above)

Both of these values should be converted according to the instructions [here](https://hexdocs.pm/pigeon/2.0.0-rc.1/Pigeon.APNS.html#module-generating-your-certificate-and-key-pem) prior to providing them to your Knock channel configuration.

## Using APNs with Knock

In order to use APNs with Knock you'll need to synchronize your users device tokens retrieved from the APNs SDK to Knock by [setting channel data](/managing-recipients/setting-channel-data) for your recipient.

You can follow the [quickstart guide](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns) on APNs to see how to get the device token.

<MultiLangCodeBlock
  snippet="users.setChannelData-push"
  title="Set APNs channel data for a user"
/>

## Managing tokens

By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.

However, Knock does provide an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. When enabled, Knock will automatically remove invalid or expired tokens upon receiving a bounce event from the provider.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our [token deregistration guide](/integrations/push/token-deregistration) for more details on enabling and working with this feature.

## Data passed to APNs

When sending a notification to APNs, we also pass through the following attributes:

| Property           | Type   | Description                                            |
| ------------------ | ------ | ------------------------------------------------------ |
| knock_message_id\* | string | The message ID of the corresponding Knock message      |
| data \*            | string | Any key/value data passed through in your trigger call |

## Silent/background notifications

We support sending [APNs notifications as "silent", data-only notifications](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app) within Knock. You can enable this per push notification template by clicking "Template settings" in the header of the template editor.

When silent push is enabled, we'll no longer pass through the content payload and your message will be sent with the `content-available: 1` flag as expected by APNs. All properties in the data payload described above will be sent with your notification.

## Using overrides to customize notifications

We have full support for overriding the payload sent to APNs for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting `data` properties and referencing attributes on your recipients.

Overrides are merged into the notification payload sent to APNs. See the <a href="https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification" target="_blank">APNs documentation for more details</a>.

| Property | Type       | Description                                                                                                    |
| -------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| headers  | dictionary | APNs specific headers (`apns-priority`, `apns-expiration`, `apns-push-type`, `apns-topic`, `apns-collapse-id`) |
| aps      | dictionary | Overrides to send to the push payload (`sound`, `alert`, `badge`, `thread-id`)                                 |
| any      | any        | Any other key values to send as part of the push message                                                       |

## Channel data requirements

In order to use a configured APNs channel you must store a list of one or more device tokens for the user or the object that you wish to deliver a notification to. You can retrieve a device token by following the guide on the [Apple developer documentation](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns).

| Property | Type     | Description               |
| -------- | -------- | ------------------------- |
| tokens\* | string[] | One or more device tokens |


## Firebase (FCM)
How to send push notifications with Firebase Cloud Messaging (FCM) and Knock.
---
title: How to send push notifications to Firebase Cloud Messaging
description: How to send push notifications with Firebase Cloud Messaging (FCM) and Knock.
tags: ["android", "fcm", "push", "silent push", "web push", "browser push"]
section: Integrations
layout: integrations
---

In this guide we'll walk through how to configure a Firebase Cloud Messaging (FCM) provider in Knock to send mobile or web push notifications. This guide assumes that you've already created an FCM channel in the Knock dashboard.

## How to configure FCM with Knock

To configure FCM with Knock, you'll need your Firebase Project ID and the complete contents of your Service Account JSON file.

You can get both of these by logging into the [Firebase console](https://console.firebase.google.com/) and navigating to project settings. Once you have them, go back to the environment configuration for your FCM channel, enter in your Project ID and Service Account JSON file, and you're good to go.

```json title="Example service account JSON"
{
  "type": "service_account",
  "project_id": "XXX",
  "private_key_id": "XXX",
  "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n",
  "client_email": "XXX@XXX.com",
  "client_id": "XXX",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/XXX"
}
```

## Using FCM with Knock

In order to use FCM with Knock you'll need to synchronize your users device tokens retrieved from the FCM SDK in either Android, iOS, or Web to Knock by [setting channel data](/managing-recipients/setting-channel-data) for your recipient.

You can follow the appropriate quickstart guide for either [iOS](https://firebase.google.com/docs/cloud-messaging/ios/client), [Android](https://firebase.google.com/docs/cloud-messaging/android/client), or [Web](https://firebase.google.com/docs/cloud-messaging/js/client) on FCM to see how to get the device token.

Once you have the device token, you can use the Knock SDK to set the channel data for your recipient. In the case of web push, you can send the token to your app server and use the corresponding Knock SDK to set the channel data:

<MultiLangCodeBlock
  snippet="users.setChannelData-push"
  title="Set FCM channel data for a user"
/>

## Managing tokens

By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.

However, Knock does provide an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. When enabled, Knock will automatically remove invalid or expired tokens upon receiving a bounce event from the provider.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our [token deregistration guide](/integrations/push/token-deregistration) for more details on enabling and working with this feature.

## Data passed to FCM

When sending a notification to FCM, we also pass through the following attributes:

| Property           | Type   | Description                                                                                                                                           |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| knock_message_id\* | string | The message ID of the corresponding Knock message                                                                                                     |
| data\*             | string | Any key/value data passed through in your trigger call, formatted for FCM (all nested objects are flattened, and all values are converted to strings) |

The following example illustrates how Knock will format your trigger data for FCM:

```json
{
  "data": {
    "foo": {
      "bar": [21, 13, 1],
      "baz": false
    },
    "biz": "abc"
  }
}
```

becomes

```json
{
  "data" {
    "foo.bar.0": "21",
    "foo.bar.1": "13",
    "foo.bar.2": "1",
    "foo.baz": "false",
    "biz": "abc"
  }
}
```

## Silent/data notifications

We support sending [FCM notifications as "silent," data-only notifications](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) within Knock. You can enable this per push notification template by clicking "Template settings" in the header of the template editor.

When silent push is enabled, we'll no longer pass through the message payload. All properties in the data payload described above will be sent with your notification still.

## Using overrides to customize notifications

We have full support for overriding the payload sent to FCM for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting `data` properties and referencing attributes on your recipients.

By default, payload overrides will be merged into the base `data` and will not replace other trigger `data` being passed to FCM. The override also needs to match the format that is expected by FCM, meaning that any custom key-value pairs should be contained inside of a `data` dictionary:

```json
{
  "data": {
    "foo": "bar",
    "baz": true
  }
}
```

If you want to fully replace the trigger data with your override rather than merge additional properties, you'll also need to set a replace `__strategy__`:

```json
{
  "__strategy__": "replace",
  "data": {
    "foo": "bar",
    "baz": true
  }
}
```

See the [FCM documentation for details](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages).

| Property     | Type       | Description                  |
| ------------ | ---------- | ---------------------------- |
| apns         | dictionary | APNs specific overrides      |
| data         | dictionary | Extra data properties to add |
| android      | dictionary | Android specific overrides   |
| fcm_options  | dictionary | FCM specific options         |
| notification | dictionary | Notification overrides       |
| webpush      | dictionary | Webpush specific overrides   |

## Common FCM errors

The following are common FCM errors you may see in your message delivery logs:

| Error              | Meaning / action to take                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `UNREGISTERED`     | The device token provided is not valid and should be removed from the recipients channel data. |
| `INVALID_ARGUMENT` | The device token given may be incorrect.                                                       |

## Channel data requirements

In order to use a configured FCM channel you must store a list of one or more device tokens for the user or the object that you wish to deliver a notification to. If you use multiple device tokens for a single user or object, Knock will generate and try and deliver a notification for each unique token.

| Property | Type     | Description               |
| -------- | -------- | ------------------------- |
| tokens\* | string[] | One or more device tokens |


## Expo (React Native)
How to send mobile push notifications with Expo and Knock.
---
title: How to send push notifications using Expo
description: How to send mobile push notifications with Expo and Knock.
tags: ["react native", "ios", "android", "push"]
section: Integrations
layout: integrations
---

In this guide we'll walk through how to configure an Expo provider in Knock to send push notifications. This guide assumes that you've already created an Expo channel in the Knock dashboard and that your React Native application is already setup to support Push notifications.

If you're new to setting up push in your Expo enabled React Native project, you can follow the <a href="https://docs.expo.dev/push-notifications/overview/" target="_blank">excellent setup guide in the Expo documentation</a>.

## How to configure Expo with Knock

To configure Expo with Knock, you'll need your Expo project name (sometimes referred to as an `experience_id`) and if you've enabled enhanced push security, you'll also need an auth token. You can read more about <a href="https://docs.expo.dev/push-notifications/sending-notifications/#additional-security" target="_blank">Enhanced Push Security in the Expo docs</a>.

You can get both of these by logging into the <a href="https://expo.dev/" target="_blank">Expo console</a>. Once you have them, go back to the environment configuration for your Expo channel, complete the configuration, and you're good to go.

## Using Expo with Knock

In order to use Expo with Knock you'll need to synchronize your users device tokens retrieved from the Expo SDK in either Android, iOS, or on the Web to Knock by [setting channel data](/managing-recipients/setting-channel-data) for your recipient.

You can follow the appropriate <a href="https://docs.expo.dev/push-notifications/overview/" target="_blank">quickstart guide for your platform</a> on Expo to see how to get the device token.

<MultiLangCodeBlock
  snippet="users.setChannelData-push"
  title="Set Expo channel data for a user"
/>

## Managing tokens

By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.

However, Knock does provide an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. When enabled, Knock will automatically remove invalid or expired tokens upon receiving a bounce event from the provider.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our [token deregistration guide](/integrations/push/token-deregistration) for more details on enabling and working with this feature.

## Data passed to Expo

When sending a notification to Expo, we also pass through the following attributes:

| Property           | Type   | Description                                            |
| ------------------ | ------ | ------------------------------------------------------ |
| knock_message_id\* | string | The message ID of the corresponding Knock message      |
| data \*            | string | Any key/value data passed through in your trigger call |

## Silent/background notifications

We support sending Expo notifications as "silent," data-only notifications within Knock. You can enable this per push notification template by clicking "Template settings" in the header of the template editor.

When silent push is enabled, we'll no longer pass through the content payload and your message will be sent with the `content-available: true` flag as expected by Expo. All properties in the data payload described above will be sent with your notification.

## Using overrides to customize notifications

We have full support for overriding the payload sent to Expo for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting `data` properties and referencing attributes on your recipients.

Overrides are merged into the notification payload sent to Expo. See the <a href="https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format" target="_blank">Expo documentation for more details</a>.

## Channel data requirements

In order to use a configured Expo channel you must store a list of one or more device tokens for the user or the object that you wish to deliver a notification to. You can retrieve a device token by following the guide on the <a href="https://docs.expo.dev/push-notifications/push-notifications-setup/" target="_blank">Expo developer documentation</a>.

| Property | Type     | Description               |
| -------- | -------- | ------------------------- |
| tokens\* | string[] | One or more device tokens |


## OneSignal
How to send mobile push notifications with OneSignal and Knock.
---
title: How to send push notifications using OneSignal
description: How to send mobile push notifications with OneSignal and Knock.
tags: ["react native", "ios", "android", "push"]
section: Integrations
layout: integrations
---

In this guide we'll walk through how to configure a OneSignal provider in Knock to send push notifications. This guide assumes that you've already created a OneSignal channel in the Knock dashboard.

Your OneSignal channel expects that you are using Knock to author Push notification templates. Those templates are then passed to OneSignal as content.

## How to configure OneSignal Push with Knock

<Callout
  emoji="💡"
  text={
    <>
      <span className="font-bold">Note:</span> this guide assumes that you have
      already setup OneSignal with push certificates and everything needed in
      order to start sending push notifications. You should also have already
      integrated the OneSignal SDK within your application.
    </>
  }
/>

To set up OneSignal Push with Knock you will need:

- Your OneSignal App ID
- Your OneSignal API Key for sending notifications
- To select a mode of operation between using `external_ids` (recommended) or `player_ids` (deprecated by OneSignal).

## Using OneSignal Push with Knock

### Using `external_id` (recommended)

If you’re using an <a href="https://documentation.onesignal.com/docs/users#external-id" target="_blank">External ID</a> to reference your OneSignal users within Knock, you do not need to supply any additional data to initiate a request. We will automatically pass your Knock user ID to OneSignal as the `external_id`.

### Using `player_id`

When using <a href="https://documentation.onesignal.com/v9.0/docs/users#player-id" target="_blank">Player IDs</a> you will need to store the `player_id` for a user within Knock as ChannelData for the OneSignal Push channel. This ensures that Knock has the correct value to pass to send a notification to a recipient when a workflow is triggered.

You can retrieve the `player_id` from OneSignal once a user has been registered, either by using the OneSignal mobile SDK, or by using a webhook from OneSignal.

<MultiLangCodeBlock
  snippet="users.setChannelData-one-signal"
  title="Setting a player_id as channel data for a user"
/>

## Data passed to OneSignal

When sending a push notification to OneSignal, we will automatically pass the following into the attachments data:

| Property           | Type   | Description                                            |
| ------------------ | ------ | ------------------------------------------------------ |
| knock_message_id\* | string | The message ID of the corresponding Knock message      |
| data \*            | string | Any key/value data passed through in your trigger call |

## Silent/background notifications

When selecting to send as a silent/background notification, Knock will passthrough the content_available=true option to OneSignal. You can enable this per push notification template by clicking "Template settings" in the header of the template editor.

## Using overrides to customize notifications

We have full support for overriding the payload sent to OneSignal for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting `data` properties and referencing attributes on your recipients.

Overrides are merged into the notification payload sent to OneSignal. See the <a href="https://documentation.onesignal.com/reference/push-notification" target="_blank">OneSignal documentation for more details</a>. Knock uses the "Aliases" targeting strategy to send push notifications to specific users via External ID.

## Managing tokens

By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.

When using `player_id` mode, Knock provides an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. This feature is not available when using `external_id` mode since Knock doesn't directly manage any tokens in this case.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our [token deregistration guide](/integrations/push/token-deregistration) for more details.

## Channel data requirements

When your OneSignal push channel is configured to use `player_ids` you must supply ChannelData per-recipient that contains one or more `player_ids` for a user.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use both `player_ids` and `external_ids` for my OneSignal integration?">
    No, you can currently only use one or the other.
  </Accordion>
  <Accordion title="Can I use a different identifier as an `external_id`?">
    Currently this is not supported but we'd love to hear a use case you have
    for it!
  </Accordion>
  <Accordion title="Can I use a `template_id` stored in OneSignal?">
    Yes, you can use push overrides to override the JSON payload and specify the
    template_id for OneSignal instead.
  </Accordion>
  <Accordion title="Can I use the OneSignal Push integration to send email or SMS?">
    No, only Push is currently supported.
  </Accordion>
</AccordionGroup>



# SMS

## Overview
Learn how to send transactional SMS notifications with Knock.
---
title: SMS notifications with Knock
description: Learn how to send transactional SMS notifications with Knock.
section: Integrations > SMS
layout: integrations
---

Effortlessly design and deliver SMS notifications to downstream providers. Let Knock manage the delivery for you.

## Features

- **Easy templating**: it's easy to create and maintain SMS notification templates in Knock's editor.
- **Link tracking**: capture link-click events right within your Knock account. For more details, see the [Knock link tracking guide](/send-notifications/tracking).

## Supported providers

- [Africa's Talking](/integrations/sms/africas-talking)
- [AWS SNS](/integrations/sms/aws-sns)
- [Mailersend](/integrations/sms/mailersend)
- [MessageBird](/integrations/sms/messagebird)
- [Plivo](/integrations/sms/plivo)
- [Sinch](/integrations/sms/sinch)
- [Sinch MessageMedia](/integrations/sms/sinch-message-media)
- [Telnyx](/integrations/sms/telnyx)
- [Twilio](/integrations/sms/twilio)
- [Vonage](/integrations/sms/vonage)

If you want us to add a new provider to this list, please let us know through the feedback button at the top of this page.


## Settings and overrides
Learn more about how to configure your SMS messages in Knock.
---
title: SMS settings and overrides
description: Learn more about how to configure your SMS messages in Knock.
section: Integrations
layout: integrations
---

## Overriding the default `to` number

By default Knock will send your SMS messages to the `phone_number` property stored on the `recipient` for the workflow run. If you need to override this, you can do so by setting the `to` field in the SMS template settings.

As an example, if you wanted to send an SMS to a single number, you could set the `to` field to either a static value (like `+1234567890`) or a dynamic value (like `{{ data.phone_number_to_override }}`).

## Provider JSON overrides

Sometimes you may want to customize the API call Knock sends to your SMS provider. A good example of this is passing custom arguments as part of the API payload, or using another feature of the provider that Knock doesn't support out of the box.

To set JSON overrides for your SMS template, you can go to the "Template settings" at the top of the template editor.


## Africa's Talking
Setup guide for SMS notifications with Africa's Talking and Knock.
---
title: How to send SMS messages with Africa's Talking
description: Setup guide for SMS notifications with Africa's Talking and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://africastalking.com/" target="_blank">Africa's Talking</a> to send SMS notifications to your recipients.

## Features

- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Africa's Talking channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Africa's Talking [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Africa's Talking channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Africa's Talking**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from Africa's Talking."
      />
      <Attribute
        name="Username"
        type="string*"
        description="The application username from Africa's Talking."
      />
      <Attribute
        name="Short code"
        type="string"
        description="The short code to send messages from."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## AWS SNS
Setup guide for SMS notifications with AWS SNS and Knock.
---
title: How to send SMS messages with AWS SNS
description: Setup guide for SMS notifications with AWS SNS and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://aws.amazon.com/sns/" target="_blank">AWS Simple Notification Service (SNS)</a> to send SMS notifications to your recipients.

## Features

- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new AWS SNS channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to take some steps in AWS before you can configure your SNS channel within Knock.

<Steps titleSize="h3">
  <Step title="Choose an AWS Authentication Scheme">
    Knock supports two authentication schemes with AWS SNS:
    
    <AccordionGroup>
      <Accordion title="Option 1: Create an AWS IAM User with security credentials">
        To send notifications via AWS SNS using an IAM User, Knock requires the **access key ID** and a **secret access key** of an AWS user with SNS send permissions (you can use the `sns:AmazonSNSFullAccess` permission for this).

        If you don't already have a user with send permissions, you can create an IAM user in AWS to use with the Knock API. You can learn more about creating IAM users in AWS <a href="https://docs.aws.amazon.com/sns/latest/dg/sns-setting-up.html#create-iam-user" target="_blank">here</a>.

        Once you've created your new IAM user, you'll need to provision them with the policy below.

        ```json title="IAM user policy"
        {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": ["sns:AmazonSNSFullAccess"],
              "Resource": "*"
            }
          ]
        }
        ```

        Now that you have an AWS user created and provisioned with SNS send access, grab the **access key ID** and a **secret access key** of the user—we'll use these later when configuring the SNS channel within Knock.
      </Accordion>
      <Accordion title="Option 2: Create an AWS IAM Role with a trust policy for Knock">
        To send notifications via AWS SNS by <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html" target="_blank">delegating an IAM Role</a> in your AWS account to Knock, <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html" target="_blank">secured with an External ID</a>:

        1. Create a new AWS Role:

           - For "Trusted Entity Type" choose "AWS Account."
           - Select "Another AWS account" and put "496685847699" in the Account ID.
           - Check "Require external ID" and enter the ID of the SNS channel you created in your Knock dashboard.

        <Image
          src="/images/integrations/sms/sns-arn-configuration.jpg"
          width={1898}
          height={1650}
          className="rounded-md mx-auto border border-gray-200"
          alt="How Knock works diagram"
        />

        2. Attach the following permission policy to that role.

           ```json title="IAM user policy"
           {
             "Version": "2012-10-17",
             "Statement": [
               {
                 "Effect": "Allow",
                 "Action": ["sns:AmazonSNSFullAccess"],
                 "Resource": "*"
               }
             ]
           }
           ```

        3. Use that role's ARN when configuring your AWS SNS channel in Knock.
      </Accordion>
    </AccordionGroup>

  </Step>
  <Step title="Configuring SNS in Knock">
    Now that you have either an AWS User's credentials or an AWS IAM Role to delegate to Knock, you're ready to [configure your SNS channel](#channel-configuration) in the Knock dashboard under the **Integrations** {">"} **Channels** section.
  </Step>
</Steps>

Here are a few other things to keep in mind once you have your SNS channel configured in Knock:

- **SNS sandbox mode.** By default, AWS places all new accounts in the SNS sandbox. While your account is in the sandbox, you can only send messages to verified destination phone numbers—keep this in mind if you're testing in development before you've moved your account out of the SNS sandbox. For more information on the SNS sandbox and how to move your account out of it, see the <a href="https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html" target="_blank">SNS sandbox documentation</a>.
- **Deliverability tracking.** We cannot currently track deliverability through SNS channels. This means that all notifications sent through SNS will show up as "Sent" in the Knock messages log, but not "Delivered".

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your AWS SNS [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your AWS SNS channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knocklink-click tracking."
      />
    </Attributes>

    **Provider settings for AWS SNS**
    <Attributes>
      <Attribute
        name="AWS region"
        type="enum*"
        description="The region your AWS account is in."
      />
      <Attribute
        name="Authentication scheme"
        type="enum*"
        description="The authentication scheme (Access Key or External ID) to use for your SNS channel."
      />
      <Attribute
        name="Access key ID"
        type="string*"
        description="The access key ID from your AWS account. Required when using Access Key authentication."
      />
      <Attribute
        name="Secret access key"
        type="string*"
        description="The secret access key from your AWS account. Required when using Access Key authentication."
      />
      <Attribute
        name="AWS IAM Role ARN to assume"
        type="string*"
        description="The ARN of the role in your AWS Account that this channel will use. Required when using External ID authentication."
      />
      <Attribute
        name="External ID"
        type="string*"
        description="The external ID for your AWS IAM Role. Required when using External ID authentication."
      />
      <Attribute
        name="Message Type"
        type="enum"
        description="The message type of your SMS (Promotional or Transactional)."
      />
      <Attribute
        name="Sender ID"
        type="string"
        description="The AWS SNS Sender ID to send messages from."
      />
      <Attribute
        name="Originator number"
        type="enum"
        description="The originator number type (Phone number or Short code) to send messages from."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send SMS messages from. Required when Originator number is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The AWS SNS short code to send SMS messages from. Required when Originator number is set to Short code."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## MailerSend
Setup guide for SMS notifications with MailerSend and Knock.
---
title: How to send SMS messages with MailerSend
description: Setup guide for SMS notifications with MailerSend and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://mailersend.com/" target="_blank">MailerSend</a> to send SMS notifications to your recipients.

## Features

- Delivery tracking
- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new MailerSend channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your MailerSend [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your MailerSend channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for MailerSend**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from MailerSend. Must have SMS sending permission."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## MessageBird
Setup guide for SMS notifications with MessageBird and Knock.
---
title: How to send SMS messages with MessageBird
description: Setup guide for SMS notifications with MessageBird and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://developers.messagebird.com/api/sms-messaging/" target="_blank">MessageBird</a> to send SMS notifications to your recipients.

<Callout
  emoji="⚠️"
  text={
    <>
      <span className="font-bold">Note:</span> On February 1, 2024,{" "}
      <a
        href="https://bird.com/en-us/blog/messagebird-is-now-bird"
        target="_blank"
      >
        MessageBird announced a rebrand as Bird
      </a>
      , along with the introduction of a Bird CRM product and new APIs for sending
      messages. <br /> <br /> This integration is with the <a
        href="https://developers.messagebird.com/api/sms-messaging/"
        target="_blank"
      >
        legacy MessageBird SMS API
      </a>, which continues to be supported by Bird but is no longer accepting new
      customers. If integrating with the new Bird API is a blocker to your Knock
      integration, please reach out to <a href="mailto:support@knock.app?subject=Bird%20API%20integration">
        support@knock.app
      </a> to let us know.
    </>
  }
/>

## Features

- Delivery tracking
- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new MessageBird channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your MessageBird [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your MessageBird channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for MessageBird**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from MessageBird. You can find this under Developers > API access."
      />
      <Attribute
        name="From"
        type="enum*"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Sender ID."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The MessageBird short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Sender ID"
        type="string*"
        description="The MessageBird Sender ID to send messages from. Required when From is set to Sender ID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## Plivo
Setup guide for SMS notifications with Plivo and Knock.
---
title: How to send SMS messages with Plivo
description: Setup guide for SMS notifications with Plivo and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://www.plivo.com/" target="_blank">Plivo</a> to send SMS notifications to your recipients.

## Features

- Delivery tracking
- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Plivo channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to take the following steps in Plivo before you can configure your channel within Knock.

<Steps titleSize="h3">
  <Step title="Create a Plivo account">
    <a href="https://console.plivo.com/accounts/register/" target="_blank">Sign up</a> for a Plivo account if you haven't already. 
    
    After doing this you will gain access to your dashboard where you can find your **Auth ID** and **Auth Token**.

  </Step>
  <Step title="Verify a phone number">
    You can add a <a href="https://console.plivo.com/phone-numbers/sandbox-numbers/" target="_blank">sandbox number</a> for testing, or you can buy a <a href="https://console.plivo.com/active-phone-numbers/" target="_blank">Plivo phone number</a> to use as the from field on your Knock channel.
  
  </Step>
  <Step title="Configuring Plivo in Knock">
    Now that you have your **verified phone number**, **Auth ID** and **Auth Token**, you're ready to configure your Plivo channel in the Knock dashboard under the **Integrations** > **Channels** section.
  
  </Step>
</Steps>

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Plivo [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Plivo channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Plivo**
    <Attributes>
      <Attribute
        name="Authentication ID"
        type="string*"
        description="The authentication ID from Plivo."
      />
      <Attribute
        name="Authentication token"
        type="string*"
        description="The authentication token from Plivo."
      />
      <Attribute
        name="From"
        type="enum*"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Sender ID."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The Plivo short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Sender ID"
        type="string*"
        description="The Plivo Sender ID to send messages from. Required when From is set to Sender ID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## Sinch
Setup guide for SMS notifications with Sinch and Knock.
---
title: How to send SMS messages with Sinch
description: Setup guide for SMS notifications with Sinch and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://sinch.com/" target="_blank">Sinch</a> to send SMS notifications to your recipients.

## Features

- Per environment configuration
- Delivery tracking
- Knock link tracking
- Sandbox mode

## Getting started

You can create a new Sinch channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Sinch [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Sinch channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Sinch**
    <Attributes>
      <Attribute
        name="API token"
        type="string*"
        description="The API token from Sinch."
      />
      <Attribute
        name="Service Plan ID"
        type="string*"
        description="The Service Plan ID from Sinch."
      />
      <Attribute
        name="Region"
        type="enum*"
        description="The region of your domain. One of AU, BR, CA, EU, US."
      />
      <Attribute
        name="From"
        type="enum"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Sender ID. Optional if you have an automatic originator number on your Sinch account."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The Sinch short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Sender ID"
        type="string*"
        description="The Sinch Sender ID to send messages from. Required when From is set to Sender ID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## Sinch MessageMedia
Setup guide for SMS notifications with Sinch MessageMedia and Knock.
---
title: How to send SMS messages with Sinch MessageMedia
description: Setup guide for SMS notifications with Sinch MessageMedia and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://messagemedia.com/" target="_blank">Sinch MessageMedia</a> to send SMS notifications to your recipients.

## Features

- Per environment configuration
- Delivery tracking
- Knock link tracking
- Sandbox mode

## Getting started

You can create a new Sinch MessageMedia channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Sinch MessageMedia [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Sinch MessageMedia channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Sinch MessageMedia**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from Sinch MessageMedia."
      />
      <Attribute
        name="API secret"
        type="string*"
        description="The API secret from Sinch MessageMedia."
      />
      <Attribute
        name="Source number"
        type="string*"
        description="The source number to send messages from."
      />
      <Attribute
        name="Source number type"
        type="enum"
        description="The optional type of the source number. One of Alpha (alphanumeric), International, or ShortCode. Will be inferred if not provided."
      />
      <Attribute
        name="Region"
        type="enum*"
        description="The region of your account. One of APAC, EU."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## Telnyx
Setup guide for SMS notifications with Telnyx and Knock.
---
title: How to send SMS messages with Telnyx
description: Setup guide for SMS notifications with Telnyx and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://telnyx.com/" target="_blank">Telnyx</a> to send SMS notifications to your recipients.

## Features

- Delivery tracking
- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Telnyx channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Telnyx [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Telnyx channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Telnyx**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from Telnyx."
      />
      <Attribute
        name="From"
        type="enum*"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Sender ID."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The Telnyx short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Sender ID"
        type="string*"
        description="The Telnyx Sender ID to send messages from. Required when From is set to Sender ID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.


## Twilio
Setup guide for SMS notifications with Twilio and Knock.
---
title: How to send SMS messages with Twilio
description: Setup guide for SMS notifications with Twilio and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://twilio.com/" target="_blank">Twilio</a> to send SMS notifications to your recipients.

## Features

- Delivery tracking
- Bounce Support
- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Twilio channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to take some steps in Twilio before you can configure your Twilio channel within Knock.

<Steps titleSize="h3">
  <Step title="Sign up for Twilio">
    <a href="https://www.twilio.com/try-twilio" target="_blank">Sign up</a> for a Twilio account if you haven't already.
  </Step>
  <Step title="Get a Twilio phone number">
    <a href="https://www.twilio.com/docs/messaging/guides/how-to-use-your-free-trial-account#get-your-free-twilio-phone-number" target="_blank">Get your first SMS-enabled phone number</a> in Twilio. You'll use this as the "From" phone number in your channel configuration within Knock.

    (We also support Twilio <a href="https://www.twilio.com/sms/short-codes" target="_blank">short codes</a> and <a href="https://www.twilio.com/docs/messaging/services" target="_blank">messaging services</a>.)

  </Step>
  <Step title="Verify phone numbers (trial accounts only)">
    If your Twilio account is in trial mode, you'll need to <a href="https://www.twilio.com/docs/messaging/guides/how-to-use-your-free-trial-account#appendix-one-adding-more-verified-personal-phone-numbers-to-your-account" target="_blank">pre-verify any phone numbers</a> that you plan to send SMS messages to during testing with Knock.
  </Step>
  <Step title="Configuring Twilio in Knock">
    Now that you have your **Twilio phone number**, **account ID** and **auth token**, you're ready to configure your Twilio channel in the Knock dashboard under the **Integrations** > **Channels** section.
  </Step>
</Steps>

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Twilio [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Twilio channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Twilio**
    <Attributes>
      <Attribute
        name="Account ID"
        type="string*"
        description="The account ID from Twilio."
      />
      <Attribute
        name="Auth token"
        type="string*"
        description="The auth token from Twilio."
      />
      <Attribute
        name="From"
        type="enum*"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Messaging Service SID."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Messaging Service SID"
        type="string*"
        description="The Messaging Service SID to send messages from. Required when From is set to Messaging Service SID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.

## Delivery tracking

Delivery tracking for Twilio can result in the following status updates to your message:

- The message delivery is confirmed and Knock updates the message to `delivered`
- The message was not delivered due to bad recipient(s) and Knock updates the message to `bounced`
- The message was not delivered due to an error reported by Twilio and Knock updates the message to `undelivered`


## Vonage
Setup guide for SMS notifications with Vonage and Knock.
---
title: How to send SMS messages with Vonage
description: Setup guide for SMS notifications with Vonage and Knock.
section: Integrations > SMS
layout: integrations
---

Knock integrates with <a href="https://vonage.com/" target="_blank">Vonage</a> to send SMS notifications to your recipients.

## Features

- Knock link tracking
- Per environment configuration
- Sandbox mode

## Getting started

You can create a new Vonage channel in the dashboard under the **Integrations** > **Channels** section. From there, you'll need to configure the channel for each environment you have.

## Channel configuration

The following channel settings should be configured per [environment](/concepts/environments). Navigate to **Integrations** > **Channels** in your dashboard, select your Vonage [channel](/concepts/channels), then click "Manage configuration" under the environment that you'd like to configure.

<AccordionGroup>
  <Accordion title="Settings">
    Fields marked with an `*` are required.
    
    **Knock settings**
    <Attributes>
      <Attribute
        name="Sandbox mode"
        type="boolean"
        nameSlug="/integrations/overview#sandbox-mode"
        description="Whether to enable sandbox mode for your Vonage channel."
      />
      <Attribute
        name="Knock link tracking"
        type="boolean"
        nameSlug="/send-notifications/tracking#link-click-tracking"
        description="Whether to enable Knock link-click tracking."
      />
    </Attributes>

    **Provider settings for Vonage**
    <Attributes>
      <Attribute
        name="API key"
        type="string*"
        description="The API key from Vonage."
      />
      <Attribute
        name="API secret"
        type="string*"
        description="The API secret from Vonage."
      />
      <Attribute
        name="From"
        type="enum*"
        description="The method used to send your SMS messages. One of Phone number, Short code, or Sender ID."
      />
      <Attribute
        name="Phone number"
        type="string*"
        description="The phone number to send messages from. Required when From is set to Phone number."
      />
      <Attribute
        name="Short code"
        type="string*"
        description="The short code to send messages from. Required when From is set to Short code."
      />
      <Attribute
        name="Sender ID"
        type="string*"
        description="The Sender ID to send messages from. Required when From is set to Sender ID."
      />
    </Attributes>

  </Accordion>
  <Accordion title="Conditions">
    Set optional per-environment [conditions](/integrations/overview#channel-conditions) for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.
  </Accordion>
</AccordionGroup>

## Recipient data requirements

In order to send an SMS notification you'll need a valid `phone_number` property set on your recipient.



# Webhook

## Overview
Learn more about how to use Knock webhook channels to send to custom destinations, build reusable fetch steps, and to power customer-facing webhooks within your own product.
---
title: Webhook channel overview
description: Learn more about how to use Knock webhook channels to send to custom destinations, build reusable fetch steps, and to power customer-facing webhooks within your own product.
tags: ["webhook", "custom channel"]
section: Integrations > Webhook
layout: integrations
---

Learn more about how to use Knock webhook channels to send to custom destinations, build reusable fetch steps, and to power customer-facing webhooks within your own product.

## Features and use cases

You can use the Knock webhook channel type to build a custom channel that sends a webhook request to a configured endpoint. This endpoint can be static, or can be dynamically built using liquid variables during workflow run time. The Knock webhook channel supports <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-blue-100 dark:bg-transparent dark:border-blue-600">GET</span>, <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-green-100 dark:bg-transparent dark:border-green-600">POST</span>, <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-yellow-100 dark:bg-transparent dark:border-yellow-500">PUT</span>, <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-red-100 dark:bg-transparent dark:border-red-500">DELETE</span>, and <span className="text-xs font-medium text-gray-600 dark:text-gray-300 border border-transparent font-mono rounded p-1 center bg-purple-100 dark:bg-transparent dark:border-purple-500">PATCH</span> requests, making it a flexible tool to use for a number of different use cases.

You might use the Knock webhook channel to...

- Configure a custom channel (examples: PagerDuty, a proprietary in-house service) that you want to send a request to as part of your Knock workflow
- Codify commonly used fetch requests (such as fetching information about a user) for use across your different Knock workflows
- Build user-facing, configurable webhooks into your own product so your users can receive a webhook when something happens in your product

In this overview, we'll cover how to configure webhook channels in Knock and use them in your notification workflows.

## Create and configure your webhook channel

To create your webhook channel, go to the Knock dashboard and navigate to **Integrations** > **Channels**. Click "Create channel," select the Webhook channel type, and click "Next."

Provide a name, key, and description for your webhook channel.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Note:</strong> the name and description provided will be used in
      the workflow builder on steps that use this webhook channel, so be as
      descriptive as possible so other members of your account know how to use
      your webhook channel.
    </>
  }
/>

Once your webhook channel has been created, you'll be able to manage its configuration on a per-environment basis. As with all Knock channels, webhooks can be used in [sandbox mode](/integrations/overview#sandbox-mode) and can be used with [channel conditions](/integrations/overview#channel-conditions).

You'll also need to build the actual webhook request that you want your webhook channel to send when it's triggered within a Knock workflow. We cover this topic in the next section.

## Build your webhook request

To start building your webhook request, navigate to your webhook channel and click "Edit webhook."

You'll now be looking at the webhook channel configuration page. The webhook channel behaves just like our fetch function, it sends a request to the endpoint you define with the headers, params, and body payload you provide.

To learn how to build a webhook request in detail, you can read [our fetch function documentation](/designing-workflows/fetch-function).

<Callout
  emoji="🌠"
  text={
    <>
      <span className="font-bold">Feature tip.</span> You can use liquid in your
      webhook channel request URL, headers, params, and body to dynamically
      build your webhook request during workflow runtime.
      <p>
        As an example if you want to build a webhook that will always fetch the
        recipient's user information, you'd build the following URL to
        dynamically call the endpoint based on the active workflow run's
        recipient ID:{" "}
        <code>{"https://foobar/com/api/users/{{ recipient.id }}"}</code>
      </p>
    </>
  }
/>

## Use your webhook channel

Once your webhook channel is configured and you've built its webhook request, you're ready to add your webhook channel to a workflow.

Webhook channels are added to Knock workflows the same way as any other channel. Just go to the Knock workflow builder and add your webhook step.

### Overriding webhook configurations

When you add your webhook channel to a workflow, it will use the webhook request you built in your channel configuration by default. You can override this on a per-step basis.

Editing a webhook step's template, such as changing the URL or body, creates 'channel setting overrides,' replacing the default environment settings with your changes. Any template modifications will include the entire template (URL, headers, params, and body) in the overrides. These overrides apply to all environments where the step is promoted.

To reset a webhook step to its channel default, click "Reset to default channel settings."

## Securing your webhooks

The webhook channel offers request signing as a setting on the channel. When request signing is enabled, Knock will generate a signing key and use that to sign the request in a `x-webhook-signature` header that can be verified by the consumer.

Request signing is enabled per-environment configuration of the webhook channel under the "Manage configuration" modal.

<Image
  src="/images/integrations/webhooks/signing-key-input.png"
  className="rounded-md mx-auto border border-gray-200"
  width={2692}
  height={1928}
/>

Once request signing is enabled, Knock will generate a signing key for you to verify the signature against. This key can be configured to be any value, or even a dynamic value resolved from the workflow run scope if necessary (see below for more).

### Using a dynamic signing key

In some cases, you may wish to use a **dynamic signing key** to verify your webhooks. For example, if you're using the webhook channel to power customer-configurable webhooks, you may want a different signing key per webhook configuration.

You can add a dynamic signing key by using liquid in the signing key input field. For example, if your signing key was stored on an object that represented the webhook you can reference the key as `{{ recipient.webhook_signing_key }}`.

<Callout
  emoji="🚨"
  text={
    <>
      <strong>Note:</strong> if the signing key is empty the webhook request
      will be skipped.
    </>
  }
/>

### Verifying the signature

The signature is generated with an HMAC using the SHA256 algorithm and, before being encoded, is comprised of the timestamp and the stringified JSON payload of the request. We encode `"timestamp in numerical form"."stringified payload"` as the signature of the request.

The `x-webhook-signature` header is a string comprised of the timestamp used in the encoding and the encoded value above. It will look like this: `t=timestamp,s=encoded-signature`

To test that the payload sent has not been compromised, you can recreate the signature using the signing key found on the webhook channel configuration and compare it to the one sent in the header.

1. Split the `x-webhook-signature` on the comma (",") and extract the values of timestamp and signature.
2. Construct the value of the signature by concatenating:

   - The timestamp (as a string)
   - The character `.`
   - The stringified JSON payload

3. Generate the signature with an HMAC and SHA256 algorithm using the signing key from your webhook's channel configuration.
4. Compare your generated signature with the one extracted in step one; they should match exactly. If the timestamp is more than five minutes old compared to the current time, you may decide you want to reject the payload for additional security.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do webhook steps always execute during a workflow run?">
    Yes. When a webhook channel exists in a workflow, it will send for every workflow run. You do not need to store any channel data on the recipient for the webhook to be triggered.

    If you want webhooks to be recipient-specific, you can use the `recipient.*` namespace to use [recipient](/concepts/recipients) variables in the URL of your webhook. If a recipient doesn't have the requisite variables configured for the webhook request to build correctly, the webhook will not be sent at runtime.

  </Accordion>
  <Accordion title="Can I use the Knock webhook channel to power customer-facing webhooks in my own product?">
    Yes! We cover this in more detail in our guide on [building customer configurable webhooks](/guides/customer-webhooks).
  </Accordion>
</AccordionGroup>



# Extensions

## Overview

## Vercel

## Datadog
Learn more about how to connect Knock with your Datadog account.
---
title: Connecting Knock to your Datadog account
description: Learn more about how to connect Knock with your Datadog account.
layout: integrations
tags: ["datadog", "extensions"]
section: Integrations > Extensions
---

You can use the Knock + Datadog integration to stream workflow, channel, and message metrics from your Knock account to your Datadog account. With this you can:

- Set up custom Datadog monitors and dashboards to track your Knock workflows & channels
- Get up-to-the-minute data on workflows triggered and messages delivered
- Monitor events ingested and actions triggered from event platforms like [Segment](/integrations/sources/segment) and [Rudderstack](/integrations/sources/rudderstack)

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> The Knock
      Datadog extension is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## What this integration does

This integration will send a stream of metrics as they happen from your Knock account to your Datadog account. Metrics are prefixed `knock.*` and include success and failure codes. Metrics are tagged (where applicable) by:

- Environment
- Workflow key
- Workflow exec mode
- Channel or workflow step type
- Integration source type
- Error reason

Please refer to your Datadog pricing agreement for information on how custom metrics sent to Datadog are priced for your account.

At this time there is no way to selectively enable specific metrics, however metrics will only be emitted to Datadog for features that you are actively using in Knock.

## Installing the integration

1. Visit the integrations page in your Knock dashboard, and click the "Extensions" tab
2. Click "Configure Datadog"
3. Enter a Datadog API Key from Datadog's [API Keys](https://app.datadoghq.com/organization-settings/api-keys) page (we recommend creating a dedicated key just for Knock)
4. Pick the correct site for your Datadog account (visit [Datadog's docs](https://docs.datadoghq.com/getting_started/site/) for more information)
5. Click "Connect"

## Dashboard starter kit

Get started with our Datadog dashboard starter kit to start monitoring Knock metrics with just a few clicks:

1. Visit [Datadog's dashboard list](https://app.datadoghq.com/dashboard/lists) and click "New Dashboard"
2. Give it a name and click "New Dashboard"
3. Click the gear icon in the corner of the dashboard and choose "Import dashboard JSON..."

- You may need to close the "Add Widgets" tray to see the gear icon

4. Click the button below to copy the dashboard JSON, and paste it into the Datadog dashboard page when prompted.

<CopyableText
  label="Copy Dashboard Starter Kit JSON"
  content={JSON.stringify(datadogDashboardJson)}
/>

<Image
  src="/images/integrations/extensions/datadog_dashboard.png"
  width={1711}
  height={903}
  className="rounded-md mx-auto"
  alt="The Knock Datadog Dashboard in action"
/>

## Reported metrics

<Attributes>
  <Attribute
    name="knock.message_delivered.total"
    type="count"
    description="How many messages have been delivered, segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.message_delivered_retryable_error.total"
    type="count"
    description="How many deliveries ended in a retryable failure, segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.message_delivered_error.total"
    type="count"
    description="How many deliveries ended in failure (not retryable), segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.message_bounced_error.total"
    type="count"
    description="How many deliveries ended in non-retryable errors from downstream providers, segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.workflow_recipient_run.total"
    type="count"
    description="How many workflow recipient runs have been started, segmented by `workflow` key and `exec_mode`."
  />
  <Attribute
    name="knock.workflow_recipient_run_error.total"
    type="count"
    description="How many errors were experienced during a workflow recipient run, segmented by `workflow` key, `exec_mode`, `step_type`, and the error `reason`. A workflow recipient run can report more than one error."
  />
  <Attribute
    name="knock.integration_event_received.total"
    type="count"
    description="The raw number of events received by Knock from an integration source, segmented by `source_type`."
  />
  <Attribute
    name="knock.integration_action_run.total"
    type="count"
    description="How many actions were triggered by received events, segmented by `source_type` and `action`."
  />
  <Attribute
    name="knock.integration_action_run_error.total"
    type="count"
    description="How many actions failed to run, segmented by `source_type` and `action`."
  />
</Attributes>

- All metrics are segmented by `environment` name (e.g. `production`, `development`)
- For each of the error cases, [the Knock dashboard](https://dashboard.knock.app) can provide more insights into specific failures (e.g. misconfigured workflow, channel, or integration action)

## Uninstalling the integration

1. Visit the integrations page in your Knock dashboard, and click the "Extensions" tab
2. Click the "Disconnect" button for the Datadog extension, and then click "Confirm"
3. If you created a dedicated Datadog API key for Knock, you can now delete the key from Datadog's [API Keys](https://app.datadoghq.com/organization-settings/api-keys) page


## New Relic
Learn more about how to connect Knock with your New Relic account.
---
title: Connecting Knock to your New Relic account
description: Learn more about how to connect Knock with your New Relic account.
layout: integrations
tags: ["new relic", "extensions"]
section: Integrations > Extensions
---

You can use the Knock + New Relic integration to stream workflow, channel, and message metrics from your Knock account to your New Relic account. With this you can:

- Set up custom New Relic monitors and dashboards to track your Knock workflows & channels
- Get up-to-the-minute data on workflows triggered and messages delivered
- Monitor events ingested and actions triggered from event platforms like [Segment](/integrations/sources/segment) and [Rudderstack](/integrations/sources/rudderstack)

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> The Knock New
      Relic extension is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## What this integration does

This integration will stream metrics from your Knock account to your New Relic account. Metrics are prefixed `knock.*` and include success and failure codes. Metrics are tagged (where applicable) by:

- Environment
- Workflow key
- Workflow exec mode
- Channel or workflow step type
- Integration source type
- Error reason

Please refer to your New Relic pricing agreement for information on how custom metrics sent to New Relic are priced for your account.

At this time there is no way to selectively enable specific metrics, but metrics will only be emitted to New Relic for features that you are actively using in Knock.

## Installing the integration

1. Visit the integrations page in your Knock dashboard, and click the "Extensions" tab
2. Click "Configure New Relic"
3. Enter a New Relic API Key from New Relic's [API Keys](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) page (we recommend creating a dedicated key just for Knock)
4. Pick the correct site for your New Relic data hosting (visit [New Relic's docs](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center/) for more information)
5. Click "Connect"

<Callout
  emoji="🔦"
  text={
    <>
      When creating a New Relic API key, make sure "Key Type" is marked as{" "}
      <strong> Ingest - License </strong>
    </>
  }
/>

## Dashboard starter kit

Get started with our New Relic dashboard starter kit to start monitoring Knock metrics with just a few clicks:

1. Visit New Relic's [all capabilities page](https://one.newrelic.com/all-capabilities) and click on "Dashboards"
2. In the top-right corner, click "Import dashboard"
3. Click the button below to copy the dashboard JSON, and paste it into the New Relic page when prompted.

<CopyableText
  label="Copy Dashboard Starter Kit JSON"
  content={JSON.stringify(newRelicDashboardJson)}
/>

<Image
  src="/images/integrations/extensions/new_relic_dashboard.png"
  width={1714}
  height={966}
  className="rounded-md mx-auto border border-gray-200"
  alt="The Knock New Relic Dashboard in action"
/>

## Reported metrics

<Attributes>
  <Attribute
    name="knock.message_delivered.total"
    type="count"
    description="How many messages have been delivered, segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.message_delivered_retryable_error.total"
    type="count"
    description="How many deliveries ended in a retryable failure, segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.message_delivered_error.total"
    type="count"
    description="How many deliveries ended in failure (not retryable), segmented by `channel` and `workflow` key."
  />
  <Attribute
    name="knock.workflow_recipient_run.total"
    type="count"
    description="How many workflow recipient runs have been started, segmented by `workflow` key and `exec_mode`."
  />
  <Attribute
    name="knock.workflow_recipient_run_error.total"
    type="count"
    description="How many errors were experienced during a workflow recipient run, segmented by `workflow` key, `exec_mode`, `step_type`, and the error `reason`. A workflow recipient run can report more than one error."
  />
  <Attribute
    name="knock.integration_event_received.total"
    type="count"
    description="Hhe raw number of events received by Knock from an [integration source](https://docs.knock.app/integrations/sources/overview), segmented by `source_type`."
  />
  <Attribute
    name="knock.integration_action_run.total"
    type="count"
    description="How many actions were triggered by received events, segmented by `source_type` and `action`."
  />
  <Attribute
    name="knock.integration_action_run_error.total"
    type="count"
    description="How many actions failed to run, segmented by `source_type` and `action`."
  />
</Attributes>

- All metrics are segmented by `environment` name (e.g. `production`, `development`)
- For each of the error cases, [the Knock dashboard](https://dashboard.knock.app) can provide more insights into specific failures (e.g. misconfigured workflow, channel, or integration action)

## Uninstalling the integration

1. Visit the integrations page in your Knock dashboard, and click the "Extensions" tab
2. Click the "Disconnect" button for the New Relic extension, and then click "Confirm"
3. If you created a dedicated New Relic API key for Knock, you can now delete the key from New Relics's [API Keys](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) page


## Segment
Learn more about how to connect Knock with your Segment account.
---
title: How to send Knock data to Segment
description: Learn more about how to connect Knock with your Segment account.
layout: integrations
tags: ["segment", "extensions", "analytics"]
section: Integrations > Extensions
---

This guide covers how to use our Segment extension to send Knock's normalized notification data into [Segment](https://segment.io) to forward on to your data warehouse or other tools where you run data analysis, such as Amplitude or Mixpanel.

Once the extension is enabled, Knock automatically passes a stream of `track` events to Segment (e.g. `Notification delivered`, `Notification seen`, `Notification read`) which you can then use in your downstream tools.

Knock also provides a separate integration for using Segment as a [Knock source](/integrations/sources/overview) to bring `track` and `identify` event data from Segment into Knock to power your notifications. You can learn more in our [Segment source docs](/integrations/sources/segment).

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> The Knock
      Segment extension is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## Getting started

Knock uses the Segment HTTP Source to send events to your Segment account. Each HTTP Source has a Write Key associated with it that Knock can use to push events into Segment. A best practice is to create a separate Segment HTTP Source for each Knock environment from which you plan to collect events.

1. Create a new Segment HTTP Source in your Segment Account for each Knock environment from which you plan to collect events
   1. Log into Segment, click **Connections** > **Sources**, and then choose "Add Source"
   2. Find the "HTTP API" source and click "Add Source"
   3. Give it a useful name, e.g. "Knock Production"
   4. Make note of the write key
   5. Repeat these steps for each Knock environment you need to configure
2. Visit the **Integrations** page in your Knock account and go to the **Extensions** tab
3. Find the Segment extension and click "Connect"
4. In the modal that appears, enter the write key for each environment you want to configure. Leave the field blank to disable writing events from that environment
5. Once you click save, events will begin flowing from that environment to Segment

<Image
  src="/images/integrations/extensions/connect-segment-modal.png"
  width={500}
  height={466}
  className="rounded-md mx-auto border border-gray-200"
  alt="Segment extension configuration example"
/>

## Events sent to Segment

When connected, Knock will forward the following `track` events to Segment.

<Table
  headers={["Event", "Description"]}
  rows={[
    [
      "Notification sent",
      "Occurs when a message is successfully sent to a channel provider.",
    ],
    [
      "Notification delivered",
      "Occurs when a message is marked as delivered to the user by the provider. This is only available on email providers with delivery tracking enabled.",
    ],
    [
      "Notification undelivered",
      "Occurs when a message delivery attempt fails permanently. Delivery will not be retried.",
    ],
    ["Notification seen", "Occurs when a message is seen by its recipient."],
    [
      "Notification unseen",
      "Occurs when a message is marked unseen by the recipient.",
    ],
    [
      "Notification read",
      "Occurs when a message is marked as read by its recipient.",
    ],
    [
      "Notification unread",
      "Occurs when a message is marked unread by the recipient.",
    ],
    [
      "Notification archived",
      "Occurs when a message is archived by its recipient.",
    ],
    [
      "Notification unarchived",
      "Occurs when a message is unarchived by its recipient.",
    ],
    [
      "Notification clicked",
      "Occurs when a link is clicked by the message recipient. This is only available when Knock link tracking is enabled.",
    ],
    [
      "Notification interacted",
      "Occurs when a recipient interacts with a message. This is only available when Knock link tracking is enabled.",
    ],
  ]}
/>

## Event schema

Knock uses the Segment [Track spec](https://segment.com/docs/connections/spec/track/) for the event data we pass to Segment. You can find an example payload of what you can expect from Knock events coming into Segment below.

```json title="example Segment Track event payload"
{
  "context": {
    "library": {
      "name": "unknown",
      "version": "unknown"
    }
  },
  "event": "Notification Seen",
  "integrations": {},
  "messageID": "2XoNHQx7lPp0zsCtZh3BGgCJxxx",
  "messageId": "api-2ZjG9Ho7EeqVV9uqkdlSRYbDxxx",
  "originalTimestamp": "2023-12-18T19:31:58.653982Z",
  "properties": {
    "channelId": "26d3f6ad-eebc-4ce4-9125-bb856dad8xxx",
    "channelType": "in_app_feed",
    "environment": "Production",
    "messageId": "2XoNHQx7lPp0zsCtZh3BGgCJxxx",
    "provider": "in_app_feed_knock",
    "stepRef": "YJAxjVC-ya69fBhoSFxxx",
    "workflowKey": "account-invite-accepted"
  },
  "receivedAt": "2023-12-18T19:32:01.326Z",
  "sentAt": null,
  "timestamp": "2023-12-18T19:31:58.653Z",
  "type": "track",
  "userId": "70171a84-7e52-46d7-8866-5b4ab88cxxx",
  "writeKey": "REDACTED"
}
```


## Heap
Learn more about how to connect Knock with your Heap account.
---
title: How to send Knock data to Heap
description: Learn more about how to connect Knock with your Heap account.
layout: integrations
tags: ["heap", "extensions", "analytics"]
section: Integrations > Extensions
---

This guide covers how to use our Heap extension to send Knock's normalized notification data into [Heap](https://heap.io) to forward on to your data warehouse or other tools where you run data analysis, such as Amplitude or Mixpanel.

Once the extension is enabled, Knock automatically passes a stream of `track` events to Heap (e.g. `Notification delivered`, `Notification seen`, `Notification read`) which you can then use in your downstream tools.

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> The Knock Heap
      extension is only available on our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## Getting started

Knock uses the Heap Bulk Track endpoint to send events to your Heap project environments. Each Heap project has a group of environments, and each of them has an `environment id` associated with it that Knock can use to push events into Heap.

A best practice is to create a separate Heap environment for each Knock environment from which you plan to collect events.

1. Create a new Heap project with environments in your Heap account. You need to create one Heap environment for each Knock environment from which you plan to collect events
   1. Log into your Heap dashboard, click **Account** > **Manage** > **Projects**, and then choose your main project
   2. A list of environments will appear on your right side of the screen. By default Heap creates two environments (Production and development), but you can create more if you need it
   3. Each environment has an `id` that will be used by Knock to send events to the given environment
2. Visit the Integrations page in your Knock account and go to the Extensions Tab
3. Find the Heap extension and click "Connect"
4. In the modal that appears, enter the Heap environment id for each environment you want to configure. Leave the field blank to disable writing events from that environment
5. Once you click save, events will begin flowing from that environment to Heap

<Image
  src="/images/integrations/extensions/connect-heap-modal.png"
  width={500}
  height={488}
  className="rounded-md mx-auto border border-gray-200"
  alt="Heap extension configuration example"
/>

## Label custom events

Heap requires the labeling of custom received events from Knock before their use.

1. From your Heap dashboard, navigate to **Data** > **Labeled Events** and click on "Label event" or **Property** > **Event**
2. Select "Custom" under the source filter and choose one of the previously received events that you want to label
3. Add a name for the given event and click on "Label event"
4. Finally, click on "Verify event"
5. Once these steps are completed, the validated event will be ready for analysis and usage in your charts

You can find more information about custom events and how to use them in the [Heap documentation](https://help.heap.io/data-types/events/how-to-use-custom-events-to-build-new-events/)

<Callout
  emoji="🔦"
  text={
    <>
      Heap has an expected latency for custom track events, which is typically
      less than 1 hour. Bear in mind that events may not immediately appear for
      labeling.
    </>
  }
/>
## Events sent to Heap

When connected, Knock will forward the following `Track` events to Heap.

<Table
  headers={["Event", "Description"]}
  rows={[
    [
      "Notification sent",
      "Occurs when a message is successfully sent to a channel provider.",
    ],
    [
      "Notification delivered",
      "Occurs when a message is marked as delivered to the user by the provider. This is only available on email providers with delivery tracking enabled.",
    ],
    [
      "Notification undelivered",
      "Occurs when a message delivery attempt fails permanently. Delivery will not be retried.",
    ],
    ["Notification seen", "Occurs when a message is seen by its recipient."],
    [
      "Notification unseen",
      "Occurs when a message is marked unseen by the recipient.",
    ],
    [
      "Notification read",
      "Occurs when a message is marked as read by its recipient.",
    ],
    [
      "Notification unread",
      "Occurs when a message is marked unread by the recipient.",
    ],
    [
      "Notification archived",
      "Occurs when a message is archived by its recipient.",
    ],
    [
      "Notification unarchived",
      "Occurs when a message is unarchived by its recipient.",
    ],
    [
      "Notification clicked",
      "Occurs when a link is clicked by the message recipient. This is only available when Knock link tracking is enabled.",
    ],
    [
      "Notification interacted",
      "Occurs when a recipient interacts with a message. This is only available when Knock link tracking is enabled.",
    ],
  ]}
/>

## Event schema

Knock uses the Heap [Bulk track endpoint](https://developers.heap.io/reference/bulk-track) for sending event data to Heap. You can find an example payload of what you can expect from Knock events coming into Heap below.

```json title="An example Heap Track event payload"
{
  "event": "Notification Sent",
  "identity": "70171a84-7e52-46d7-8866-5b4ab88cxxx",
  "properties": {
    "channelId": "26d3f6ad-eebc-4ce4-9125-bb856dad8xxx",
    "channelType": "in_app_feed",
    "environment": "Production",
    "messageId": "2XoNHQx7lPp0zsCtZh3BGgCJxxx",
    "provider": "in_app_feed_knock",
    "stepRef": "YJAxjVC-ya69fBhoSFxxx",
    "workflowKey": "account-invite-accepted"
  },
  "timestamp": "2024-02-23T17:06:35.415647Z"
}
```


## Data warehouse sync
Sync notification analytics data from Knock into your own data warehouse
---
title: Data warehouse sync
description: Sync notification analytics data from Knock into your own data warehouse
layout: integrations
section: Integrations > Extensions
---

You can bring your notification analytics from Knock into your own data warehouse so that you can analyze it alongside the rest of your data. To set up this sync, please contact our [support team](mailto:support@knock.app).

<Callout
  emoji="✨"
  text={
    <>
      <span className="font-bold">Enterprise plan feature.</span> Data warehouse
      sync is available exclusively with our{" "}
      <a href="https://knock.app/pricing">Enterprise plan</a>.
    </>
  }
/>

## How it works

Knock leverages [Prequel](https://www.prequel.co/) to integrate with your data warehouse. There is no self-service UI to connect your account to start receiving data; instead when you contact us to set up a sync we'll send you a secure link to fill in the information about your data warehouse. Once it's connected, you'll begin receiving a [backfill of historical data](https://docs.prequel.co/docs/transfer-logic#backfills--full-refreshes), and then going forward you will receive the most up to date data on an ongoing basis.

## Setup

First, you'll have to give Knock your database type and host destination address for your data warehouse. The databases supported as destinations for Knock are [those listed on Prequel](https://docs.prequel.co/docs/destinations-overview).

Next, Knock generates a magic link you'll fill out. See what information you'll need for your particular database [here](https://docs.prequel.co/reference/post_import-magic-links).

Once the information is filled out, Prequel will provide you with a table definition. Additionally, you can run a test connection to make sure it's wired up. If it's successful, you can save it and it will proceed with the backfill transfer.

## Available data

### Messages table

Our data warehouse connector syncs data from our `messages` table. Each `message` represents a notification that was executed for a single recipient. You can read more about messages as a concept [here](/concepts/messages).

Below is a description of the columns included in the table and the data type of each. To see how this data type will map onto the data types of your destination table, check the [destination type mapping](https://docs.prequel.co/docs/data-types#destination-type-mapping) in the Prequel docs.

<AccordionGroup>
<Accordion title="Table definition example">
    Please note that the table name will vary based on the name of the schema provided when filling out the form.
    ```sql
        CREATE TABLE <name of schema>.messages (
          message_id character varying(65535) NOT NULL ENCODE raw distkey,
            account_id character varying(65535) ENCODE lzo,
            environment_id character varying(65535) ENCODE lzo,
            environment_name character varying(65535) ENCODE lzo,
            environment_slug character varying(65535) ENCODE lzo,
            channel_id character varying(65535) ENCODE lzo,
            channel_name character varying(65535) ENCODE lzo,
            channel_key character varying(65535) ENCODE lzo,
            channel_type character varying(65535) ENCODE lzo,
            channel_provider character varying(65535) ENCODE lzo,
            workflow_id character varying(65535) ENCODE lzo,
            workflow_key character varying(65535) ENCODE lzo,
            combined_trigger_data character varying(32768) ENCODE lzo,
            step_ref character varying(65535) ENCODE lzo,
            recipient_id character varying(65535) ENCODE lzo,
            recipient_type character varying(65535) ENCODE lzo,
            tenant_id character varying(65535) ENCODE lzo,
            exec_mode character varying(65535) ENCODE lzo,
            message_status character varying(65535) ENCODE lzo,
            inserted_at timestamp with time zone ENCODE az64,
            updated_at timestamp with time zone ENCODE raw,
            seen_at timestamp with time zone ENCODE az64,
            read_at timestamp with time zone ENCODE az64,
            clicked_at timestamp with time zone ENCODE az64,
            interacted_at timestamp with time zone ENCODE az64,
            archived_at timestamp with time zone ENCODE az64,
            has_been_seen bigint ENCODE az64,
            has_been_read bigint ENCODE az64,
            has_been_clicked bigint ENCODE az64,
            has_been_interacted bigint ENCODE az64,
            has_been_archived bigint ENCODE az64,
            actors character varying(65535) ENCODE lzo
            PRIMARY KEY (message_id)
        ) DISTSTYLE KEY SORTKEY (message_id, updated_at);
    ```
  </Accordion>
  <Accordion title="Messages table structure">
  See possible [engagement statuses](/send-notifications/message-statuses#engagement-status) for a message.

    <Table
      headers={["Name", "Type", "Description"]}
      rows={[
        [
          "message_id",
          "string",
          "The unique identifier for this message and the primary key for this table",
        ],
        ["account_id", "string", "The UUID of the message's account"],
        ["environment_id", "string", "The UUID of the message's environment"],
        ["environment_name", "string", "The name of the message's environment"],
        ["environment_slug", "string", "The slug of the message's environment"],
        ["channel_id", "string", "The UUID of the channel the message was sent on"],
        [
          "channel_key",
          "string",
          "The unique key of the channel the message was sent on",
        ],
        [
          "channel_name",
          "string",
          "The name of the channel the message was sent on",
        ],
        [
          "channel_provider",
          "string",
          "The provider for the channel the message was sent on",
        ],
        ["channel_type", "string", "The type of channel the message was sent on"],
        [
          "workflow_id",
          "string",
          "The UUID of the version of the workflow that the message belongs to",
        ],
        [
          "workflow_key",
          "string",
          "The unique key of the workflow the message belongs to",
        ],
        [
          "combined_trigger_data",
          "json",
          <div key="combined_trigger_data_body">
            Combined and truncated trigger data for the workflow run that generated the message, at the time the message was created. See the <a target="_blank" rel="noreferrer" href="/reference#trigger-data-filtering">trigger data filtering guide</a> for more info.
          </div>
        ],
        [
          "step_ref",
          "string",
          "The reference of the step on the workflow that the message belongs to",
        ],
        ["recipient_id", "string", "The ID of the recipient for the message"],
        [
          "recipient_type",
          "string",
          <div key="recipient_type_body">
            The{" "}
            <a
              target="_blank"
              rel="noreferrer"
              href="/concepts/recipients"
            >
              type of recipient for the message
            </a>
            , can be a user or an object
          </div>,
        ],
        ["tenant_id", "string", "The tenant associated with this message"],
        [
          "exec_mode",
          "string",
          <div key="exec_mode_body">
            The execution mode of the workflow. Possible values are:
            <ul>
              <li>
                <code>trigger</code> - from the API
              </li>
              <li>
                <code>rehearse</code> - test run
              </li>
              <li>
                <code>rehearse_step</code> - test run a single step
              </li>
              <li>
                <code>integration</code> - from an event integration source
              </li>
              <li>
                <code>scheduled</code> - previously scheduled execution
              </li>
            </ul>
          </div>,
        ],
        [
          "message_status",
          "string",
          <div key="message_status_body">
            The latest{" "}
            <a
              target="_blank"
              rel="noreferrer"
              href="/send-notifications/message-statuses#delivery-status"
            >
              delivery status of a message
            </a>
            .
          </div>,
        ],
        [
          "inserted_at",
          "timestamp",
          "The timestamp of when the message was created",
        ],
        [
          "updated_at",
          "timestamp",
          "The timestamp of when the message was last updated",
        ],
        [
          "archived_at",
          "timestamp",
          "The timestamp of when the message was archived",
        ],
        ["seen_at", "timestamp", "The timestamp of when the message was seen"],
        ["read_at", "timestamp", "The timestamp of when the message was read"],
        [
          "clicked_at",
          "timestamp",
          "The timestamp of when a link in the message was clicked",
        ],
        [
          "interacted_at",
          "timestamp",
          "The timestamp of when the message was interacted with",
        ],
        [
          "has_been_seen",
          "integer (0 = false, 1 = true)",
          "Whether the message has been seen",
        ],
        [
          "has_been_read",
          "integer (0 = false, 1 = true)",
          "Whether the message has been read",
        ],
        [
          "has_been_clicked",
          "integer (0 = false, 1 = true)",
          "Whether a link in the message has been clicked",
        ],
        [
          "has_been_interacted",
          "integer (0 = false, 1 = true)",
          "Whether the message has been interacted with",
        ],
        [
          "has_been_archived",
          "integer (0 = false, 1 = true)",
          "Whether the message has been archived",
        ],
        [
          "actors",
          "json",
          <div key="actors">
            A JSON array of actor users or objects. Users are provided as string IDs. Objects are provided as JSON dictionaries with keys for "id" and "collection". See the <a target="_blank" rel="noreferrer" href="/concepts/recipients#recipientidentifier-definition"><code>RecipientIdentifier</code> definition</a> for more info.
          </div>
        ],
      ]}
    />

  </Accordion>
</AccordionGroup>

### Recipient change stream table

<Callout
  emoji="👉"
  text={
    <>
      <strong>Note:</strong> at this time, the recipient change stream table
      contains only users. Please{" "}
      <a href="mailto:support@knock.app">contact us</a> if you need to sync
      other recipient types.
    </>
  }
/>

Our data warehouse connector syncs data from our `recipients` table. Each row captures the properties and preferences of a [Recipient](/concepts/recipients) at a given moment in time.

Each row has an `event_type` indicating how the event was generated. Possible values are:

- `recipient.created` - indicates the first time a recipient was identified
- `recipient.snapshot` - is emitted every time a recipient's properties or preferences are updated, and contains the complete set of properties and preferences at that moment in time. This event may also be generated manually for all or a subset of recipients (by ID) by contacting support.
- `recipient.deleted` - contains no properties or preferences, but indicates when a recipient was deleted. A recipient may be re-identified after being deleted, which will generate another recipient.created event

Events in the recipient change stream table are retained for 7 days.

Below is a description of the columns included in the table and the data type of each. To see how this data type will map onto the data types of your destination table, check the [destination type mapping](https://docs.prequel.co/docs/data-types#destination-type-mapping) in the Prequel docs.

<AccordionGroup>
<Accordion title="Table definition example">
    Please note that the table name will vary based on the name of the schema provided when filling out the form.
    ```sql
        CREATE TABLE <name of schema>.recipient_change_stream (
          id character varying(65535) NOT NULL ENCODE raw distkey,
            account_id character varying(65535) ENCODE lzo,
            environment_id character varying(65535) ENCODE lzo,
            environment_name character varying(65535) ENCODE lzo,
            environment_slug character varying(65535) ENCODE lzo,
            recipient_id character varying(65535) ENCODE lzo,
            recipient_type character varying(65535) ENCODE lzo,
            event_Type character varying(65535) ENCODE lzo,
            properties json ENCODE lzo,
            preferences json ENCODE lzo,
            timestamp timestamp with time zone ENCODE az64,
            PRIMARY KEY (id)
        ) DISTSTYLE KEY SORTKEY (id, timestamp);
    ```
  </Accordion>
  <Accordion title="Recipient change stream table structure">
    <Table
      headers={["Name", "Type", "Description"]}
      rows={[
        ["id", "string", "Unique event ID. Can be used to deduplicate events."],
        ["account_id", "string", "The UUID of the recipient's account"],
        ["environment_id", "string", "The UUID of the recipient's environment"],
        ["environment_name", "string", "The name of the recipient's environment"],
        ["environment_slug", "string", "The slug of the recipient's environment"],
        ["recipient_id", "string", "The ID of the recipient for the message"],
        ["recipient_type", "string",
            <div key="recipient_type_body">
              The <a target="_blank" rel="noreferrer" href="/concepts/recipients"> type of recipient recorded</a>
            </div>,
        ],
        ["event_type", "string",
            <div key="event_type_body">
              Possible values are:
              <ul>
                <li><code>recipient.created</code> - indicates the first time a recipient was identified</li>
                <li><code>recipient.snapshot</code> - is emitted every time a recipient properties or preferences are updated, and contains the complete set of properties and preferences at that moment in time</li>
                <li><code>recipient.deleted</code> - contains no properties or preferences, but indicates when a recipient was deleted. A recipient may be re-identified after being deleted, which will generate another recipient.created event</li>
              </ul>

              A manual snapshot of the current state of all or a subset of recipients (by ID) can be made by contacting support.
            </div>,
        ],
        ["properties", "json",
            <div key="properties_body">
              All properties currently assigned to the recipient. Will be empty for <code>recipient.deleted</code>.
            </div>,
        ],
        ["preferences", "json",
            <div key="preferences_body">
              All preference sets currently assigned to the recipient, keyed by preference set ID. Will be empty for <code>recipient.deleted</code>.
            </div>,
        ],
        ["timestamp", "timestamp", "The timestamp of when the event was emitted."]
      ]}
    />

  </Accordion>
</AccordionGroup>



# API Reference
Complete reference documentation for the Knock API.

## API Reference
Complete reference documentation for the Knock API. Includes code snippets and examples for our Python, Elixir, PHP, Node.js, Go, Ruby, and .NET libraries.
---
title: API reference
description: Complete reference documentation for the Knock API. Includes code snippets and examples for our Python, Elixir, PHP, Node.js, Go, Ruby, and .NET libraries.
showNav: false
layout: api
tags: ["api", "sdks", "api key", "keys", "errors"]
---

<a id="overview" className="absolute -top-8 invisible" />

<Section title="API Reference" slug="overview">
<ContentColumn>
The Knock API enables you to add a complete notification engine to your product. This API provides
programmatic access to integrating Knock via a REST-ful API.

</ContentColumn>
<ExampleColumn>

```bash title="Base URL"
https://api.knock.app/v1
```

</ExampleColumn>

</Section>

<Section title="Client libraries" slug="client-libraries">
<ContentColumn>

Knock offers native SDKs in several popular programming languages:

- [Node JS](https://github.com/knocklabs/knock-node)
- [Python](https://github.com/knocklabs/knock-python)
- [Ruby](https://github.com/knocklabs/knock-ruby)
- [Go](https://github.com/knocklabs/knock-go)
- [PHP](https://github.com/knocklabs/knock-php)
- [Java](https://github.com/knocklabs/knock-java)
- [C# (dotnet)](https://github.com/knocklabs/knock-dotnet)
- [Elixir](https://github.com/knocklabs/knock-elixir)

</ContentColumn>
</Section>

<Section title="API keys" slug="api-keys">
<ContentColumn>

Knock authenticates your API requests using your account's API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error.

You can view and manage your API keys in the Developer Dashboard. There are two types of API keys:

- Publishable keys are only meant to identify your account with Knock. They aren't secret, and can safely be made public in any of your client-side code. Publishable keys are prefixed with `pk_*`.

- Secret keys can perform any API request to Knock, they should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. Secret keys are prefixed with `sk_*`.

Each Environment in your account has both a publishable and secret key pair. API requests will be scoped to the provided key's Environment.

</ContentColumn>
</Section>

<Section title="Authentication" slug="authentication">
<ContentColumn>

You must pass your API key to Knock as a Bearer token using the `Authorization` header.

</ContentColumn>
<ExampleColumn>

```bash title="Authentication header"
Authorization: Bearer sk_test_12345
```

</ExampleColumn>
</Section>

<Section title="Rate limits" slug="rate-limits">
<ContentColumn>

Each endpoint in the Knock API is rate limited. Knock uses a tier system to determine the rate limit scale for each endpoint. When your request has been rate limited, the Knock API will return a `429 Too Many Requests` error in response.

<Callout
  emoji="💡"
  text={
    <>
      <strong>Rate limit tiers are assigned per-endpoint.</strong> Knock does
      not have separate rate limit tiers for different accounts or pricing
      plans. Each endpoint in this reference has a rate limit tier label that
      indicates the scale of requests you can make to that endpoint.
    </>
  }
/>

Knock's default behavior scopes rate limits based on the authorizing credential used in your requests. When you use a public or private API key to authorize a request, Knock will scope the rate limit for each endpoint by the [environment](/concepts/environments) associated with the key. If you use a signed user token as your authorizing credential, Knock will scope the rate limit by both the key's environment and the signing user. See our guide on [enhanced security mode](/in-app-ui/security-and-authentication#authentication-with-enhanced-security) for more details on working with signed user tokens.

If you're concerned about exceeding a Knock rate limit, please [contact us](https://knock.app/contact-sales) and we can help figure out a usage rate that's right for your specific needs.

</ContentColumn>
<ExampleColumn>

<div className="prose-sm lg:prose dark:prose-invert">
  <table>
    <thead>
      <tr>
        <th>Scale</th>
        <th>Limit</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <RateLimit tier={1} />
        </td>
        <td>1 request / second</td>
      </tr>
      <tr>
        <td>
          <RateLimit tier={2} />
        </td>
        <td>5 requests / second</td>
      </tr>
      <tr>
        <td>
          <RateLimit tier={3} />
        </td>
        <td>60 requests / second</td>
      </tr>
      <tr>
        <td>
          <RateLimit tier={4} />
        </td>
        <td>200 requests / second</td>
      </tr>
      <tr>
        <td>
          <RateLimit tier={5} />
        </td>
        <td>1,000 requests / second</td>
      </tr>
    </tbody>
  </table>
</div>

</ExampleColumn>
</Section>

<Section title="Batch and bulk endpoint deduplication rate limits" slug="batch-rate-limits">
<ContentColumn>

Knock's batch and bulk endpoints may also have an additional layer of rate limiting applied. For these cases, Knock will also limit the number of times you can update a specific entity over a given scale. These limits are in place to prevent too many duplicate modifications applied to the same set of entities.

When you exceed a batch deduplication rate limit, Knock will still return a success (`2xx`) response if it is able to handle the request. For any entities not updated due to a rate limit hit, Knock will return the data as it exists at request time. Knock will also include an `x-ratelimited-{param}` header. The `{param}` value will be the name of the request param within which the rate limit was applied. The value will be a comma-delimited string of the param values that were rejected due to a rate limit hit.

Knock can apply batch deduplication rate limits to all or part of a request. If Knock rejects a subset of your batch, you can expect to see the full set of requested entities in the response body, and the IDs of those that were rejected in the `x-ratelimited-{param}` header.

</ContentColumn>
<ExampleColumn>

<div className="prose-sm lg:prose dark:prose-invert mb-6">
  <table>
    <thead>
      <tr>
        <th>Scale</th>
        <th>Limit</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <RateLimit isBatch tier={1} />
        </td>
        <td>1 update / second / entity</td>
      </tr>
    </tbody>
  </table>
</div>

```json title="Example request body"
{
  "message_ids": [1, 2, 3, 4]
}
```

```json title="Example response body"
[
  { "__typename": "Message", "id": 1 },
  { "__typename": "Message", "id": 2 },
  { "__typename": "Message", "id": 3 },
  { "__typename": "Message", "id": 4 }
]
```

```json title="Example response header"
{
  "x-ratelimited-message_ids": "2,4"
}
```

</ExampleColumn>
</Section>

<Section title="Idempotent requests" slug="idempotent-requests">
<ContentColumn>

Knock supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) so that requests can be retried safely without unintended side effects.

To perform an idempotent request, set an `Idempotency-Key` header on your request. This idempotency key is a unique value that you generate for each request. It is used to identify and prevent the duplicate processing of requests. If you retry a request with the same idempotency key within 24 hours from the original request, Knock will return the same response as the original request. You may use any string up to 255 characters in length as an idempotency key.

Idempotency keys can be random UUIDs, or they can have some meaning in your application. For example, if you are sending a notification after a user has placed an order, you could use a key that is a combination of the reason for the notification, the user ID, and the order ID (e.g. `order-placed:user-123:order-456`). If your user then cancels the order, you could use an idempotency key like `order-cancelled:user-123:order-456`. This will ensure each type of notification is only sent once, even if your system retries the request multiple times.

If you are making calls to Knock from a job queue, the ID of the job can be a good choice for an idempotency key. If the job fails and is retried, the same idempotency key will be used.

<Callout
  emoji="💡"
  text={
    <>
      <strong>
        The default idempotency window for the Knock API is 24 hours.
      </strong>{" "}
      If you're interested in configuring a different idempotency window for
      your account, please contact us at{" "}
      <a href="mailto:support@knock.app">support@knock.app</a>.
    </>
  }
/>

</ContentColumn>
<ExampleColumn>

<Endpoints title="Supported endpoints">
  <Endpoint
    name="trigger-workflow"
    method="POST"
    path="/workflows/:key/trigger"
    withLink
  />
</Endpoints>

<MultiLangCodeBlock
  snippet="api.idempotency"
  title="Making an idempotent API call"
/>

```json title="Response headers"
{
  "idempotent-replayed": "true",
  "original-x-request-id": "F1FIj5XwD_m4h0sAASfi"
}
```

</ExampleColumn>
</Section>

<Section title="Data retention" slug="data-retention">
<ContentColumn>

Several V1 API endpoints return data that is subject to deletion according to the data retention policy associated with your account. These endpoints are tagged with the `Retention policy applied` badge.

For more information, see the [data retention docs](/manage-your-account/data-retention).

</ContentColumn>
</Section>

<Section title="Bulk endpoints" slug="bulk-endpoints">
<ContentColumn>

Knock exposes several endpoints that enqueue and return a `BulkOperation`. These endpoints perform their logic asynchronously, and you use the `BulkOperation` record to track progress.

In some cases, a bulk endpoint will accept a large set of entities to perform some action upon. In others, a bulk endpoint will accept a set of filter parameters and then execute an action across a large set of data on your account.

See the [Bulk operations section](#bulk-operations) for more information on parsing and polling bulk operation statuses.

</ContentColumn>
</Section>

<Section title="Trigger data filtering" slug="trigger-data-filtering">
<ContentColumn>

Some V1 API endpoints that return lists of message data accept a `trigger_data` parameter. Knock uses this parameter to scope results it returns down to messages generated with the trigger data you provide.

The trigger data that Knock filters against is the _**combined and truncated data from the time the message was generated**_.

If a batch step preceded the creation of your message, the trigger data available for filtering will be the combined data for all the workflow triggers bundled into your batch. If a fetch step preceded, then the filterable data will include any data pulled in via the fetch step request.

Knock truncates trigger data for filtering to ensure it can efficiently process your request. The current data truncation rules are:

- Nested data structures (objects and arrays) are removed. Trigger data for filtering will be a JSON object with a single level of key-value pairs.
- Supported values are the JSON scalars string, number, boolean, and `null`.
- String values are limited to 256 characters in length. Strings that exceed this limit are truncated to the maximum.

</ContentColumn>
</Section>

<Section title="Pagination" slug="pagination">
<ContentColumn>

All top-level API resources expose support for bulk fetches via a `list` method. For instance, you can [list users](#list-users), [list objects](#list-objects) in a collection, and [list subscriptions](#list-subscriptions).

Resources that return multiple entities support the same cursor-based pagination to interact with the resources, using `after`, `before`, and `page_size` parameters as well as returning a common format for the metadata associated with the page.

### Query parameters

<Attributes>
  <Attribute
    name="after"
    type="string"
    description="The pagination cursor to fetch items after. Usually derived from the after cursor in `PageInfo`."
  />
  <Attribute
    name="before"
    type="string"
    description="The pagination cursor to fetch items before. Usually derived from the before cursor in `PageInfo`."
  />
  <Attribute
    name="page_size"
    type="number (optional)"
    description="A number between 1 and 50 that represents the number of items to return in the response. Defaults to 50."
  />
</Attributes>

### Response format

<Attributes>
  <Attribute
    name="entries"
    type="object[]"
    description="A list of items contained in this response"
  />
  <Attribute
    name="page_info"
    type="PageInfo"
    description="Metadata about the page of data returned"
  />
</Attributes>

### PageInfo response details

<Attributes>
  <Attribute
    name="after"
    type="string"
    description="The cursor to use to fetch items after the last item in the list. May be null when there are no other items to retrieve."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to use to fetch items before the first item in the list. May be null when there are no other items to retrieve."
  />
  <Attribute
    name="page_size"
    type="number"
    description="The maximum number of items requested in the page"
  />
  <Attribute
    name="total_count"
    type="number"
    description="The total number of items in this resource (up-to 10,000)"
  />
</Attributes>

</ContentColumn>

<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "User",
      "id": "user_1",
      "name": "User name",
      "email": "user-1@example.com",
      "created_at": null,
      "updated_at": "2021-03-05T12:00:00Z"
    },
    {
      "__typename": "User",
      "id": "user_2",
      "name": "User name",
      "email": "user-2@example.com",
      "created_at": null,
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "page_size": 50,
    "total_count": 2,
    "after": null,
    "before": null
  }
}
```

</ExampleColumn>
</Section>

<Section title="Errors" slug="errors" direction="column">
<ContentColumn>

Knock uses standard [HTTP response codes](https://developer.mozilla.org/en-US/Web/HTTP/Status) to indicate the success or failure of your API requests.

- `2xx` success status codes confirm that your request worked as expected.

- `4xx` error status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key).

- `5xx` error status codes indicate a Knock server error.

</ContentColumn>
</Section>

<Section title="Error codes" slug="error-codes" direction="column">
<div className="w-full">

<span className="mb-6">
  {"Here's a list of common "}
  <span className="bg-code-background text-code rounded text-sm font-normal py-0.75 px-1.5 font-mono inline-block border-1 border-gray-200">
    4xx
  </span>
  {
    " error codes you may encounter while working with the Knock API. We also provide additional context on how to resolve them."
  }
</span>

<ErrorExample
  title="actor_missing"
  description="You called a workflow with an actor that has not yet been identified in Knock. To resolve, identify the actor prior to passing their ID in a workflow trigger."
/>

<ErrorExample
  title="api_key_expired"
  description="Your API key has expired. You can regenerate one on the developers page of the Knock dashboard."
/>

<ErrorExample
  title="api_key_missing"
  description="The API key you provided is invalid."
/>

<ErrorExample
  title="authentication_required"
  description="This endpoint requires authentication. Check the Authentication section of this API reference for more information."
/>

<ErrorExample
  title="channel_invalid"
  description="The channel you supplied in this request is invalid. A common cause of this error is that the channel you're referencing has not yet been configured in the current environment."
/>

<ErrorExample
  title="incorrect_token_type"
  description="You cannot call this endpoint with this token."
/>

<ErrorExample
  title="invalid_params"
  description="The parameters supplied in your request were invalid. Check the payload you're sending to Knock to make sure it's valid."
/>

<ErrorExample
  title="invalid_user_token"
  description="The user token supplied is invalid."
/>

<ErrorExample
  title="missing_jwt_signing_key"
  description={
    <p>
      <span>
        Your request needs a JWT signing key. You can learn more about JWT
        signing keys in our{" "}
      </span>
      <a
        href="/client-integration/authenticating-users"
        className="text-brand underline"
      >
        client authentication docs.
      </a>
    </p>
  }
/>

<ErrorExample
  title="missing_user_token"
  description={
    <p>
      This environment requires that you supply a `X-Knock-User-Token` header
      when using a public API key. You can learn more in our{" "}
      <a
        href="/client-integration/authenticating-users"
        className="text-brand underline"
      >
        client authentication docs.
      </a>
    </p>
  }
/>

<ErrorExample
  title="workflow_inactive"
  description={
    <p>
      The workflow you attempted to invoke is marked with an inactive{" "}
      <a
        href="/concepts/workflows#workflow-status"
        className="text-brand underline"
      >
        status
      </a>
      . To resolve this error, activate the workflow on its page in the dashboard.
    </p>
  }
/>

<ErrorExample
  title="workflow_missing"
  description="The workflow you attempted to invoke could not be found. To resolve this error, confirm that you're calling the correct environment and that your workflow has been committed to it."
/>

</div>
</Section>

<Section title="Workflows" slug="workflows">
<ContentColumn>

A [Workflow](/concepts/workflows) 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 `trigger` call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)

</ContentColumn>
<ExampleColumn>
<Endpoints>
  <Endpoint
    name="trigger-workflow"
    method="POST"
    path="/workflows/:key/trigger"
    withLink
  />
  <Endpoint
    name="cancel-workflow"
    method="POST"
    path="/workflows/:key/cancel"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section isIdempotent title="Triggering a workflow" slug="trigger-workflow">
<ContentColumn>

Invokes the workflow with the given key for the given set of recipients. Each recipient will have a workflow run triggered for them against the latest committed version of the workflow in the environment.

Read more about [triggering a workflow](/send-notifications/triggering-workflows).

This endpoint will return errors in the following cases:

- The workflow does not exist, or has not been committed to the environment
- The workflow's [status](/concepts/workflows#workflow-status) is set to inactive
- The trigger data does not match the schema defined for the workflow ([learn more](/developer-tools/validating-trigger-data))

### Endpoint

<Endpoint method="POST" path="/workflows/:key/trigger" />

### Rate limit

<RateLimit tier={5} />

### Payload size limit

The workflow trigger endpoint enforces the following payload size limits:

- The `data` payload must be no more than `10MB`
- The `recipients` list must not exceed 1000 entries

### Path parameters

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="The key of the workflow to call"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="recipients"
    type="RecipientIdentifier[] (required)"
    description="A list of user identifiers, object references, or inline recipient definitions to run this workflow for"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="actor"
    type="RecipientIdentifier (optional)"
    description="An identifier of who or what performed this action"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="cancellation_key"
    type="string (optional)"
    description="The key to use for canceling the workflow"
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="The id of the tenant that this workflow run should be associated with"
  />
  <Attribute
    name="data"
    type="object (optional)"
    description="A set of key-value pairs to pass to the workflow trigger"
  />
</Attributes>

### Returns

<Attributes>
  <Attribute
    name="workflow_run_id"
    type="string"
    description="A unique UUID of this workflow run"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="workflows.trigger" title="Trigger a workflow" />

```json title="Response"
{
  "workflow_run_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

</ExampleColumn>
</Section>

<Section title="Triggering a workflow with inline identifications" slug="trigger-workflow-inline-identify">
<ContentColumn>

In the `recipients` and `actor` fields in a trigger call, you can optionally include maps of properties describing a user or an object. These can be properties describing a brand new user/object, or properties describing an update to an existing one. When this data is present in a workflow trigger, Knock will persist it as part of processing the workflow. This is comparable to direct calls to the [identify user](#identify-user) or [set object](#set-object) APIs.

Each recipient and actor must have an `id` field set in addition to other properties (e.g. email, name, or phone number).

See our guides on inline identification [for users](/managing-recipients/identifying-recipients#inline-identifying-recipients) and [for objects](/concepts/objects#3-set-objects-inline) for more details on this use case.

### Endpoint

<Endpoint method="POST" path="/workflows/:key/trigger" />

### Rate limit

<RateLimit tier={5} />

### Payload size limit

The workflow trigger endpoint enforces the following payload size limits:

- The `data` payload must be no more than `10MB`
- The `recipients` list must not exceed 1000 entries

### Path parameters

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="The key of the workflow to call"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="recipients"
    type="Recipient[] (required)"
    description="A list of maps of properties describing a user or an object to identify in Knock and trigger this workflow for"
  />
  <Attribute
    name="actor"
    type="Recipient (optional)"
    description="A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action"
  />
  <Attribute
    name="cancellation_key"
    type="string (optional)"
    description="The key to use for canceling the workflow"
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="The id of the tenant that this workflow run should be associated with"
  />
  <Attribute
    name="data"
    type="object (optional)"
    description="A set of key-value pairs to pass to the trigger call"
  />
</Attributes>

### Returns

<Attributes>
  <Attribute
    name="workflow_run_id"
    type="string"
    description="A unique UUID of this workflow run"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="workflows.trigger-with-identification"
  title="Trigger a workflow with inline identifications"
/>

```json title="Response"
{
  "workflow_run_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

</ExampleColumn>
</Section>

<Section title="Canceling workflows" slug="cancel-workflow">
<ContentColumn>

Cancel a delayed workflow for one or more recipients.

[Read more about canceling workflows](/send-notifications/canceling-workflows).

### Endpoint

<Endpoint method="POST" path="/workflows/:key/cancel" />

### Rate limit

<RateLimit tier={5} />

### Payload size limit

The workflow cancellation endpoint enforces the following payload size limits:

- The `recipients` list must not exceed 1000 entries

### Path parameters

<Attributes>
  <Attribute name="key" type="string" description="The key of the workflow" />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="cancellation_key"
    type="string"
    description="The cancellation key unique to the trigger call"
  />
  <Attribute
    name="recipients"
    type="RecipientIdentifier[]"
    description="An optional list of user ids or object references to cancel the workflow for"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
</Attributes>

### Returns

`204`, with empty content.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="workflows.cancel" title="Cancel a workflow" />

</ExampleColumn>
</Section>

<Section title="Messages" slug="messages">
<ContentColumn>

A message is a notification delivered on a particular channel to a user.

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The unique ID of this message"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The ID of the channel through which this message was delivered"
  />
  <Attribute
    name="recipient"
    type="RecipientIdentifier"
    description="The ID of the user who received the message. If the recipient is an object, the result will be an object containing its id and collection"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="actors"
    type="RecipientIdentifier[]"
    description="One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a batch."
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="workflow"
    type="string"
    description="The key of the workflow that this message was generated from"
  />
  <Attribute
    name="tenant"
    type="string"
    description="The ID of the tenant that this message belongs to"
  />
  <Attribute
    name="status"
    type="string"
    description="The delivery status for the message. One of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`, `bounced`."
  />
  <Attribute
    name="engagement_statuses"
    type="string[]"
    description="One or more engagement statuses for the message. Each engagement status can be one of `seen`, `read`, `interacted`, `link_clicked`, or `archived`."
  />
  <Attribute
    name="seen_at"
    type="string (optional)"
    description="When the message was last seen"
  />
  <Attribute
    name="read_at"
    type="string (optional)"
    description="When the message was last read"
  />
  <Attribute
    name="interacted_at"
    type="string (optional)"
    description="When the message was last interacted with"
  />
  <Attribute
    name="link_clicked_at"
    type="string (optional)"
    description="When a message link was last clicked"
  />
  <Attribute
    name="archived_at"
    type="string (optional)"
    description="When the message was archived"
  />
  <Attribute
    name="inserted_at"
    type="string"
    description="When the message was created"
  />
  <Attribute
    name="updated_at"
    type="string"
    description="When the message was last updated"
  />
  <Attribute
    name="source"
    type="object"
    description="The workflow which is the message source"
  />
  <Attribute
    name="data"
    type="object"
    description="Data from the activities linked to the message"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint method="GET" path="/messages" name="list-messages" withLink />
  <Endpoint method="GET" path="/messages/:id" name="get-a-message" withLink />
  <Endpoint
    method="GET"
    path="/messages/:id/events"
    name="get-message-events"
    withLink
  />
  <Endpoint
    method="GET"
    path="/messages/:id/activities"
    name="get-message-activities"
    withLink
  />
  <Endpoint
    method="GET"
    path="/messages/:id/content"
    name="get-message-content"
    withLink
  />
  <Endpoint
    method="GET"
    path="/messages/batch/content"
    name="batch-get-message-content"
    withLink
  />
  <Endpoint
    method="GET"
    path="/messages/:id/delivery_logs"
    name="get-message-delivery-logs"
    withLink
  />
  <Endpoint
    method="PUT"
    path="/messages/:id/:status"
    name="update-message-status"
    withLink
  />
  <Endpoint
    method="DELETE"
    path="/messages/:id/:status"
    name="undo-message-status"
    withLink
  />
  <Endpoint
    method="POST"
    path="/messages/batch/:status"
    name="batch-update-message-status"
    withLink
  />
  <Endpoint
    method="POST"
    path="/channels/:id/messages/bulk/:status"
    name="bulk-update-channel-message-status"
    withLink
  />
</Endpoints>

```json title="Message object"
{
  "__typename": "Message",
  "id": "1rjI9XBgWQ6EUA3D3Ul3VjUimOD",
  "channel_id": "0bfd9f86-56b0-41f0-ade3-dc5cc6a69bb8",
  "recipient": "user_12345",
  "actors": ["user_12345"],
  "workflow": "merged-changes",
  "tenant": null,
  "status": "delivered",
  "engagement_statuses": ["read", "interacted"],
  "seen_at": null,
  "read_at": "2021-05-11T00:00:00.00Z",
  "interacted_at": "2021-05-11T00:00:00.00Z",
  "link_clicked_at": null,
  "archived_at": null,
  "inserted_at": "2021-03-05T12:00:00Z",
  "updated_at": "2021-03-05T12:00:00Z",
  "source": {
    "__typename": "WorkflowSource",
    "key": "merged-changes",
    "version_id": "7251cd3f-0028-4d1a-9466-ee79522ba3de",
    "categories": ["reminders"]
  },
  "data": {
    "foo": "bar"
  },
  "metadata": {
    "external_id": "external_id_from_provider"
  }
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Listing messages" slug="list-messages">
<ContentColumn>

Returns a paginated list of messages.

### Endpoint

<Endpoint method="GET" path="/messages" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Messages outside the account's retention window will not be included in the results.

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="source"
    type="string (optional)"
    description="Limits the results to only items of the source workflow"
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="Limits the results to items with the corresponding tenant, or where the tenant is empty"
  />
  <Attribute
    name="status"
    type="string[] (optional)"
    description="One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es)."
  />
  <Attribute
    name="engagement_status"
    type="string[] (optional)"
    description="One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es)."
  />
  <Attribute
    name="channel_id"
    type="string (optional)"
    description="Limits the results to only items that belong to the channel"
  />
  <Attribute
    name="message_ids[]"
    type="string[] (optional)"
    description="Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query."
  />
  <Attribute
    name="workflow_categories"
    type="string[] (optional)"
    description="Limits the results to only items related to any of the provided categories"
  />
  <Attribute
    name="workflow_run_id"
    type="string (optional)"
    description="Limits the results to messages triggered by the top-level workflow run ID"
  />
  <Attribute
    name="workflow_recipient_run_id"
    type="string (optional)"
    description="Limits the results to messages for a specific recipient's workflow run"
  />
  <Attribute
    name="trigger_data"
    type="JSON string (optional)"
    description="Limits the results to only items that were generated with the given data"
    nameSlug="#trigger-data-filtering"
  />
  <Attribute
    name="inserted_at.gt"
    type="datetime (optional)"
    description="Retrieves messages inserted after the given date"
  />
  <Attribute
    name="inserted_at.gte"
    type="datetime (optional)"
    description="Retrieves messages inserted after or equal to the given date"
  />
  <Attribute
    name="inserted_at.lt"
    type="datetime (optional)"
    description="Retrieves messages inserted before the given date"
  />
  <Attribute
    name="inserted_at.lte"
    type="datetime (optional)"
    description="Retrieves messages inserted before or equal to the given date"
  />
</Attributes>

### Returns

A paginated list of Message records

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="messages.list" title="List messages" />

```json title="Response"
{
  "items": [
    {
      "__typename": "Message",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "1rjI9XBgWQ6EUA3D3Ul3VjUimOD",
      "channel_id": "0bfd9f86-56b0-41f0-ade3-dc5cc6a69bb8",
      "recipient": {
        "id": "project_1",
        "collection": "projects"
      },
      "actors": [],
      "workflow": "merged-changes",
      "tenant": null,
      "status": "delivered",
      "engagement_statuses": ["read", "interacted"],
      "seen_at": null,
      "read_at": "2021-05-11T00:00:00.00Z",
      "interacted_at": "2021-05-11T00:00:00.00Z",
      "link_clicked_at": null,
      "archived_at": null,
      "inserted_at": "2021-03-05T12:00:00Z",
      "updated_at": "2021-03-05T12:00:00Z",
      "source": {
        "__typename": "WorkflowSource",
        "key": "merged-changes",
        "version_id": "7251cd3f-0028-4d1a-9466-ee79522ba3de",
        "categories": ["reminders"]
      },
      "data": {
        "foo": "bar"
      },
      "metadata": {
        "external_id": "external_id_from_provider"
      }
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Fetching a message" slug="get-a-message">
<ContentColumn>

Retrieve a message by the id.

### Endpoint

<Endpoint method="GET" path="/messages/:id" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
</Attributes>

### Returns

A Message

</ContentColumn>

<ExampleColumn>
  <MultiLangCodeBlock snippet="messages.get" title="Get a message" />
</ExampleColumn>

</Section>

<Section isRetentionSubject title="Events" slug="get-message-events">
<ContentColumn>

Returns a paginated list of events for a message.

### Endpoint

<Endpoint method="GET" path="/messages/:id/events" />

### Rate limit

<RateLimit tier={3} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
</Attributes>

### Returns

A paginated list of MessageEvent records

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="messages.getEvents" title="Get message events" />

```json title="Response"
{
  "items": [
    {
      "__typename": "MessageEvent",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "25cQpkVBUTbzKKug0qVEDqcAJxm",
      "environment_id": "a49e3beb-f654-4f2f-8963-f69cc1f7e6dc",
      "recipient": "e62cbb03-86a0-47d6-84fe-f49981906267",
      "data": {},
      "type": "enqueued",
      "inserted_at": "2021-04-06T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Activities" slug="get-message-activities">
<ContentColumn>

Returns a paginated list of activities associated with the message. Note: for non batched messages this will always return a single activity. For messages produced after a batch step, this will contain one or more activities.

### Endpoint

<Endpoint method="GET" path="/messages/:id/activities" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="trigger_data"
    type="JSON string (optional)"
    description="Limits the results to only items that were generated with the given data"
    nameSlug="#trigger-data-filtering"
  />
</Attributes>

### Returns

A paginated list of Activity records

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="messages.getActivities"
  title="Get message activities"
/>

```json title="Response"
{
  "items": [
    {
      "__typename": "Activity",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "25cQpkVBUTbzKKug0qVEDqcAJxm",
      "data": {
        "notification_payload": "foobar"
      },
      "actor": {
        "__typename": "User",
        "id": "7b553fc3-eb65-4ad8-8836-d1224dad703b",
        "created_at": "2022-04-07T12:00:00.00Z",
        "email": "actor@example.com",
        "name": "Actor",
        "updated_at": "2022-04-07T12:00:00.00Z"
      },
      "recipient": {
        "__typename": "Object",
        "id": "f7a84d87-7b9e-4128-82a8-cde38593817f",
        "collection": "projects",
        "properties": {
          "name": "Project 1"
        },
        "created_at": "2022-04-07T12:00:00.00Z",
        "updated_at": "2022-04-07T12:00:00.00Z"
      },
      "inserted_at": "2021-04-06T12:00:00Z",
      "updated_at": "2021-04-06T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Message content" slug="get-message-content">
<ContentColumn>

Retrieves the contents of a message, as generated and sent to the end provider.

### Endpoint

<Endpoint method="GET" path="/messages/:id/content" />

### Rate limit

<RateLimit tier={3} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
</Attributes>

### Returns

A `MessageContent` object.

**Note: the `data` attribute of the `MessageContent` payload will vary based on the type
of message being sent (email, chat, in-app feed, sms, and push).**

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="messages.getContent" title="Get message content" />

```json title="Response"
{
  "__typename": "MessageContent",
  "id": "264os2yt574e1T3jblzjbh7Qa69",
  "data": {
    "bcc": "bcc@example.com",
    "cc": "cc@example.com",
    "from": {
      "email": "info-app@example.com",
      "name": "Example App"
    },
    "html_body": "<p>example</p>",
    "reply_to": "reply-to@example.com",
    "subject": "Example Notification",
    "text_body": "example",
    "to": "user@example.com"
  },
  "inserted_at": "2021-04-06T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Batch message content" slug="batch-get-message-content">
<ContentColumn>

Retrieves the contents of a list of messages, as generated and sent to the end provider.

### Endpoint

<Endpoint method="GET" path="/messages/batch/content" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Query parameters

<Attributes>
  <Attribute
    name="message_ids[]"
    type="string[]"
    description="The IDs of the messages (max 25)"
  />
</Attributes>

### Returns

A list of `MessageContent` objects for the provided message IDs.

**Note: the `data` attribute of the `MessageContent` payload will vary based on the type
of message being sent (email, chat, in-app feed, sms, and push).**

</ContentColumn>
<ExampleColumn>

```json title="Response"
[
  {
    "__typename": "MessageContent",
    "id": "264os2yt574e1T3jblzjbh7Qa69",
    "data": {
      "bcc": "bcc@example.com",
      "cc": "cc@example.com",
      "from": {
        "email": "info-app@example.com",
        "name": "Example App"
      },
      "html_body": "<p>example</p>",
      "reply_to": "reply-to@example.com",
      "subject": "Example Notification",
      "text_body": "example",
      "to": "user@example.com"
    },
    "inserted_at": "2024-04-06T12:00:00Z"
  },
  {
    "__typename": "MessageContent",
    "id": "2iQYdsKFjfIJfXGOGcHi1UOjLMA",
    "data": {
      "bcc": "bcc@example.com",
      "cc": "cc@example.com",
      "from": {
        "email": "info-app@example.com",
        "name": "Example App"
      },
      "html_body": "<p>example</p>",
      "reply_to": "reply-to@example.com",
      "subject": "Example Notification",
      "text_body": "example",
      "to": "user@example.com"
    },
    "inserted_at": "2024-05-09T10:29:00Z"
  }
]
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Delivery logs" slug="get-message-delivery-logs">
<ContentColumn>

Retrieves the delivery logs of a message, generated while sending and checking the delivery status of the message sent to an end provider. Note: for in-app channels, the delivery logs will always be an empty list.

### Endpoint

<Endpoint method="GET" path="/messages/:id/delivery_logs" />

### Rate limit

<RateLimit tier={3} />

### Data retention rule

Returns a `404 Not Found` error for a message outside the account's retention window.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before"
  />
</Attributes>

### Returns

A paginated list of `MessageDeliveryLog`.

**Note**: the `request` and `response` attributes of the MessageDeliveryLog payload will vary depending on the provider.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "items": [
    {
      "__typename": "MessageDeliveryLog",
      "environment_id": "0b94230b-1eef-4627-9dd5-6ab67b0006b4",
      "id": "2KYa5b8ptmGEr1J0uX0IcBlC7OE",
      "inserted_at": "2023-01-19T18:43:07.994259Z",
      "request": {
        "body": {},
        "headers": {
          "Content-Type": "application/json"
        },
        "host": "https://api.postmarkapp.com",
        "method": "POST",
        "path": "/email",
        "query": null
      },
      "response": {
        "body": {},
        "headers": {
          "content-type": "application/json; charset=utf-8"
        },
        "status": 200
      },
      "service_name": "Postmark"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Updating a message status" slug="update-message-status">
<ContentColumn>

Marks the given message with the provided `status`, recording an event in the process. Note that message engagement statuses are [mutually inclusive](/send-notifications/message-statuses#engagement-status); a message can have zero, one, or multiple statuses.

### Endpoint

<Endpoint method="PUT" path="/messages/:id/:status" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
  <Attribute
    name="status"
    type="enum"
    description="One of `seen`, `read`, `interacted`, `archived`"
  />
  <Attribute
    name="metadata"
    type="object"
    description="Additional metadata to be set. Only applicable for `interacted` status updates. Cannot include more than 5 key-value pairs, must not contain nested data."
  />
</Attributes>

### Returns

A Message.

</ContentColumn>
</Section>

<Section title="Undoing a message status change" slug="undo-message-status">
<ContentColumn>

Un-marks the given `status` on a message, recording an event in the process. Note that message engagement statuses are [mutually inclusive](/send-notifications/message-statuses#engagement-status); a message can have zero, one, or multiple statuses.

### Endpoint

<Endpoint method="DELETE" path="/messages/:id/:status" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the message" />
  <Attribute
    name="status"
    type="enum"
    description="One of `seen`, `read`, `interacted`, `archived`"
  />
</Attributes>

### Returns

A Message.

</ContentColumn>
</Section>

<Section title="Batch changing message statuses" slug="batch-update-message-status">
<ContentColumn>

Multiple messages can be changed at once using the batch API, where all message ids given in will have their statuses changed.

### Endpoint

<Endpoint method="POST" path="/messages/batch/:status" />

### Rate limit

<RateLimit tier={3} />

### Batch rate limit

<RateLimit isBatch tier={1} />

<div className="mt-6">
  <Callout
    emoji="⚠️"
    text={
      <>
        <strong>
          Knock scopes this batch rate limit by{" "}
          <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
            message_ids
          </code>{" "}
          and{" "}
          <code style={{ fontWeight: 600, backgroundColor: "inherit" }}>
            status
          </code>
          .
        </strong>{" "}
        This allows for 1 update per second per message per status.
      </>
    }
  />
</div>

### Path parameters

<Attributes>
  <Attribute
    name="status"
    type="enum"
    description="One of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="message_ids"
    type="string[]"
    description="A list of one or more message IDs"
  />
  <Attribute
    name="metadata"
    type="object"
    description="Additional metadata to be set for all messages in the batch. Only applicable for `interacted` status updates. Cannot include more than 5 key-value pairs, must not contain nested data."
  />
</Attributes>

### Returns

A list of Messages that were mutated during the call.

</ContentColumn>
</Section>

<Section isRetentionSubject title="Bulk changing message statuses in a channel" slug="bulk-update-channel-message-status">
<ContentColumn>

Apply the given `status` to a set of messages for the given channel. Will modify all valid messages, or a subset based on the filters provided.

Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint method="POST" path="/channels/:id/messages/bulk/:status" />

### Rate limit

<RateLimit tier={2} />

### Data retention rule

For in-app channels, messages can be updated indefinitely via this operation. For all other channel types, messages outside the account's retention window will not be updated as part of this operation.

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The ID of a channel that you wish to modify messages under"
  />
  <Attribute
    name="status"
    type="enum"
    description="One of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="user_ids"
    type="string[] (optional)"
    description="Scope the bulk update to one or more users"
  />
  <Attribute
    name="tenants"
    type="string[] (optional)"
    description="A list of one or more tenants to match"
  />
  <Attribute
    name="has_tenant"
    type="boolean (optional)"
    description="When set to false, will only return messages that do not have a tenant associated"
  />
  <Attribute
    name="workflows"
    type="string[] (optional)"
    description="A list of one or more workflow keys to match"
  />
  <Attribute
    name="older_than"
    type="string (optional)"
    description="An ISO-8601 timestamp to find messages created before"
  />
  <Attribute
    name="newer_than"
    type="string (optional)"
    description="An ISO-8601 timestamp to find messages created after"
  />
  <Attribute
    name="delivery_status"
    type="enum (optional)"
    description="Limit messages to one of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`"
  />
  <Attribute
    name="engagement_status"
    type="enum (optional)"
    description="Limit messages to one of `seen`, `unseen`, `read`, `unread`, `archived`, `unarchived`, `interacted`, `link_clicked`"
  />
</Attributes>

### Returns

A `BulkOperation`

</ContentColumn>

<ExampleColumn>

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "messages.<status>",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Feeds" slug="feeds">
<ContentColumn>

A feed exposes the messages delivered to an in-app feed channel, formatted specially to be consumed
in a notification feed.

A feed will always return a list of `FeedItems`, which are pointers to a message delivered and contain
all of the information needed in order to render an item within a notification feed.

**Note: feeds are a specialized form of messages that are designed purely for in-app rendering, and
as such return information that is required on the client to do so**

### Attributes

<Attributes>
  <Attribute
    name="entries"
    type="FeedItem[]"
    description="An ordered list of feed items (most recent first)"
  />
  <Attribute
    name="page_info"
    type="PageInfo"
    description="Pagination information for the items returned"
  />
  <Attribute
    name="vars"
    type="object"
    description="Environment specific account variables"
  />
  <Attribute
    name="meta"
    type="FeedMetadata"
    description="Information about the total unread and unseen items"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    method="GET"
    path="/users/:user_id/feeds/:feed_id"
    name="get-feed"
    withLink
  />
</Endpoints>

```json title="Response"
{
  "entries": [
    {
      "__typename": "FeedItem",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "activities": [
        {
          "__typename": "Activity",
          "actor": {
            "__typename": "User",
            "id": "c121a5ea-8f2c-4c60-ab40-9966047d5bea",
            "created_at": null,
            "updated_at": "2021-05-08T20:40:01.340Z",
            "email": "some-user@knock.app",
            "name": "Some User"
          },
          "data": {
            "dest_environment_name": "Production",
            "src_environment_name": "Development",
            "total_merged": 1
          },
          "id": "1sMtIwNnDIV52a8G8kmymzDVExQ",
          "inserted_at": "2021-05-11T00:50:09.895759Z",
          "recipient": {
            "__typename": "User",
            "id": "c121a5ea-8f2c-4c60-ab40-9966047d5bea",
            "created_at": null,
            "updated_at": "2021-05-08T20:40:01.340Z",
            "email": "some-user@knock.app",
            "name": "Some User"
          },
          "updated_at": "2021-05-11T00:50:09.895759Z"
        }
      ],
      "actors": [
        {
          "__typename": "User",
          "id": "c121a5ea-8f2c-4c60-ab40-9966047d5bea",
          "created_at": null,
          "updated_at": "2021-05-08T20:40:01.340Z",
          "email": "some-user@knock.app",
          "name": "Some User"
        }
      ],
      "blocks": [
        {
          "content": "**{{ actor.name }}** merged {{ total_merged }} {% if total_merged == 1 %} change {% else %} changes {% endif %}\nfrom **{{ src_environment_name }}** into **{{ dest_environment_name }}**.",
          "name": "body",
          "rendered": "<p><strong>The person</strong> merged 1  change \nfrom <strong>Development</strong> into <strong>Production</strong>.</p>",
          "type": "markdown"
        },
        {
          "content": "{{ vars.app_url }}/{{ account_slug }}/commits",
          "name": "action_url",
          "rendered": "https://example.com/thing/commits",
          "type": "text"
        }
      ],
      "data": {
        "dest_environment_name": "Production",
        "src_environment_name": "Development",
        "total_merged": 1
      },
      "id": "1sMtIsRvZtYf86aOfkM2PCpC6Xc",
      "inserted_at": "2021-05-11T00:50:09.904531Z",
      "read_at": "2021-05-13T02:45:28.559124Z",
      "seen_at": "2021-05-11T00:51:43.617550Z",
      "interacted_at": null,
      "link_clicked_at": null,
      "archived_at": null,
      "source": {
        "__typename": "WorkflowSource",
        "key": "merged-changes",
        "version_id": "7251cd3f-0028-4d1a-9466-ee79522ba3de",
        "categories": ["reminders"]
      },
      "tenant": null,
      "total_activities": 1,
      "total_actors": 1,
      "updated_at": "2021-05-13T02:45:28.559863Z"
    }
  ],
  "vars": {
    "app_name": "The app name"
  },
  "meta": {
    "__typename": "FeedMetadata",
    "unread_count": 0,
    "unseen_count": 0
  },
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a feed for user" slug="get-feed">
<ContentColumn>

Retrieves a feed of items in reverse chronological order for a given `user_id` on the given `feed_id`. In the case where the user has not yet been identified within Knock, this endpoint will return an empty feed.

You can customize the response for this endpoint by using [response filters](/integrations/in-app/knock#customizing-api-response-content) to exclude or only include certain properties on your resources.

**Note: if you're making this call from a client-side environment you should be using your publishable key
along with a user token to make this request**

### Endpoint

<Endpoint method="GET" path="/users/:user_id/feeds/:feed_id" />

### Rate limit

<RateLimit tier={2} />

<div className="mt-6">
  <Callout
    emoji="⚠️"
    text={
      <>
        <strong>
          This endpoint's rate limit is always scoped per-user and
          per-environment.
        </strong>{" "}
        This is true even for requests made without a signed user token.
      </>
    }
  />
</div>

### Path parameters

<Attributes>
  <Attribute name="user_id" type="string" description="The ID of the user" />
  <Attribute
    name="feed_id"
    type="string"
    description="The ID of the feed (the channel ID)"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page. Defaults to 50 and the max limit is 200."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="source"
    type="string"
    description="Limits the feed to only items of the source workflow"
  />
  <Attribute
    name="tenant"
    type="string"
    description="Limits the feed to only display items with the corresponding tenant, or where the tenant is empty"
  />
  <Attribute
    name="has_tenant"
    type="boolean"
    description="Scope the feed to display items with or without any tenancy"
  />
  <Attribute
    name="status"
    type="string"
    description="One of `unread`,`read`, `unseen`,`seen`, `all`"
  />
  <Attribute
    name="workflow_categories"
    type="string[]"
    description="Limits the feed to only display items related to any of the provided categories"
  />
  <Attribute
    name="archived"
    type="string"
    description="One of `include`, `exclude`, `only` (defaults to `exclude`)"
  />
  <Attribute
    name="trigger_data"
    type="JSON string"
    description="Limits the results to only items that were generated with the given data"
    nameSlug="#trigger-data-filtering"
  />
  <Attribute
    name="inserted_at.gt"
    type="datetime (optional)"
    description="Filter feed items created after the specified ISO-8601 timestamp (exclusive)"
  />
  <Attribute
    name="inserted_at.gte"
    type="datetime (optional)"
    description="Filter feed items created at or after the specified ISO-8601 timestamp (inclusive)"
  />
  <Attribute
    name="inserted_at.lt"
    type="datetime (optional)"
    description="Filter feed items created before the specified ISO-8601 timestamp (exclusive)"
  />
  <Attribute
    name="inserted_at.lte"
    type="datetime (optional)"
    description="Filter feed items created at or before the specified ISO-8601 timestamp (inclusive)"
  />
</Attributes>

### Returns

A feed response.

</ContentColumn>
</Section>

<Section title="Users" slug="users">
<ContentColumn>

A user represents an individual who may need to receive a notification from Knock. They are always referenced by your internal identifier.

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the user"
  />
  <Attribute name="name" type="string (optional)" description="The full name of the user" />
  <Attribute name="email" type="string (optional)" description="The email of the user" />
  <Attribute name="avatar" type="string (optional)" description="A URL for the avatar of the user" />
  <Attribute name="phone_number" type="string (optional)" description="The phone number of the user to use with SMS channels" />
  <Attribute
    name="locale"
    type="string (optional)"
    description={
      <>
        <span>The locale of the user. Used for </span>
        <a href="/concepts/translations">message localization</a>
        <span>.</span>
      </>
    }
  />
  <Attribute
    name="timezone"
    type="string (optional)"
    description={
      <>
        <span>
          The timezone of the user. Must be a valid{" "}
          <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
            tz database time zone string
          </a>
          . Used for <a href="/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients">
            recurring schedules
          </a> and {""}
          <a href="/designing-workflows/send-windows">
          send windows
          </a>.
        </span>
      </>
    }
  />
  <Attribute
    name="*"
    type="key-value pairs"
    description="Any custom properties"
  />
</Attributes>
</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="identify-user" method="PUT" path="/users/:user_id" withLink />
  <Endpoint name="list-users" method="GET" path="/users" withLink />
  <Endpoint name="get-user" method="GET" path="/users/:user_id" withLink />
  <Endpoint
    name="get-user-messages"
    method="GET"
    path="/users/:user_id/messages"
    withLink
  />
  <Endpoint
    name="delete-user"
    method="DELETE"
    path="/users/:user_id"
    withLink
  />
  <Endpoint
    name="merge-user"
    method="POST"
    path="/users/:user_id/merge"
    withLink
  />
  <Endpoint
    name="bulk-identify-users"
    method="POST"
    path="/users/bulk/identify"
    withLink
  />
  <Endpoint
    name="bulk-delete-users"
    method="POST"
    path="/users/bulk/delete"
    withLink
  />
</Endpoints>

```json title="User object"
{
  "__typename": "User",
  "id": "user_1",
  "name": "User name",
  "email": "user@example.com",
  "foo": "bar",
  "baz": true,
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Identify a user" slug="identify-user">
<ContentColumn>

Identifying a user will create or update a user in Knock, merging the properties given with what we currently have set on the user (if any).

### Endpoint

<Endpoint method="PUT" path="/users/:user_id" />

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier of the user"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="name"
    type="string (optional)"
    description="The name of the user"
  />
  <Attribute
    name="email"
    type="string (optional)"
    description="The email of the user"
  />
  <Attribute
    name="avatar"
    type="string (optional)"
    description="A URL for the avatar of the user"
  />
  <Attribute
    name="phone_number"
    type="string (optional)"
    description="The phone number of the user to use with SMS channels"
  />
  <Attribute
    name="locale"
    type="string (optional)"
    description={
      <>
        <span>The locale of the user. Used for </span>
        <a href="/concepts/translations">message localization</a>
        <span>.</span>
      </>
    }
  />
  <Attribute
    name="timezone"
    type="string (optional)"
    description={
      <>
        <span>
          The timezone of the user. Must be a valid{" "}
          <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
            tz database time zone string
          </a>
          . Used for <a href="/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients">
            recurring schedules
          </a>.
        </span>
      </>
    }
  />
  <Attribute
    name="preferences"
    type="object<string, PreferenceSet> (optional)"
    typeSlug="/reference#preferences"
    description="A set of preferences that determines whether a recipient should receive a particular type of notification."
  />
  <Attribute
    name="channel_data"
    type="object<string, ChannelData> (optional)"
    typeSlug="/reference#channel-data"
    description="Channel-specific information that's needed to deliver a notification to an end provider."
  />
  <Attribute
    name="*"
    type="key-value pairs"
    description="Any custom properties"
  />
</Attributes>

### Returns

A User.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="users.identify" title="Identify a user" />

```json title="Response"
{
  "__typename": "User",
  "id": "user_1",
  "name": "User name",
  "email": "user@example.com",
  "locale": "en",
  "timezone": "America/New_York",
  "foo": "bar",
  "baz": true,
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="List users" slug="list-users">
<ContentColumn>

Lists all non-deleted users for the environment. You can optionally request all preferences associated with a user while listing by passing `include[]=preferences`.

### Endpoint

<Endpoint method="GET" path="/users" />

### Rate limit

<RateLimit tier={4} />

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="include"
    type="string[]"
    description="A list of entities to side load as part of the response. Currently only supports `preferences`."
  />
</Attributes>

### Returns

A paginated list of `User` records.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "User",
      "id": "user_1",
      "name": "User name",
      "email": "user@example.com",
      "foo": "bar",
      "baz": true,
      "created_at": null,
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a user" slug="get-user">
<ContentColumn>

Retrieve a user by their ID, including all properties previously set.

### Endpoint

<Endpoint method="GET" path="/users/:user_id" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier of the user"
  />
</Attributes>

### Returns

A User.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="users.get" title="Get a user" />

```json title="Response"
{
  "__typename": "User",
  "id": "user_1",
  "name": "User name",
  "email": "user@example.com",
  "foo": "bar",
  "baz": true,
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="User messages" slug="get-user-messages">
<ContentColumn>

Retrieve a paginated list of messages for a user. Will return most recent messages first.

### Endpoint

<Endpoint method="GET" path="/users/:id/messages" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Messages outside the account's retention window will not be included in the results.

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The ID of the user" />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="source"
    type="string (optional)"
    description="Limits the results to only items of the source workflow"
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="Limits the results to items with the corresponding tenant, or where the tenant is empty"
  />
  <Attribute
    name="status"
    type="string[] (optional)"
    description="One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es)."
  />
  <Attribute
    name="engagement_status"
    type="string[] (optional)"
    description="One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es)."
  />
  <Attribute
    name="channel_id"
    type="string (optional)"
    description="Limits the results to only items that belong to the channel"
  />
  <Attribute
    name="message_ids[]"
    type="string[] (optional)"
    description="Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query."
  />
  <Attribute
    name="workflow_categories"
    type="string[] (optional)"
    description="Limits the results to only items related to any of the provided categories"
  />
  <Attribute
    name="trigger_data"
    type="JSON string (optional)"
    description="Limits the results to only items that were generated with the given data"
    nameSlug="#trigger-data-filtering"
  />
  <Attribute
    name="inserted_at.gt"
    type="datetime (optional)"
    description="Retrieves messages inserted after the given date"
  />
  <Attribute
    name="inserted_at.gte"
    type="datetime (optional)"
    description="Retrieves messages inserted after or equal to the given date"
  />
  <Attribute
    name="inserted_at.lt"
    type="datetime (optional)"
    description="Retrieves messages inserted before the given date"
  />
  <Attribute
    name="inserted_at.lte"
    type="datetime (optional)"
    description="Retrieves messages inserted before or equal to the given date"
  />
</Attributes>

### Returns

A paginated list of Message records

</ContentColumn>

<ExampleColumn>

<MultiLangCodeBlock snippet="users.messages" title="Get user messages" />

```json title="Response"
{
  "items": [
    {
      "__typename": "Message",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "1rjI9XBgWQ6EUA3D3Ul3VjUimOD",
      "channel_id": "0bfd9f86-56b0-41f0-ade3-dc5cc6a69bb8",
      "recipient": "user_12345",
      "actors": [],
      "workflow": "merged-changes",
      "tenant": null,
      "status": "delivered",
      "engagement_statuses": ["read", "interacted"],
      "seen_at": null,
      "read_at": "2021-05-11T00:00:00.00Z",
      "interacted_at": "2021-05-11T00:00:00.00Z",
      "link_clicked_at": null,
      "archived_at": null,
      "inserted_at": "2021-03-05T12:00:00Z",
      "updated_at": "2021-03-05T12:00:00Z",
      "source": {
        "__typename": "WorkflowSource",
        "key": "merged-changes",
        "version_id": "7251cd3f-0028-4d1a-9466-ee79522ba3de",
        "categories": ["reminders"]
      },
      "data": {
        "foo": "bar"
      },
      "metadata": {
        "external_id": "external_id_from_provider"
      }
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Delete a user" slug="delete-user">
<ContentColumn>

Deletes a user by the id given.

### Endpoint

<Endpoint method="DELETE" path="/users/:user_id" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier of the user"
  />
</Attributes>

### Returns

No response.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="users.delete" title="Delete a user" />

</ExampleColumn>
</Section>

<Section title="Merge users" slug="merge-user">
<ContentColumn>

Merges the two users together, merging the user specified in the `from_user_id` into the `user_id`.

[Read more on how merging works →](/concepts/users#merging-users)

### Endpoint

<Endpoint method="POST" path="/users/:user_id/merge" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier of the user to merge into"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="from_user_id"
    type="string"
    description="Unique identifier of the user to merge from"
  />
</Attributes>

### Returns

The merged `User`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="users.merge" title="Merge a user" />

```json title="Response"
{
  "__typename": "User",
  "id": "user_1",
  "name": "User name",
  "email": "user@example.com",
  "foo": "bar",
  "baz": true,
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Bulk identify users" slug="bulk-identify-users">
<ContentColumn>

Identifies up to 1000 users at a time. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint method="POST" path="/users/bulk/identify" />

### Rate limit

<RateLimit tier={1} />

### Body parameters

<Attributes>
  <Attribute
    name="users"
    type="User[]"
    description="A list of users to upsert"
    typeSlug="#users"
  />
</Attributes>

### Returns

A BulkOperation.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.bulkIdentify"
  title="Bulk identifies users"
/>

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "users.identify",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Bulk delete users" slug="bulk-delete-users">
<ContentColumn>

Deletes up to 1000 users at a time. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint method="POST" path="/users/bulk/delete" />

### Rate limit

<RateLimit tier={1} />

### Body parameters

<Attributes>
  <Attribute
    name="user_ids"
    type="string[]"
    description="Unique identifiers of the users to delete"
  />
</Attributes>

### Returns

A BulkOperation.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="users.bulkDelete" title="Bulk deletes users" />

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "users.delete",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Objects" slug="objects">
<ContentColumn>

An Object represents a resource in your system that you've stored in Knock.

The most common use case for objects is as a store for non-user [channel data](/send-notifications/setting-channel-data)
when sending [Slack notifications](/integrations/slack).

### Attributes

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the object within the collection."
  />
  <Attribute
    name="locale"
    type="string (optional)"
    description={
      <>
        <span>The locale of the object. Used for </span>
        <a href="/concepts/translations">message localization</a>
        <span>.</span>
      </>
    }
  />
  <Attribute
    name="timezone"
    type="string (optional)"
    description={
      <>
        <span>
          The timezone of the object. Must be a valid{" "}
          <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
            tz database time zone string
          </a>
          . Used for <a href="/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients">
            recurring schedules
          </a> and {""}
          <a href="/designing-workflows/send-windows">send windows</a>.
        </span>
      </>
    }
  />
  <Attribute
    name="properties"
    type="object"
    description="An object of key-value pairs for attributes you want to associate with the object. Each collection has its own schema in Knock as
    defined by these properties."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="list-objects"
    method="GET"
    path="/objects/:collection"
    withLink
  />
  <Endpoint
    name="get-object"
    method="GET"
    path="/objects/:collection/:id"
    withLink
  />
  <Endpoint
    name="get-object-messages"
    method="GET"
    path="/objects/:collection/:id/messages"
    withLink
  />
  <Endpoint
    name="set-object"
    method="PUT"
    path="/objects/:collection/:id"
    withLink
  />
  <Endpoint
    name="delete-object"
    method="DELETE"
    path="/objects/:collection/:id"
    withLink
  />
  <Endpoint
    name="bulk-set-objects"
    method="POST"
    path="/objects/:collection/bulk/set"
    withLink
  />
  <Endpoint
    name="bulk-delete-objects"
    method="POST"
    path="/objects/:collection/bulk/delete"
    withLink
  />
</Endpoints>

```json title="Object"
{
  "__typename": "Object",
  "id": "project-123",
  "collection": "projects",
  "properties": {
    "name": "My project"
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="List objects" slug="list-objects">
<ContentColumn>

Lists all objects under a collection. Note: does not validate that the collection exists and contains objects. You can optionally request all preferences associated with an object while listing by passing `include[]=preferences`.

### Endpoint

<Endpoint name="list-objects" method="GET" path="/objects/:collection" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="include"
    type="string[]"
    description="A list of entities to side load as part of the response. Currently only supports `preferences`."
  />
</Attributes>

### Response

Returns a paginated list of `Object` records.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.list"
  title="List objects in a collection"
/>

```json title="Response"
{
  "entries": [
    {
      "__typename": "Object",
      "id": "project-123",
      "collection": "projects",
      "properties": {
        "name": "My project"
      },
      "created_at": null,
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get an object" slug="get-object">
<ContentColumn>

Retrieve an object in a collection by the id.

### Endpoint

<Endpoint name="get-object" method="GET" path="/objects/:collection/:id" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the object within the collection."
  />
</Attributes>

### Response

Returns an `Object`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="objects.get" title="Get an object" />

```json title="Response"
{
  "__typename": "Object",
  "id": "project-123",
  "collection": "projects",
  "properties": {
    "name": "My project"
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section isRetentionSubject title="Object messages" slug="get-object-messages">
<ContentColumn>

Returns a paginated list of messages for an object. Will return newest messages first.

### Endpoint

<Endpoint method="GET" path="/objects/:collection/:id/messages" />

### Rate limit

<RateLimit tier={4} />

### Data retention rule

Messages outside the account's retention window will not be included in the results.

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The collection of the object"
  />
  <Attribute name="id" type="string" description="The ID of the object" />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="source"
    type="string (optional)"
    description="Limits the results to only items of the source workflow"
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="Limits the results to items with the corresponding tenant, or where the tenant is empty"
  />
  <Attribute
    name="status"
    type="string[] (optional)"
    description="One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es)."
  />
  <Attribute
    name="engagement_status"
    type="string[] (optional)"
    description="One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es)."
  />
  <Attribute
    name="channel_id"
    type="string (optional)"
    description="Limits the results to only items that belong to the channel"
  />
  <Attribute
    name="message_ids[]"
    type="string[] (optional)"
    description="Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query."
  />
  <Attribute
    name="workflow_categories"
    type="string[] (optional)"
    description="Limits the results to only items related to any of the provided categories"
  />
  <Attribute
    name="trigger_data"
    type="JSON string (optional)"
    description="Limits the results to only items that were generated with the given data"
    nameSlug="#trigger-data-filtering"
  />
  <Attribute
    name="inserted_at.gt"
    type="datetime (optional)"
    description="Retrieves messages inserted after the given date"
  />
  <Attribute
    name="inserted_at.gte"
    type="datetime (optional)"
    description="Retrieves messages inserted after or equal to the given date"
  />
  <Attribute
    name="inserted_at.lt"
    type="datetime (optional)"
    description="Retrieves messages inserted before the given date"
  />
  <Attribute
    name="inserted_at.lte"
    type="datetime (optional)"
    description="Retrieves messages inserted before or equal to the given date"
  />
</Attributes>

### Returns

A paginated list of Message records

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="objects.messages" title="Get object messages" />

```json title="Response"
{
  "items": [
    {
      "__typename": "Message",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "1rjI9XBgWQ6EUA3D3Ul3VjUimOD",
      "channel_id": "0bfd9f86-56b0-41f0-ade3-dc5cc6a69bb8",
      "recipient": {
        "id": "project_1",
        "collection": "projects"
      },
      "actors": [],
      "workflow": "merged-changes",
      "tenant": null,
      "status": "delivered",
      "engagement_statuses": ["read", "interacted"],
      "seen_at": null,
      "read_at": "2021-05-11T00:00:00.00Z",
      "interacted_at": "2021-05-11T00:00:00.00Z",
      "link_clicked_at": null,
      "archived_at": null,
      "inserted_at": "2021-03-05T12:00:00Z",
      "updated_at": "2021-03-05T12:00:00Z",
      "source": {
        "__typename": "WorkflowSource",
        "key": "merged-changes",
        "version_id": "7251cd3f-0028-4d1a-9466-ee79522ba3de",
        "categories": ["reminders"]
      },
      "data": {
        "foo": "bar"
      },
      "metadata": {
        "external_id": "external_id_from_provider"
      }
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Set an object" slug="set-object">
<ContentColumn>

Sets an object within a collection, performing an upsert operation. Any existing properties will be merged with the incoming properties.

### Endpoint

<Endpoint name="set-object" method="PUT" path="/objects/:collection/:id" />

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the object within the collection."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="locale"
    type="string (optional)"
    description={
      <>
        <span>The locale of the object. Used for </span>
        <a href="/concepts/translations">message localization</a>
        <span>.</span>
      </>
    }
  />
  <Attribute
    name="timezone"
    type="string (optional)"
    description={
      <>
        <span>
          The timezone of the object. Must be a valid{" "}
          <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
            tz database time zone string
          </a>
          . Used for <a href="/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients">
            recurring schedules
          </a> and {""}
          <a href="/designing-workflows/send-windows">send windows</a>.
        </span>
      </>
    }
  />
  <Attribute
    name="preferences"
    type="object<string, PreferenceSet>  (optional)"
    typeSlug="/reference#preferences"
    description="A set of preferences that determines whether a recipient should receive a particular type of notification."
  />
  <Attribute
    name="channel_data"
    type="object<string, ChannelData> (optional)"
    typeSlug="/reference#channel-data"
    description="Channel-specific information that's needed to deliver a notification to an end provider."
  />
  <Attribute
    name="*"
    type="any"
    description="A collection of key value pairs to set as properties for this object."
  />
</Attributes>

### Response

Returns an `Object`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="objects.set" title="Set an object" />

```json title="Response"
{
  "__typename": "Object",
  "id": "project-1",
  "collection": "projects",
  "properties": {
    "name": "My project",
    "total_assets": 10,
    "tags": ["cool", "fun", "project"],
    "locale": "en-US",
    "timezone": "America/New_York"
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Delete an object" slug="delete-object">
<ContentColumn>

Deletes an object from a collection by the id provided.

### Endpoint

<Endpoint
  name="delete-object"
  method="DELETE"
  path="/objects/:collection/:id"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the object within the collection."
  />
</Attributes>

### Response

No response.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock snippet="objects.delete" title="Delete an object" />

</ExampleColumn>
</Section>

<Section title="Bulk set objects in a collection" slug="bulk-set-objects">
<ContentColumn>

Bulk sets up to 1000 objects at a time within a collection. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint
  name="bulk-set-objects"
  method="POST"
  path="/objects/:collection/bulk/set"
/>

### Rate limit

<RateLimit tier={1} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="objects[].id"
    type="string"
    description="The id of the object to set."
  />
  <Attribute
    name="objects[].*"
    type="any"
    description="Key value pairs to set as properties on this object."
  />
</Attributes>

### Response

Returns a `BulkOperation`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.bulkSet"
  title="Bulk set objects in a collection"
/>

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "objects.<collection>.set",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Bulk delete objects in a collection" slug="bulk-delete-objects">
<ContentColumn>

Bulk deletes up to 1000 objects at a time within a collection. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint
  name="bulk-delete-objects"
  method="POST"
  path="/objects/:collection/bulk/delete"
/>

### Rate limit

<RateLimit tier={1} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="object_ids"
    type="string[]"
    description="The ids of the objects to delete within the collection"
  />
</Attributes>

### Response

Returns a `BulkOperation`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.bulkDelete"
  title="Bulk delete objects in a collection"
/>

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "objects.<collection>.delete",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Subscriptions" slug="subscriptions">
<ContentColumn>

A subscription represents the relationship between a recipient (the subscriber) and an object.

### Attributes

<Attributes>
  <Attribute
    name="properties"
    type="object"
    description="An object of key-value pairs for attributes you want to associate with the subscription."
  />
  <Attribute
    name="recipient"
    type="object"
    description="A user or an object associated with this subscription"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="list-subscriptions"
    method="GET"
    path="/objects/:collection/:id/subscriptions"
    withLink
  />
  <Endpoint
    name="get-user-subscriptions"
    method="GET"
    path="/users/:id/subscriptions"
    withLink
  />
  <Endpoint
    name="add-subscriptions"
    method="POST"
    path="/objects/:collection/:id/subscriptions"
    withLink
  />
  <Endpoint
    name="bulk-add-subscriptions"
    method="POST"
    path="/objects/:collection/bulk/subscriptions/add"
    withLink
  />
  <Endpoint
    name="delete-subscriptions"
    method="DELETE"
    path="/objects/:collection/:id/subscriptions"
    withLink
  />
</Endpoints>

```json title="Tenant"
{
  "__typename": "ObjectSubscription",
  "properties": {
    "role": "ADMIN"
  },
  "recipient": {
    "__typename": "User",
    "id": "dnedry",
    "name": "Dennis Nedry",
    "email": "dnedry@ingen.net"
  },
  "inserted_at": "2021-03-05T12:00:00Z",
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="List subscriptions" slug="list-subscriptions">
<ContentColumn>

Lists all subscriptions to an object (the subscribers) or all of the current subscriptions for which the specified object is a recipient, depending on the `mode` given. Defaults to returning subscriber information.

Will return the underlying recipient attached. Note: the object must exist.

### Endpoint

<Endpoint
  name="list-subscriptions"
  method="GET"
  path="/objects/:collection/:id/subscriptions"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="A collection that the object belongs to"
  />
  <Attribute
    name="id"
    type="string"
    description="The unique identifier of the object in the collection"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before"
  />
  <Attribute
    name="mode"
    type="string"
    description='When set to "recipient" will return all of the active subscriptions for which the specified object is a recipient (as a subscriber to other objects), rather than the subscribers of the specified object.'
  />
  <Attribute
    name="objects"
    type="object<string, ObjectRef>"
    description='A collection of ObjectRefs, containing the object collection and id, to filter subscriptions. Filtering by objects will only be enabled when mode is set to "recipient."'
  />
  <Attribute
    name="recipients"
    type="string[] | object<string, RecipientRef>"
    description="A collection of recipient identifiers (user_ids and/or ObjectRefs) to filter subscribers of the object. Filtering by recipients will only be enabled when mode is not set."
  />
</Attributes>

### Response

A paginated list response

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "ObjectSubscription",
      "properties": {
        "role": "ADMIN"
      },
      "recipient": {
        "__typename": "User",
        "id": "dnedry",
        "name": "Dennis Nedry",
        "email": "dnedry@ingen.net"
      },
      "object": {
        "__typename": "Object",
        "collection": "project",
        "id": "project-1",
        "properties": {
          "name": "Project 1"
        }
      },
      "inserted_at": "2021-03-05T12:00:00Z",
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 25
  }
}
```

</ExampleColumn>
</Section>

<Section title="User subscriptions" slug="get-user-subscriptions">
<ContentColumn>

Returns a paginated list of subscriptions for a single user, in descending order.

### Endpoint

<Endpoint
  name="get-recipient-subscriptions"
  method="GET"
  path="/users/:id/subscriptions"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The unique identifier of the User"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="objects"
    type="object<string, ObjectRef>"
    description="A collection of ObjectRefs, containing the object collection and id, to filter subscriptions."
  />
</Attributes>

### Response

A paginated response containing a list of `Subscription` entities.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "ObjectSubscription",
      "properties": {
        "role": "ADMIN"
      },
      "recipient": {
        "__typename": "User",
        "id": "dnedry",
        "name": "Dennis Nedry",
        "email": "dnedry@ingen.net"
      },
      "object": {
        "__typename": "Object",
        "collection": "project",
        "id": "project-1",
        "properties": {
          "name": "Project 1"
        }
      },
      "inserted_at": "2021-03-05T12:00:00Z",
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Add subscriptions" slug="add-subscriptions">
<ContentColumn>

Adds one or more recipients as subscribers to the object by creating subscriptions.

### Endpoint

<Endpoint
  name="add-subscriptions"
  method="POST"
  path="/objects/:collection/:id/subscriptions"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="A collection that the object belongs to"
  />
  <Attribute
    name="id"
    type="string"
    description="The unique identifier of the object in the collection"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="recipients"
    type="RecipientIdentifier[]"
    description="A list of recipient identifiers. You can subscribe up to 100 recipients to an object at a time."
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="properties"
    type="map (optional)"
    description="An optional set of key-value pairs to associate with the subscriptions"
  />
</Attributes>

### Response

A list of created `ObjectSubscription`

</ContentColumn>
<ExampleColumn>

```json title="Request"
{
  "recipients": ["dnedry"],
  "properties": {
    "role": "ADMIN"
  }
}
```

```json title="Response"
[
  {
    "__typename": "ObjectSubscription",
    "properties": {
      "role": "ADMIN"
    },
    "recipient": {
      "__typename": "User",
      "id": "dnedry",
      "name": "Dennis Nedry",
      "email": "dnedry@ingen.net"
    },
    "inserted_at": "2021-03-05T12:00:00Z",
    "updated_at": "2021-03-05T12:00:00Z"
  }
]
```

</ExampleColumn>
</Section>

<Section title="Bulk add subscriptions" slug="bulk-add-subscriptions">
<ContentColumn>

Creates subscriptions for one or more recipients to one or more objects within the specified `collection`. You can create up to 50 recipient subscriptions per object at a time and you can modify up to 100 objects per request, totaling up to 5,000 operations per request.

Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

### Endpoint

<Endpoint
  name="bulk-add-subscriptions"
  method="POST"
  path="/objects/:collection/bulk/subscriptions/add"
/>

### Rate limit

<RateLimit tier={1} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The type of object you are storing in Knock."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="subscriptions"
    type="AddSubscriptionsOp[]"
    description="A list of subscriptions to create. Each entry represents a set of Recipients to subscribe to an Object."
  />
</Attributes>

### Response

A `BulkOperation`.

</ContentColumn>

<ExampleColumn>

```json title="Request body"
{
  "subscriptions": [
    {
      "id": "my-object-1",
      "properties": {
        "foo": "bar",
        "biz": "baz"
      },
      "recipients": ["user-1", "user-2", "user-3"]
    },
    {
      "id": "my-object-2",
      "recipients": [{ "id": "user-3", "email": "user-3@example.com" }]
    }
  ]
}
```

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "objects.<collection>.upsert_subscriptions",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Delete subscriptions" slug="delete-subscriptions">
<ContentColumn>

Removes one or more recipients as subscribers to the object.

### Endpoint

<Endpoint
  name="delete-subscriptions"
  method="DELETE"
  path="/objects/:collection/:id/subscriptions"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="A collection that the object belongs to"
  />
  <Attribute
    name="id"
    type="string"
    description="The unique identifier of the object in the collection"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="recipients"
    type="RecipientIdentifier[]"
    description="A list of recipient identifiers"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
</Attributes>

### Response

A list of deleted `ObjectSubscription`

</ContentColumn>
<ExampleColumn>

```json title="Request"
{
  "recipients": ["dnedry"]
}
```

```json title="Response"
[
  {
    "__typename": "ObjectSubscription",
    "properties": {
      "role": "ADMIN"
    },
    "recipient": {
      "__typename": "User",
      "id": "dnedry",
      "name": "Dennis Nedry",
      "email": "dnedry@ingen.net"
    },
    "inserted_at": "2021-03-05T12:00:00Z",
    "updated_at": "2021-03-05T12:00:00Z"
  }
]
```

</ExampleColumn>
</Section>

<Section title="Preferences" slug="preferences">
<ContentColumn>

A preference determines whether a recipient should receive a particular type of notification. By default
all preferences are opted in unless a preference explicitly opts the recipient out of the notification.

The preference set `:id` can be either `"default"` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).

[Read more about Preferences](/concepts/preferences).

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the preference set"
  />
  <Attribute
    name="workflows"
    type="object"
    description="A set of preferences for workflows, each can resolve to a boolean, to a set of channel types, or to a set of conditions"
  />
  <Attribute
    name="channel_types"
    type="object"
    description="A set of preferences for channel types"
  />
  <Attribute
    name="categories"
    type="object"
    description="A set of preferences for workflow categories, each can resolve to a boolean, to a set of channel types, or to a set of conditions"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="get-all-preferences-user"
    method="GET"
    path="/users/:user_id/preferences"
    withLink
  />
  <Endpoint
    name="get-preferences-user"
    method="GET"
    path="/users/:user_id/preferences/:id"
    withLink
  />
  <Endpoint
    name="set-preferences-user"
    method="PUT"
    path="/users/:user_id/preferences/:id"
    withLink
  />
  <Endpoint
    name="get-all-preferences-object"
    method="GET"
    path="/objects/:collection/:object_id/preferences"
    withLink
  />
  <Endpoint
    name="get-preferences-object"
    method="GET"
    path="/objects/:collection/:object_id/preferences/:id"
    withLink
  />
  <Endpoint
    name="set-preferences-object"
    method="PUT"
    path="/objects/:collection/:object_id/preferences/:id"
    withLink
  />
  <Endpoint
    name="bulk-set-preferences"
    method="POST"
    path="/users/bulk/preferences"
    withLink
  />
</Endpoints>

```json title="PreferenceSet object"
{
  "__typename": "PreferenceSet",
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": true
      }
    }
  },
  "channel_types": {
    "in_app_feed": true,
    "sms": false
  },
  "categories": {
    "park-wide": {
      "channel_types": {
        "sms": false
      }
    }
  }
}
```

</ExampleColumn>
</Section>

<Section title="Listing user preferences" slug="get-all-preferences-user">
<ContentColumn>

Retrieve all preference sets for a user. This endpoint returns a list of preference sets associated with the user.

### Endpoint

<Endpoint
  name="get-all-preferences-user"
  method="GET"
  path="/users/:user_id/preferences"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="Unique identifier for the user"
  />
</Attributes>

### Response

Returns a list of `PreferenceSet` objects.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.listPreferences"
  title="List a user's preferences"
/>

```json title="Response"
[
  {
    "__typename": "PreferenceSet",
    "id": "default",
    "workflows": null,
    "channel_types": {
      "in_app_feed": true,
      "sms": true
    },
    "categories": {
      "park-wide": {
        "sms": false
      }
    }
  },
  {
    "__typename": "PreferenceSet",
    "id": "tenant-1",
    "workflows": {
      "new-comment": {
        "channel_types": {
          "email": false,
          "in_app_feed": true
        }
      }
    },
    "channel_types": {
      "in_app_feed": true,
      "sms": false
    },
    "categories": null
  }
]
```

</ExampleColumn>
</Section>

<Section title="Getting user preferences" slug="get-preferences-user">
<ContentColumn>

Retrieve a user's preference set. Will always return an empty preference set object,
even if it does not currently exist for the user.

### Endpoint

<Endpoint
  name="get-preferences-user"
  method="GET"
  path="/users/:user_id/preferences/:id"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="Unique identifier for the user"
  />
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the preference set"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="tenant"
    type="string"
    description="An optional tenant identifier to supply to return the user's preferences with any tenant defaults applied"
  />
</Attributes>

### Response

Returns a `PreferenceSet`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.getPreferences"
  title="Get a user's preferences"
/>

```json title="Response"
{
  "__typename": "PreferenceSet",
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": true
      }
    }
  },
  "channel_types": {
    "in_app_feed": true,
    "sms": true
  },
  "categories": {
    "park-wide": {
      "channel_types": {
        "sms": false
      }
    }
  }
}
```

</ExampleColumn>
</Section>

<Section title="Setting user preferences" slug="set-preferences-user">
<ContentColumn>

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

If no user exists in the current environment for the given `:user_id`, Knock will create the user entry as part of this request.

The preference set `:id` can be either `"default"` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).

### Endpoint

<Endpoint
  name="set-preferences"
  method="PUT"
  path="/users/:user_id/preferences/:id"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="Unique identifier for the user"
  />
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the preference set"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="channel_types"
    type="object"
    description="A set of channel type preferences"
  />
  <Attribute
    name="workflows"
    type="object"
    description="A set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions"
  />
  <Attribute
    name="categories"
    type="object"
    description="A set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions"
  />
</Attributes>

### Response

Returns a `PreferenceSet`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.setPreferences"
  title="Set a user's preferences"
/>

```json title="Response"
{
  "__typename": "PreferenceSet",
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": true,
        "sms": true
      }
    }
  },
  "channel_types": {
    "in_app_feed": true
  },
  "categories": {
    "park-wide": {
      "sms": false
    }
  }
}
```

</ExampleColumn>
</Section>

<Section title="Listing object preferences" slug="get-all-preferences-object">
<ContentColumn>

Retrieve all preference sets for an object. This endpoint returns a list of preference sets associated with the object.

### Endpoint

<Endpoint
  name="get-all-preferences-object"
  method="GET"
  path="/objects/:collection/:object_id/preferences"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
</Attributes>

### Response

Returns a list of `PreferenceSet` objects.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.listPreferences"
  title="List an object's preferences"
/>

```json title="Response"
[
  {
    "__typename": "PreferenceSet",
    "id": "default",
    "workflows": null,
    "channel_types": {
      "in_app_feed": true,
      "sms": true
    },
    "categories": {
      "park-wide": {
        "sms": false
      }
    }
  },
  {
    "__typename": "PreferenceSet",
    "id": "tenant-1",
    "workflows": {
      "new-comment": {
        "channel_types": {
          "email": true,
          "in_app_feed": false
        }
      }
    },
    "channel_types": {
      "in_app_feed": true,
      "sms": false
    },
    "categories": null
  }
]
```

</ExampleColumn>
</Section>

<Section title="Getting object preferences" slug="get-preferences-object">
<ContentColumn>

Retrieve an object's preference set. Will always return an empty preference set object,
even if it does not currently exist for the object.

### Endpoint

<Endpoint
  name="get-preferences-object"
  method="GET"
  path="/objects/:collection/:object_id/preferences/:id"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the preference set"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="tenant"
    type="string"
    description="An optional tenant identifier to supply to return the user's preferences with any tenant defaults applied"
  />
</Attributes>

### Response

Returns a `PreferenceSet`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.getPreferences"
  title="Get an object's preferences"
/>

```json title="Response"
{
  "__typename": "PreferenceSet",
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": true
      }
    }
  },
  "channel_types": {
    "in_app_feed": true,
    "sms": true
  },
  "categories": {
    "park-wide": {
      "channel_types": {
        "sms": false
      }
    }
  }
}
```

</ExampleColumn>
</Section>

<Section title="Setting object preferences" slug="set-preferences-object">
<ContentColumn>

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

If no object exists in the current environment for the given `:collection` and `:object_id`, Knock will create the object as part of this request.

The preference set `:id` can be either `"default"` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).

### Endpoint

<Endpoint
  name="set-preferences-object"
  method="PUT"
  path="/objects/:collection/:object_id/preferences/:id"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
  <Attribute
    name="id"
    type="string"
    description="Unique identifier for the preference set"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="channel_types"
    type="object"
    description="A set of channel type preferences"
  />
  <Attribute
    name="workflows"
    type="object"
    description="A set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions"
  />
  <Attribute
    name="categories"
    type="object"
    description="A set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions"
  />
</Attributes>

### Response

Returns a `PreferenceSet`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.setPreferences"
  title="Set an object's preferences"
/>

```json title="Response"
{
  "__typename": "PreferenceSet",
  "id": "default",
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": true,
        "sms": true
      }
    }
  },
  "channel_types": {
    "in_app_feed": true
  },
  "categories": {
    "park-wide": {
      "sms": false
    }
  }
}
```

</ExampleColumn>
</Section>

<Section title="Bulk set user preferences" slug="bulk-set-preferences">
<ContentColumn>

Bulk sets the preferences for up to 1,000 users at a time. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

The preference set `:id` can be either `"default"` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).

Please note: This is a destructive operation and will replace any existing users' preferences with the preferences sent.

### Endpoint

<Endpoint
  name="bulk-set-preferences"
  method="POST"
  path="/users/bulk/preferences"
/>

### Rate limit

<RateLimit tier={1} />

### Body parameters

<Attributes>
  <Attribute
    name="user_ids"
    type="string[]"
    description="A list of user ids to set preferences for"
  />
  <Attribute
    name="preferences.id"
    type="string"
    description="The id of the preference set"
  />
  <Attribute
    name="preferences.channel_types"
    type="object"
    description="A set of channel type preferences to set"
  />
  <Attribute
    name="preferences.workflows"
    type="object"
    description="A set of workflow preferences, can be a boolean or an object containing channel type preferences"
  />
  <Attribute
    name="preferences.categories"
    type="object"
    description="A set of categories preferences, can be a boolean or an object containing channel type preferences"
  />
</Attributes>

### Response

Returns a `BulkOperation`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.bulkSetPreferences"
  title="Bulk set many users' preferences"
/>

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 42,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "users.set_preferences",
  "processed_rows": 42,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 42,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Tenants" slug="tenants">
<ContentColumn>

A Tenant represents a grouping with configurable settings that can be applied to a workflow when it's triggered in order to override account-level settings such as branding.

Use tenants when sending a notification to user(s) that you want to configure specific brand elements for, such as a separate organization logo.

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the tenant."
  />
  <Attribute
    name="properties"
    type="object"
    description="An object of key-value pairs for attributes you want to associate with the tenant. Currently only name is accepted as an attribute for tenants."
  />
  <Attribute
    name="settings"
    type="object"
    description="An object of key-value pairs for configurable settings on a tenant. Currently contains a preference_set key for tenant-specific default preferences, as well as a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url. The icon_url and logo_url settings must be a valid image URL with an image MIME type."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="list-tenants" method="GET" path="/tenants" withLink />
  <Endpoint name="get-tenant" method="GET" path="/tenants/:id" withLink />
  <Endpoint name="set-tenant" method="PUT" path="/tenants/:id" withLink />
  <Endpoint name="delete-tenant" method="DELETE" path="/tenants/:id" withLink />
</Endpoints>

```json title="Tenant"
{
  "__typename": "Tenant",
  "id": "tenant-1",
  "properties": {
    "name": "Tenant 1"
  },
  "settings": {
    "branding": {
      "primary_color": "#33FF5B",
      "primary_color_contrast": "#ffffff",
      "logo_url": "https://www.example.com/path-to-logo-asset-url",
      "icon_url": "https://www.example.com/path-to-icon-asset-url"
    },
    "preference_set": null
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="List tenants for environment" slug="list-tenants">
<ContentColumn>

Lists tenants for the environment of the API key

### Endpoint

<Endpoint name="list-tenants" method="GET" path="/tenants" />

### Rate limit

<RateLimit tier={4} />

### Response

Returns a list of `Tenant` objects.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="tenants.list"
  title="List tenants in an environment"
/>

```json title="Response"
{
  "entries": [
    {
      "__typename": "Tenant",
      "id": "tenant-1",
      "properties": {
        "name": "Tenant 1"
      },
      "settings": {
        "branding": {
          "primary_color": "#33FF5B",
          "primary_color_contrast": "#ffffff",
          "logo_url": "https:www.example.com/path-to-logo-asset-url",
          "icon_url": "https:www.example.com/path-to-icon-asset-url"
        },
        "preference_set": null
      },
      "created_at": null,
      "updated_at": "2021-03-05T12:00:00Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50,
    "total_count": 1
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a tenant" slug="get-tenant">
<ContentColumn>

Retrieve a tenant by its id.

### Endpoint

<Endpoint name="get-tenant" method="GET" path="/tenants/:id" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the tenant."
  />
</Attributes>

### Response

Returns a `Tenant`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="tenants.get"
  title="Get tenant in an environment"
/>

```json title="Response"
{
  "__typename": "Tenant",
  "id": "tenant-1",
  "properties": {
    "name": "Tenant 1"
  },
  "settings": {
    "branding": {
      "primary_color": "#33FF5B",
      "primary_color_contrast": "#ffffff",
      "logo_url": "https:www.example.com/path-to-logo-asset-url",
      "icon_url": "https:www.example.com/path-to-icon-asset-url"
    },
    "preference_set": null
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Set a tenant" slug="set-tenant">
<ContentColumn>

Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.

### Endpoint

<Endpoint name="set-tenant" method="PUT" path="/tenants/:id" />

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the tenant."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="name"
    type="string"
    description="The name to set on the tenant's name property."
  />
  <Attribute
    name="settings"
    type="object"
    description="An object of key-value pairs for configurable settings on a tenant. Currently contains a preference_set key for tenant-specific default preferences, as well as a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url. The icon_url and logo_url settings must be a valid image URL with an image MIME type."
/>

</Attributes>

### Response

Returns a `Tenant`.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="tenants.set"
  title="Set tenant in an environment"
/>

```json title="Response"
{
  "__typename": "Tenant",
  "id": "tenant-1",
  "properties": {
    "name": "Tenant 1"
  },
  "settings": {
    "branding": {
      "primary_color": "#33FF5B",
      "primary_color_contrast": "#ffffff",
      "logo_url": "https:www.example.com/path-to-logo-asset-url",
      "icon_url": "https:www.example.com/path-to-icon-asset-url"
    },
    "preference_set": null
  },
  "created_at": null,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Delete a tenant" slug="delete-tenant">
<ContentColumn>

Deletes a tenant by the id provided.

### Endpoint

<Endpoint name="delete-tenant" method="DELETE" path="/tenants/:id" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique identifier for the tenant within the collection."
  />
</Attributes>

### Response

No response.

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="tenants.delete"
  title="Delete tenant from an environment"
/>
</ExampleColumn>
</Section>

<Section title="Schedules" slug="schedules">
<ContentColumn>

A schedule allows you to automatically trigger a workflow at a given time for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

[Learn more about schedules](/concepts/schedules)

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="A unique, Knock generated identifier for the schedule."
  />
  <Attribute
    name="actor"
    type="Recipient | null"
    description="The actor to be referenced on the workflow trigger."
  />
  <Attribute
    name="recipient"
    type="Recipient"
    description="The recipient of the scheduled workflow."
  />
  <Attribute
    name="data"
    type="object | null"
    description="Static data to be passed to the workflow trigger."
  />
  <Attribute
    name="workflow"
    type="string"
    description="The key of the workflow that will be triggered in this schedule."
  />
  <Attribute
    name="tenant"
    type="string | null"
    description="The tenant to be passed to the workflow trigger."
  />
  <Attribute
    name="repeats"
    type="ScheduleRepeat[] | null"
    description="A list of one or more repeat definitions that determine when this schedule should run."
  />
  <Attribute
    name="last_occurrence_at | null"
    type="datetime (optional)"
    description="A datetime string in UTC that indicates when the last run for the schedule happened."
  />
  <Attribute
    name="next_occurrence_at | null"
    type="datetime (optional)"
    description="A datetime string in the recipient's timezone that indicates when the schedule will next run, generated from the repeat rules."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="list-schedules" method="GET" path="/schedules" withLink />
  <Endpoint
    name="get-user-schedules"
    method="GET"
    path="/users/:id/schedules"
    withLink
  />
  <Endpoint
    name="get-object-schedules"
    method="GET"
    path="/objects/:collection/:id/schedules"
    withLink
  />
  <Endpoint name="create-schedules" method="POST" path="/schedules" withLink />
  <Endpoint name="update-schedules" method="PUT" path="/schedules" withLink />
  <Endpoint
    name="delete-schedules"
    method="DELETE"
    path="/schedules"
    withLink
  />
  <Endpoint
    name="bulk-create-schedules"
    method="POST"
    path="/schedules/bulk/create"
    withLink
  />
</Endpoints>

```json title="Schedule"
{
  "__typename": "Schedule",
  "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
  "actor": null,
  "data": {
    "custom_key": "custom_value"
  },
  "last_occurrence_at": "2023-04-17T08:30:00Z",
  "next_occurrence_at": "2023-04-24T08:30:00Z",
  "recipient": {
    "__typename": "User",
    "id": "dnedry",
    "name": "Dennis Nedry",
    "email": "dnedry@ingen.net"
  },
  "repeats": [
    {
      "__typename": "ScheduleRepeat",
      "day_of_month": null,
      "days": ["mon"],
      "frequency": "weekly",
      "hours": 8,
      "interval": 1,
      "minutes": 30
    }
  ],
  "workflow": "some-workflow",
  "tenant": null,
  "inserted_at": "2023-04-23T22:29:17.216686Z",
  "updated_at": "2023-04-23T22:29:17.216686Z"
}
```

</ExampleColumn>
</Section>

<Section title="List schedules" slug="list-schedules">
<ContentColumn>

Returns a paginated list of schedules in descending order.

### Endpoint

<Endpoint name="list-schedules" method="GET" path="/schedules" />

### Rate limit

<RateLimit tier={4} />

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="workflow"
    type="string (required)"
    description="The workflow key to filter schedules for."
  />
  <Attribute
    name="recipients"
    type="string[] | object<string, RecipientRef>"
    description="A collection of recipient identifiers (user_ids and/or ObjectRefs) to filter schedules for."
  />
  <Attribute
    name="tenant"
    type="string"
    description="A tenant identifier to filter schedules for."
  />
</Attributes>

### Response

A paginated response containing a list of `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "Schedule",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
      "actor": null,
      "data": {
        "custom_key": "custom_value"
      },
      "last_occurrence_at": "2023-04-17T08:30:00Z",
      "next_occurrence_at": "2023-04-24T08:30:00Z",
      "recipient": {
        "__typename": "User",
        "id": "dnedry",
        "name": "Dennis Nedry",
        "email": "dnedry@ingen.net"
      },
      "repeats": [
        {
          "__typename": "ScheduleRepeat",
          "day_of_month": null,
          "days": ["mon"],
          "frequency": "weekly",
          "hours": 8,
          "interval": 1,
          "minutes": 30
        }
      ],
      "workflow": "digest-workflow",
      "tenant": null,
      "inserted_at": "2023-04-23T22:29:17.216686Z",
      "updated_at": "2023-04-23T22:29:17.216686Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="User schedules" slug="get-user-schedules">
<ContentColumn>

Returns a paginated list of schedules for a single user, in descending order.

### Endpoint

<Endpoint
  name="get-recipient-schedules"
  method="GET"
  path="/users/:id/schedules"
/>

### Rate limit

<RateLimit tier={4} />

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="workflow"
    type="string (required)"
    description="The workflow key to filter schedules for."
  />
  <Attribute
    name="tenant"
    type="string"
    description="A tenant identifier to filter schedules for."
  />
</Attributes>

### Response

A paginated response containing a list of `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "Schedule",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
      "actor": null,
      "data": {
        "custom_key": "custom_value"
      },
      "last_occurrence_at": "2023-04-17T08:30:00Z",
      "next_occurrence_at": "2023-04-24T08:30:00Z",
      "recipient": {
        "__typename": "User",
        "id": "dnedry",
        "name": "Dennis Nedry",
        "email": "dnedry@ingen.net"
      },
      "repeats": [
        {
          "__typename": "ScheduleRepeat",
          "day_of_month": null,
          "days": ["mon"],
          "frequency": "weekly",
          "hours": 8,
          "interval": 1,
          "minutes": 30
        }
      ],
      "workflow": "digest-workflow",
      "tenant": null,
      "inserted_at": "2023-04-23T22:29:17.216686Z",
      "updated_at": "2023-04-23T22:29:17.216686Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Object schedules" slug="get-object-schedules">
<ContentColumn>

Returns a paginated list of schedules for a single object, in descending order.

### Endpoint

<Endpoint
  name="get-recipient-schedules"
  method="GET"
  path="/objects/:collection/:id/schedules"
/>

### Rate limit

<RateLimit tier={4} />

### Query parameters

<Attributes>
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 50)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `__cursor` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `__cursor` field)"
  />
  <Attribute
    name="workflow"
    type="string (required)"
    description="The workflow key to filter schedules for."
  />
  <Attribute
    name="tenant"
    type="string"
    description="A tenant identifier to filter schedules for."
  />
</Attributes>

### Response

A paginated response containing a list of `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "__typename": "Schedule",
      "__cursor": "g3QAAAABZAACaWRtAAAAGzFzTXRJc1J2WnRZZjg2YU9ma00yUENwQzZYYw==",
      "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
      "actor": null,
      "data": {
        "custom_key": "custom_value"
      },
      "last_occurrence_at": "2023-04-17T08:30:00Z",
      "next_occurrence_at": "2023-04-24T08:30:00Z",
      "recipient": {
        "__typename": "User",
        "id": "dnedry",
        "name": "Dennis Nedry",
        "email": "dnedry@ingen.net"
      },
      "repeats": [
        {
          "__typename": "ScheduleRepeat",
          "day_of_month": null,
          "days": ["mon"],
          "frequency": "weekly",
          "hours": 8,
          "interval": 1,
          "minutes": 30
        }
      ],
      "workflow": "digest-workflow",
      "tenant": null,
      "inserted_at": "2023-04-23T22:29:17.216686Z",
      "updated_at": "2023-04-23T22:29:17.216686Z"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Create schedules" slug="create-schedules">
<ContentColumn>

Creates new schedules for the recipients provided. Up to 100 recipients may be specified in a single schedule creation call. Recipients may be inline-identified during this call.

### Endpoint

<Endpoint name="create-schedules" method="POST" path="/schedules" />

### Rate limit

<RateLimit tier={3} />

### Body parameters

<Attributes>
  <Attribute
    name="recipients"
    type="RecipientIdentifier[]"
    description="A list of recipient identifiers"
    typeSlug="/concepts/recipients#recipientidentifier-definition"
  />
  <Attribute
    name="actor"
    type="Recipient | null"
    description="The actor to be referenced on the workflow trigger for this schedule."
  />
  <Attribute
    name="data"
    type="object | null"
    description="Static data to be passed to the workflow trigger or this schedule."
  />
  <Attribute
    name="workflow"
    type="string"
    description="The key of the workflow that will be triggered in this schedule."
  />
  <Attribute
    name="tenant"
    type="string | null"
    description="The tenant to be passed to the workflow trigger for this schedule."
  />
  <Attribute
    name="repeats"
    type="ScheduleRepeat[] | null"
    description="A list of one or more repeat definitions that determine when this schedule should run."
  />
  <Attribute
    name="scheduled_at"
    type="string"
    description="A UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule."
  />
</Attributes>

### Response

The list of created `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Request (POST to /schedules)"
{
  "recipients": ["dnedry"],
  "workflow": "digest-workflow",
  "data": {
    "custom_key": "custom_value"
  },
  "repeats": [
    {
      "frequency": "weekly",
      "interval": 1,
      "days": ["mon"],
      "hours": 8,
      "minutes": 30
    }
  ],
  "scheduled_at": "2025-04-17T08:30:00Z"
}
```

```json title="Response"
[
  {
    "__typename": "Schedule",
    "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
    "actor": null,
    "data": {
      "custom_key": "custom_value"
    },
    "last_occurrence_at": null,
    "next_occurrence_at": "2025-04-17T08:30:00Z",
    "recipient": {
      "__typename": "User",
      "id": "dnedry",
      "name": "Dennis Nedry",
      "email": "dnedry@ingen.net"
    },
    "repeats": [
      {
        "__typename": "ScheduleRepeat",
        "day_of_month": null,
        "days": ["mon"],
        "frequency": "weekly",
        "hours": 8,
        "interval": 1,
        "minutes": 30
      }
    ],
    "workflow": "digest-workflow",
    "tenant": null,
    "inserted_at": "2024-04-23T22:29:17.216686Z",
    "updated_at": "2024-04-23T22:29:17.216686Z"
  }
]
```

</ExampleColumn>
</Section>

<Section title="Update schedules" slug="update-schedules">
<ContentColumn>

Updates the schedules for the `schedule_ids` given. Can update up to 100 schedules at a time.

### Endpoint

<Endpoint name="update-schedules" method="PUT" path="/schedules" />

### Rate limit

<RateLimit tier={3} />

### Body parameters

<Attributes>
  <Attribute
    name="schedule_ids"
    type="string[]"
    description="A list of schedule ids of the schedules to mutate."
  />
  <Attribute
    name="actor"
    type="Recipient | null"
    description="The actor to be referenced on the workflow trigger for this schedule."
  />
  <Attribute
    name="data"
    type="object | null"
    description="Static data to be passed to the workflow trigger or this schedule."
  />
  <Attribute
    name="tenant"
    type="string | null"
    description="The tenant to be passed to the workflow trigger for this schedule."
  />
  <Attribute
    name="repeats"
    type="ScheduleRepeat[] | null"
    description="A list of one or more repeat definitions that determine when this schedule should run."
  />
  <Attribute
    name="scheduled_at"
    type="string"
    description="A UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule."
  />
</Attributes>

### Response

The list of updated `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Request (PUT to /schedules)"
{
  "schedule_ids": ["2OqXCSJUgbhhgIX3iaPfI3ZOVd9"],
  "data": {
    "custom_key": "custom_value",
    "another_key": "another_value"
  },
  "repeats": [
    {
      "frequency": "weekly",
      "interval": 1,
      "days": ["mon"],
      "hours": 8,
      "minutes": 30
    }
  ]
}
```

```json title="Response"
[
  {
    "__typename": "Schedule",
    "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
    "actor": null,
    "data": {
      "custom_key": "custom_value",
      "another_key": "another_value"
    },
    "next_occurrence_at": "2023-04-17T08:30:00Z",
    "next_occurrence_at": "2023-04-24T08:30:00Z",
    "recipient": {
      "__typename": "User",
      "id": "dnedry",
      "name": "Dennis Nedry",
      "email": "dnedry@ingen.net"
    },
    "repeats": [
      {
        "__typename": "ScheduleRepeat",
        "day_of_month": null,
        "days": ["mon"],
        "frequency": "weekly",
        "hours": 8,
        "interval": 1,
        "minutes": 30
      }
    ],
    "workflow": "digest-workflow",
    "tenant": null,
    "inserted_at": "2023-04-23T22:29:17.216686Z",
    "updated_at": "2023-04-23T22:29:17.216686Z"
  }
]
```

</ExampleColumn>
</Section>

<Section title="Delete schedules" slug="delete-schedules">
<ContentColumn>

Deletes the schedules for the `schedule_ids` given. Can delete up to 100 schedules at a time. Deleting a schedule will cancel its next occurrence immediately. Any running scheduled workflows will not be affected.

### Endpoint

<Endpoint name="delete-schedules" method="DELETE" path="/schedules" />

### Rate limit

<RateLimit tier={3} />

### Body parameters

<Attributes>
  <Attribute
    name="schedule_ids"
    type="string[]"
    description="A list of schedule ids of the schedules to mutate."
  />
</Attributes>

### Response

The list of deleted `Schedule` entities.

</ContentColumn>
<ExampleColumn>

```json title="Request (DELETE to /schedules)"
{
  "schedule_ids": ["2OqXCSJUgbhhgIX3iaPfI3ZOVd9"]
}
```

```json title="Response"
[
  {
    "__typename": "Schedule",
    "id": "2OqXCSJUgbhhgIX3iaPfI3ZOVd9",
    "actor": null,
    "data": {
      "custom_key": "custom_value",
      "another_key": "another_value"
    },
    "next_occurrence_at": "2023-04-24T08:30:00Z",
    "recipient": {
      "__typename": "User",
      "id": "dnedry",
      "name": "Dennis Nedry",
      "email": "dnedry@ingen.net"
    },
    "repeats": [
      {
        "__typename": "ScheduleRepeat",
        "day_of_month": null,
        "days": ["mon"],
        "frequency": "weekly",
        "hours": 8,
        "interval": 1,
        "minutes": 30
      }
    ],
    "workflow": "digest-workflow",
    "tenant": null,
    "inserted_at": "2023-04-23T22:29:17.216686Z",
    "updated_at": "2023-04-23T22:29:17.216686Z"
  }
]
```

</ExampleColumn>
</Section>

<Section title="Bulk create schedules" slug="bulk-create-schedules">
<ContentColumn>

Bulk creates up to 1,000 schedules at a time. Returns a `BulkOperation` that executes the job asynchronously. Progress can be tracked via the [BulkOperation API](#bulk-operations).

**Each schedule provided in the `schedules` list must have a single recipient.** The recipients do not have to be unique across schedules.

This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.

### Endpoint

<Endpoint
  name="bulk-create-schedules"
  method="POST"
  path="/schedules/bulk/create"
/>

### Rate limit

<RateLimit tier={1} />

### Body parameters

<Attributes>
  <Attribute
    name="schedules"
    type="Schedule[]"
    description="A list of schedules to create. Each schedule must have a single recipient. The recipients do not have to be unique."
    typeSlug="/reference#schedules"
  />
</Attributes>

### Response

Returns a `BulkOperation`.

</ContentColumn>
<ExampleColumn>

```json title="Request (POST to /schedules/bulk/create)"
{
  "schedules": [
    {
      "recipient": "dnedry",
      "workflow": "comment-digest",
      "data": {
        "custom_key": "custom_value"
      },
      "repeats": [
        {
          "frequency": "weekly",
          "interval": 1,
          "days": ["mon"],
          "hours": 8,
          "minutes": 30
        }
      ],
      "scheduled_at": "2025-04-17T08:30:00Z",
      "ending_at": "2025-05-24T08:30:00Z",
      "tenant": "acme_corp"
    },
    {
      "recipient": "esattler",
      "workflow": "comment-digest",
      "data": {
        "custom_key": "custom_value"
      },
      "repeats": [
        {
          "frequency": "weekly",
          "interval": 1,
          "days": ["mon"],
          "hours": 8,
          "minutes": 30
        }
      ],
      "scheduled_at": "2025-04-17T08:30:00Z",
      "ending_at": "2025-05-24T08:30:00Z",
      "tenant": "acme_corp"
    }
  ]
}
```

```json title="Response"
{
  "__typename": "BulkOperation",
  "completed_at": "2025-03-05T12:00:27Z",
  "error_count": 0,
  "error_items": [],
  "estimated_total_rows": 872,
  "failed_at": null,
  "id": "8f7e6d5c-4b3a-2d1e-9f8e-7d6c5b4a3210",
  "inserted_at": "2025-03-05T12:00:00Z",
  "name": "schedules.create_schedules",
  "processed_rows": 872,
  "progress_path": "/v1/bulk_operations/8f7e6d5c-4b3a-2d1e-9f8e-7d6c5b4a3210",
  "started_at": "2025-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 872,
  "updated_at": "2025-03-05T12:00:27Z"
}
```

</ExampleColumn>
</Section>

<Section title="Channel data" slug="channel-data">
<ContentColumn>

<a href="/managing-recipients/setting-channel-data">`ChannelData`</a> is channel-specific
information stored on a Knock [user](/reference#users) or [object](/reference#objects)
that's needed to deliver a notification to an end provider.

For a push channel, this includes device-specific tokens that map the recipient to the device they use. For chat apps, such as Slack, this includes the access token used to send
notifications to a customer's Slack channel.

The shape of the `data` payload varies depending on the channel type; you can learn more about channel data schemas [here](/send-notifications/setting-channel-data#provider-data-requirements).

### Attributes

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The UUID of the channel this data belongs to"
  />
  <Attribute
    name="data"
    type="object"
    description="The provider specific channel data"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="get-user-channel-data"
    method="GET"
    path="/users/:user_id/channel_data/:channel_id"
    withLink
  />
  <Endpoint
    name="set-user-channel-data"
    method="PUT"
    path="/users/:user_id/channel_data/:channel_id"
    withLink
  />
  <Endpoint
    name="unset-user-channel-data"
    method="DELETE"
    path="/users/:user_id/channel_data/:channel_id"
    withLink
  />
  <Endpoint
    name="get-object-channel-data"
    method="GET"
    path="/objects/:collection/:object_id/channel_data/:channel_id"
    withLink
  />
  <Endpoint
    name="set-object-channel-data"
    method="PUT"
    path="/objects/:collection/:object_id/channel_data/:channel_id"
    withLink
  />
  <Endpoint
    name="unset-object-channel-data"
    method="DELETE"
    path="/objects/:collection/:object_id/channel_data/:channel_id"
    withLink
  />
</Endpoints>

```json title="ChannelData object"
{
  "__typename": "ChannelData",
  "channel_id": "c2189f43-c732-488a-bfa0-fdf16e145cdf",
  "data": {
    "tokens": ["some-fcm-token"]
  }
}
```

</ExampleColumn>
</Section>

<Section title="Getting user channel data" slug="get-user-channel-data">
<ContentColumn>

Retrieves the channel data for the provided user on the channel specified.

### Endpoint

<Endpoint method="GET" path="/users/:user_id/channel_data/:channel_id" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="The id of the user to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Returns

- `200` with a `ChannelData` object (when found)
- `404` when not found

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.getChannelData"
  title="Get a users channel data"
/>

</ExampleColumn>
</Section>

<Section title="Setting user channel data" slug="set-user-channel-data">
<ContentColumn>

Sets channel data for the user and the channel specified.

If no user exists in the current environment for the given :user_id, Knock will create the user entry as part of this request.

### Endpoint

<Endpoint method="PUT" path="/users/:user_id/channel_data/:channel_id" />

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="The id of the user to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="data"
    type="object"
    description={
      <p>
        The data to set for the specified <code>channel_id</code>. The shape of
        the payload varies depending on the channel. You can learn more about
        channel data schemas{" "}
        <a
          href="/send-notifications/setting-channel-data#provider-data-requirements"
          className="text-brand underline"
        >
          here
        </a>
        .
      </p>
    }
  />
</Attributes>

### Returns

- `200` with a `ChannelData` object (when set)
- `404` when the channel specified cannot be found
- `422` with errors when the data is incorrectly shaped

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.setChannelData"
  title="Set a users channel data"
/>

</ExampleColumn>
</Section>

<Section title="Unsetting user channel data" slug="unset-user-channel-data">
<ContentColumn>

Unsets (removes) channel data for the user and the channel specified.

### Endpoint

<Endpoint method="DELETE" path="/users/:user_id/channel_data/:channel_id" />

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="user_id"
    type="string"
    description="The id of the user to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Returns

- `204` no content
- `404` when the channel specified cannot be found

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="users.unsetChannelData"
  title="Unset a users channel data"
/>

</ExampleColumn>
</Section>

<Section title="Getting object channel data" slug="get-object-channel-data">
<ContentColumn>

Retrieves the channel data for the provided object on the channel specified.

### Endpoint

<Endpoint
  method="GET"
  path="/objects/:collection/:object_id/channel_data/:channel_id"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Returns

- `200` with a `ChannelData` (when found)
- `404` when not found

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.getChannelData"
  title="Get an objects channel data"
/>

</ExampleColumn>
</Section>

<Section title="Setting object channel data" slug="set-object-channel-data">
<ContentColumn>

Sets channel data for the object and the channel specified.

If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request.

### Endpoint

<Endpoint
  method="PUT"
  path="/objects/:collection/:object_id/channel_data/:channel_id"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="data"
    type="object"
    description={
      <p>
        The data to set for the specified <code>channel_id</code>. The shape of
        the payload varies depending on the channel. You can learn more about
        channel data schemas{" "}
        <a
          href="/send-notifications/setting-channel-data#provider-data-requirements"
          className="text-brand underline"
        >
          here
        </a>
        .
      </p>
    }
  />
</Attributes>

### Returns

- `200` with a `ChannelData` object (when set)
- `404` when the channel specified cannot be found
- `422` with errors when the data is incorrectly shaped

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.setChannelData.slack"
  title="Set an object's channel data"
/>

</ExampleColumn>
</Section>

<Section title="Unsetting object channel data" slug="unset-object-channel-data">
<ContentColumn>

Unsets (removes) channel data for the object and the channel specified.

### Endpoint

<Endpoint
  method="DELETE"
  path="/objects/:collection/:object_id/channel_data/:channel_id"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="object_id"
    type="string"
    description="The id of the object to lookup"
  />
  <Attribute
    name="collection"
    type="string"
    description="The parent collection of the object to lookup"
  />
  <Attribute
    name="channel_id"
    type="string"
    description="The id of the Knock channel to lookup"
  />
</Attributes>

### Returns

- `204` no content
- `404` when the channel specified cannot be found

</ContentColumn>
<ExampleColumn>

<MultiLangCodeBlock
  snippet="objects.unsetChannelData"
  title="Unsets an object's channel data"
/>

</ExampleColumn>
</Section>

<Section title="Bulk operations" slug="bulk-operations">
<ContentColumn>

A bulk operation is a set of changes applied across 0 or more records triggered via a call to the Knock API and performed asynchronously. The `BulkOperation` record represents the state of the operation, including recording the number of rows that have been modified during the operation.

Please note here: the `estimated_total_rows` field may have a different value to the `processed_rows` field due to the asynchronous nature of the operation.

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The unique ID of this bulk operation"
  />
  <Attribute
    name="name"
    type="string"
    description="The type of operation being performed"
  />
  <Attribute
    name="estimated_total_rows"
    type="integer"
    description="An approximation of the number of rows that will be mutated in this operation"
  />
  <Attribute
    name="processed_rows"
    type="integer"
    description="The number of the rows that have been handled in this operation, either successfully or in error"
  />
  <Attribute
    name="success_count"
    type="integer"
    description="The number of the rows that have been modified successfully in this operation"
  />
  <Attribute
    name="error_count"
    type="integer"
    description="The number of the rows that errored in this operation"
  />
  <Attribute
    name="error_items"
    type="object[]"
    description="A list of items that errored in this operation, if available"
  />
  <Attribute
    name="status"
    type="enum"
    description="One of `queued`, `processing`, `completed`, `failed`"
  />
  <Attribute
    name="started_at"
    type="string"
    description="An ISO-8601 datetime string for when the operation started processing"
  />
  <Attribute
    name="completed_at"
    type="string"
    description="An ISO-8601 datetime string for when the operation completed processing"
  />
  <Attribute
    name="failed_at"
    type="string"
    description="An ISO-8601 datetime string for when the operation failed processing"
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    method="GET"
    path="/bulk_operations/:id"
    name="bulk-operation-status"
    withLink
  />
</Endpoints>

```json title="BulkOperation object"
{
  "__typename": "BulkOperation",
  "completed_at": "2021-03-05T12:00:00Z",
  "error_count": 1,
  "error_items": [{ "id": "foo", "collection": "bar" }],
  "estimated_total_rows": 342,
  "failed_at": null,
  "id": "50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "inserted_at": "2021-03-05T12:00:00Z",
  "name": "some_operation",
  "processed_rows": 342,
  "progress_path": "/v1/bulk_operations/50d2847b-c738-466a-a3d7-e68e4bb1cedd",
  "started_at": "2021-03-05T12:00:00Z",
  "status": "completed",
  "success_count": 341,
  "updated_at": "2021-03-05T12:00:00Z"
}
```

</ExampleColumn>
</Section>

<Section title="Retrieve a bulk operation" slug="bulk-operation-status">
<ContentColumn>

Retrieve the bulk operation, revealing the current status and the number of rows processed. You can poll this endpoint
to understand when a bulk operation has finished executing (either completed, or failed).

### Endpoint

<Endpoint method="GET" path="/bulk_operations/:id" />

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The ID of a bulk operation to retrieve"
  />
</Attributes>

### Returns

A `BulkOperation`

</ContentColumn>
</Section>

<Section title="Slack" slug="slack">
  <ContentColumn>
  These endpoints handle communication with the Slack API to streamline authentication and data gathering. They are used by [SlackKit](/in-app-ui/react/slack-kit) components and hooks.
  </ContentColumn>

  <ExampleColumn>
    <Endpoints>
      <Endpoint name="slack-auth-check" method="GET" path="/providers/slack/:channel_id/auth_check" withLink/>
      <Endpoint name="slack-channels" method="GET" path="/providers/slack/:channel_id/channels" withLink/>
      <Endpoint name="slack-revoke-access" method="PUT" path="/providers/slack/:channel_id/revoke_access" withLink/>
    </Endpoints>
  </ExampleColumn>
</Section>

<Section title="Slack auth check" slug="slack-auth-check">
  <ContentColumn>
  Get the status of Slack authentication.
  ### Endpoint

<Endpoint
  name="auth_check"
  method="GET"
  path="/providers/slack/:channel_id/auth_check"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Slack channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="access_token_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="access_token_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
</Attributes>

### Returns

- `200` Connection data from the Slack API.
- `403` When no access token is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Connection data success response

{
  "connection": {
    "ok": true,
    "url": "https://jurassicpark.slack.com/",
    "team": "Dino Workspace",
    "user": "alangrant",
    "team_id": "T12345678",
    "user_id": "W12345678"
  }
}
```

```json
// Connection data error response

{
  "connection": {
    "ok": false,
    "error": "invalid_auth"
  }
}
```

```json
// Missing access token error response

{
  "code": "authorization",
  "message": "Access token not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Slack channels" slug="slack-channels">
<ContentColumn>
Get a list of the Slack channels for the access token stored in the given access token object.

### Endpoint

<Endpoint
  name="channels"
  method="GET"
  path="/providers/slack/:channel_id/channels"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Slack channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="access_token_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="access_token_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
  <Attribute
    name="query_options[:option]"
    type="string"
    description="An optional query option passed to Slack. One of `cursor`, `exclude_archived`, `limit`, `team_id`, `types`. 
    See Slack documentation for more information: https://api.slack.com/methods/conversations.list#arg_cursor"
    typeSlug="https://api.slack.com/methods/conversations.list#arg_cursor"
  />
</Attributes>

### Returns

- `200` List of partial data about the Slack channels requested.
- `403` When no access token is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Success response

{
  "slack_channels": [
    {
      "name": "general",
      "id": "CMYK1234",
      "is_private": "false",
      "is_im": "false",
      "context_team_id": ""
    }
  ],
  "next_cursor": ""
}
```

```json
// Missing access token error response

{
  "code": "authorization",
  "message": "Access token not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Slack revoke access" slug="slack-revoke-access">
<ContentColumn>
Revoke an access token from Slack and remove it from the access token object.

### Endpoint

<Endpoint
  name="channels"
  method="PUT"
  path="/providers/slack/:channel_id/revoke_access"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Slack channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="access_token_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="access_token_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
</Attributes>

### Returns

- `200` Success response
- `403` When no access token is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Success response

"ok"
```

```json
// Missing access token error response

{
  "code": "authorization",
  "message": "Access token not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Microsoft Teams" slug="ms-teams">
  <ContentColumn>
  These endpoints handle communication with the Microsoft Graph API to streamline authentication and data gathering. They are used by [TeamsKit](/in-app-ui/react/teams-kit) components and hooks.
  </ContentColumn>

  <ExampleColumn>
    <Endpoints>
      <Endpoint name="ms-teams-auth-check" method="GET" path="/providers/ms-teams/:channel_id/auth_check" withLink/>
      <Endpoint name="ms-teams-teams" method="GET" path="/providers/ms-teams/:channel_id/teams" withLink/>
      <Endpoint name="ms-teams-channels" method="GET" path="/providers/ms-teams/:channel_id/channels" withLink/>
      <Endpoint name="ms-teams-revoke-access" method="PUT" path="/providers/ms-teams/:channel_id/revoke_access" withLink/>
    </Endpoints>
  </ExampleColumn>
</Section>

<Section title="Microsoft Teams auth check" slug="ms-teams-auth-check">
  <ContentColumn>
  Get the status of Microsoft Teams authentication.
  ### Endpoint

<Endpoint
  name="auth_check"
  method="GET"
  path="/providers/ms-teams/:channel_id/auth_check"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Microsoft Teams channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="ms_teams_tenant_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="ms_teams_tenant_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
</Attributes>

### Returns

- `200` Success response
- `403` When no Microsoft Entra tenant ID is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Connection data success response

{
  "connection": {
    "ok": true
  }
}
```

```json
// Connection data error response

{
  "connection": {
    "ok": false,
    "reason": "Knock Object containing Microsoft Teams tenant not found."
  }
}
```

```json
// Missing Microsoft Entra tenant ID error response

{
  "code": "authorization",
  "message": "Microsoft Teams tenant ID not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Microsoft Teams teams" slug="ms-teams-teams">
<ContentColumn>
Get a list of teams belonging to the Microsoft Entra tenant.

### Endpoint

<Endpoint
  name="teams"
  method="GET"
  path="/providers/ms-teams/:channel_id/teams"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Microsoft Teams channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="ms_teams_tenant_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="ms_teams_tenant_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
  <Attribute
    name="query_options[:option]"
    type="string"
    description={
      <>
        An optional query option passed to the Microsoft Graph API. One of{" "}
        <code>$filter</code>, <code>$select</code>, <code>$top</code>,{" "}
        <code>$skiptoken</code>. See the{" "}
        <a
          href="https://learn.microsoft.com/en-us/graph/api/teams-list#optional-query-parameters"
          target="_blank"
        >
          Microsoft Graph API documentation
        </a>{" "}
        for more information.
      </>
    }
  />
</Attributes>

### Returns

- `200` List of teams in the Microsoft Entra tenant.
- `403` When no Microsoft Entra tenant ID is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Success response

{
  "ms_teams_teams": [
    {
      "id": "team-id-1",
      "displayName": "Engineering Team"
    }
  ],
  "skip_token": "token-for-next-page"
}
```

```json
// Missing Microsoft Entra tenant ID error response

{
  "code": "authorization",
  "message": "Microsoft Teams tenant ID not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Microsoft Teams channels" slug="ms-teams-channels">
<ContentColumn>
Get a list of the Microsoft Teams channels within a team. By default, archived and private channels are excluded from the results.

### Endpoint

<Endpoint
  name="channels"
  method="GET"
  path="/providers/ms-teams/:channel_id/channels"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Microsoft Teams channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="ms_teams_tenant_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="ms_teams_tenant_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
  <Attribute
    name="team_id"
    type="string"
    description="The ID of the Microsoft Teams team to list channels from."
  />
  <Attribute
    name="query_options[:option]"
    type="string"
    description={
      <>
        An optional query option passed to the Microsoft Graph API. One of{" "}
        <code>$filter</code>, <code>$select</code>. See the{" "}
        <a
          href="https://learn.microsoft.com/en-us/graph/api/channel-list#optional-query-parameters"
          target="_blank"
        >
          Microsoft Graph API documentation
        </a>{" "}
        for more information.
      </>
    }
  />
</Attributes>

### Returns

- `200` List of Microsoft Teams channels in the specified team.
- `403` When no Microsoft Entra tenant ID is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Success response

{
  "ms_teams_channels": [
    {
      "id": "channel-id-1",
      "displayName": "General"
    }
  ]
}
```

```json
// Missing Microsoft Entra tenant ID error response

{
  "code": "authorization",
  "message": "Microsoft Teams tenant ID not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Microsoft Teams revoke access" slug="ms-teams-revoke-access">
<ContentColumn>
Removes a Microsoft Entra tenant ID from the Microsoft Teams tenant object.

### Endpoint

<Endpoint
  name="channels"
  method="PUT"
  path="/providers/ms-teams/:channel_id/revoke_access"
/>

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="channel_id"
    type="string"
    description="The Knock Microsoft Teams channel ID"
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="ms_teams_tenant_object[object_id]"
    type="string"
    description="ID of the Object or Tenant."
  />
  <Attribute
    name="ms_teams_tenant_object[collection]"
    type="string"
    description="Collection of the Object or Tenant. If Tenant, should be `$tenants`."
  />
</Attributes>

### Returns

- `200` Success response
- `403` When no Microsoft Entra tenant ID is set for the given object.

</ContentColumn>
<ExampleColumn>

```json
// Success response

"ok"
```

```json
// Missing Microsoft Entra tenant ID error response

{
  "code": "authorization",
  "message": "Microsoft Teams tenant ID not set.",
  "status": 403,
  "type": "authentication_error"
}
```

</ExampleColumn>
</Section>

<Section title="Audiences" slug="audiences">
  <ContentColumn>
    <Callout
      emoji="🚧"
      text={
        <>
          Audiences are currently in beta. If you'd like early access, or this is
          blocking your adoption of Knock, please{" "}
          <a href="mailto:support@knock.app?subject=Audiences">get in touch</a>.
        </>
      }
    />

    An [Audience](https://docs.knock.app/concepts/audiences) represents a user segment.

    Use the Audiences API to sync user segments from your data warehouse to Knock. Audiences can be used to target messages or orchestrate workflows via branch and step conditions.

  </ContentColumn>

  <ExampleColumn>
    <Endpoints>
      <Endpoint name="audiences-list" method="GET" path="/audiences/:audience_key/members" withLink/>
      <Endpoint name="audiences-add-members" method="POST" path="/audiences/:audience_key/members" withLink/>
      <Endpoint name="audiences-remove-members" method="DELETE" path="/audiences/:audience_key/members" withLink/>
    </Endpoints>
  </ExampleColumn>
</Section>

<Section title="List audience members" slug="audiences-list-members">
<ContentColumn>
  <Callout
    emoji="🚧"
    text={
      <>
        Audiences are currently in beta. If you'd like early access, or this is
        blocking your adoption of Knock, please{" "}
        <a href="mailto:support@knock.app?subject=Audiences">get in touch</a>.
      </>
    }
  />

List audience members.

### Endpoint

<Endpoint
  name="audiences-list-members"
  method="GET"
  path="/audiences/:audience_key/members"
/>

### Rate limit

<RateLimit tier={4} />

### Path parameters

<Attributes>
  <Attribute
    name="audience_key"
    type="string"
    description="The key of the audience to add the user to"
  />
  <Attribute
    name="page_size"
    type="number"
    description="The total number to retrieve per page (defaults to 25)"
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after (hint: use the `page_info.after` field)"
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before (hint: use the `page_info.before` field)"
  />
</Attributes>

### Returns

A paginated list of audience members records. The value of the `user` field is a [User](/reference#users) object. If no user is found for a given user ID, the value of the `user` field will be `null`.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "added_at": "2024-09-26T23:34:24.923224Z",
      "tenant": null,
      "user": {
        "__typename": "User",
        "created_at": null,
        "id": "a703abd7-7717-447b-bb85-dbd3fca64cff",
        "updated_at": "2024-09-26T23:32:27.214Z",
        "email": "user-1@example.com",
        "name": "User 1"
      },
      "user_id": "a703abd7-7717-447b-bb85-dbd3fca64cff",
      "__typename": "AudienceMember"
    },
    {
      "added_at": "2024-09-26T23:34:24.923224Z",
      "tenant": "tenant-1",
      "user": {
        "__typename": "User",
        "created_at": null,
        "id": "efab1fb5-1a28-446c-8042-ac0fc5d13d48",
        "updated_at": "2024-09-26T23:32:45.244Z",
        "email": "user-2@example.com",
        "name": "User 2"
      },
      "user_id": "efab1fb5-1a28-446c-8042-ac0fc5d13d48",
      "__typename": "AudienceMember"
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "limit": 25,
    "total_count": 2
  }
}
```

</ExampleColumn>
</Section>

<Section title="Add audience members" slug="audiences-add-members">
<ContentColumn>

<Callout
  emoji="🚧"
  text={
    <>
      Audiences are currently in beta. If you'd like early access, or this is
      blocking your adoption of Knock, please{" "}
      <a href="mailto:support@knock.app?subject=Audiences">get in touch</a>.
    </>
  }
/>

Adds members to an audience. The same user can be added to the audience multiple times with distinct tenant IDs.

### Endpoint

<Endpoint
  name="audiences-add-members"
  method="POST"
  path="/audiences/:audience_key/members"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="audience_key"
    type="string"
    description="The key of the audience to add members to"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="members"
    type="object[]"
    description="Members to add to the audience. The `tenant` field is optional. Max length is 1000."
  />
</Attributes>

### Returns

- `204` no content
- `404` if the audience cannot be found

</ContentColumn>
<ExampleColumn>

```json title="Request"
// Request (POST to /audiences/:audience_key/members)

{
  "members": [
    {
      "user": {
        "id": "a703abd7-7717-447b-bb85-dbd3fca64cff"
      }
    },
    {
      "user": {
        "id": "efab1fb5-1a28-446c-8042-ac0fc5d13d48"
      },
      "tenant": "tenant-1"
    }
  ]
}
```

</ExampleColumn>
</Section>

<Section title="Remove audience members" slug="audiences-remove-members">
<ContentColumn>
  <Callout
    emoji="🚧"
    text={
      <>
        Audiences are currently in beta. If you'd like early access, or this is
        blocking your adoption of Knock, please{" "}
        <a href="mailto:support@knock.app?subject=Audiences">get in touch</a>.
      </>
    }
  />

Removes members from an audience. If a member was added with a tenant ID, that tenant ID must also be provided for the member in the deletion request.

### Endpoint

<Endpoint
  name="audiences-remove-members"
  method="DELETE"
  path="/audiences/:audience_key/members"
/>

### Rate limit

<RateLimit tier={3} />

### Path parameters

<Attributes>
  <Attribute
    name="audience_key"
    type="string"
    description="The key of the audience to remove members from"
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="members"
    type="object[]"
    description="Members to remove from the audience. The `tenant` field is optional. Max length is 1000."
  />
</Attributes>

### Returns

- `204` no content
- `404` if the audience cannot be found

</ContentColumn>
<ExampleColumn>

```json title="Request"
// Request (POST to /audiences/:audience_key/members)

{
  "members": [
    {
      "user": {
        "id": "a703abd7-7717-447b-bb85-dbd3fca64cff"
      }
    },
    {
      "user": {
        "id": "efab1fb5-1a28-446c-8042-ac0fc5d13d48"
      },
      "tenant": "tenant-1"
    }
  ]
}
```

</ExampleColumn>
</Section>


## CLI Reference
Learn more about the commands and flags available in the Knock CLI.
---
title: CLI reference
description: Learn more about the commands and flags available in the Knock CLI.
tags: ["cli", "command line", "cmd", "command-line", "terminal"]
layout: cli
Section: CLI
---

<a id="overview" className="absolute -top-8 invisible" />

<Section title="Knock CLI reference" slug="overview">
<ContentColumn>

This reference documents every command and flag available in Knock's command-line interface.

The Knock CLI helps you work with your Knock resources right from the terminal.

With the CLI, you can:

- Work with your Knock workflows and notification templates locally.
- Integrate Knock into your CI/CD environment to automatically promote changes.
- Map your translation files into Knock to localize your notifications.

</ContentColumn>
</Section>

<Section title="Install the CLI" slug="installation">
<ContentColumn>

### Install with homebrew

For macOS, you can install the Knock CLI using [homebrew](https://brew.sh/). Once the CLI is installed you can call it by using the `knock` command in your terminal.

### Install with npm

For other operating systems, you can install the Knock CLI using `npm`, a node package manager. Once the CLI is installed, you can call it by using the `knock` command in your terminal.

**Requirements**

The Knock CLI is built with Node.js and installable as a `npm` package. You must have `node` and `npm` installed already, with the following versions:

- Node.js: 16.14.0 or higher
- NPM: 7.18.1 or higher

You can find the Knock CLI npm package [here](https://www.npmjs.com/package/@knocklabs/cli).

</ContentColumn>
<ExampleColumn>

```bash title="Install the Knock CLI with homebrew"
brew install knocklabs/tap/knock
```

<div style={{ marginTop: 80 }} />

```bash title="Install the Knock CLI with npm"
npm install -g @knocklabs/cli
```

</ExampleColumn>
</Section>

<Section title="Authentication" slug="authentication">
<ContentColumn>

The Knock CLI relies on a [service token](/developer-tools/service-tokens) to authenticate and make requests to your Knock account. You can specify a service token in all CLI calls, or you can optionally use a configuration file to authenticate all requests.

[Learn how to create a service token.](/developer-tools/service-tokens)

**Setting up a configuration file (optional)**

A service token is required by the CLI for most commands. For convenience, Knock CLI supports a user configuration file, where you can store the service token for the CLI to read automatically rather than having to manually pass in with `--service-token` flag for every command.

To set up a user configuration file, create a `config.json` file in the Knock CLI's config directory at `~/.config/knock` (macOS/Unix) or `%LOCALAPPDATA%\knock` (Windows), and add the following json:

```json title="config.json"
{
  "serviceToken": "YOUR_SERVICE_TOKEN"
}
```

When Knock CLI detects a user configuration file, it will use the service token provided in it automatically.

</ContentColumn>
<ExampleColumn>

```bash title="Verify your service token"
knock whoami --service-token=XXX
```

</ExampleColumn>
</Section>

<Section title="knock {cmd} <arguments> [flags]" slug="global-flags" headingClassName="font-mono">
<ContentColumn>

The following flags are supported for every command.

### Flags

<Attributes>
  <Attribute
    name="--service-token"
    type="string"
    description="The service token for a Knock account to issue the commands against. Required when not using a configuration file."
  />
</Attributes>

</ContentColumn>
</Section>

<Section title="knock workflow list [flags]" slug="workflow-list" headingClassName="font-mono">
<ContentColumn>

You can see all your existing workflows in a given environment with the workflow list command.

Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--limit"
    type="number"
    description="The total number to fetch per page."
  />
  <Attribute
    name="--after"
    type="string"
    description="Fetches all entries after this cursor."
  />
  <Attribute
    name="--before"
    type="string"
    description="Fetches all entries before this cursor."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow list
```

```bash title="Pagination example"
knock workflow list --after=xxx
```

</ExampleColumn>
</Section>

<Section title="knock workflow get [flags]" slug="workflow-get" headingClassName="font-mono">
<ContentColumn>

You can show more details about a given workflow with the `workflow get` command, followed by the target workflow key.

Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow get my-workflow
```

```bash title="Get workflow in a different environment"
knock workflow get my-workflow --environment=production
```

</ExampleColumn>
</Section>

<Section title="knock workflow pull [flags]" slug="workflow-pull" headingClassName="font-mono">
<ContentColumn>

You can pull and download workflows with its message templates from Knock to a local file system with the `workflow pull` command. Knock CLI will create a new workflow directory or update the existing workflow directory in the local file system.

Note: if pulling the target workflow for the first time (or all workflows), Knock CLI will ask to confirm before writing to the local file system.

See how workflow files are structured in your system [here](/concepts/workflows#workflow-files-structure).

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--all"
    type="boolean"
    description={
      <>
        <p>
          Whether to pull all workflows from the specified environment into the
          target directory path set by `--workflows-dir`. Defaults to false.
        </p>
        <p>
          When used, all contents in the target directory will be erased and
          replaced with all workflows from the specified environment.
        </p>
      </>
    }
  />
  <Attribute
    name="--workflows-dir"
    type="directory"
    description="Specifies which target directory path to pull all workflows into. Only available to be used with --all, and defaults to the current working directory."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--force"
    type="boolean"
    description="Removes the confirmation prompt. Defaults to false."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow pull my-workflow
```

```bash title="Pulling a workflow in a different environment"
knock workflow pull my-workflow --environment=production
```

```bash title="Pulling all workflows into ./workflows directory"
knock workflow pull --all --workflows-dir=./workflows
```

</ExampleColumn>
</Section>

<Section title="knock workflow push [flags]" slug="workflow-push" headingClassName="font-mono">
<ContentColumn>

You can push and upload a workflow directory to Knock with the `workflow push` command. Knock will update an existing workflow by the matching workflow key, or create a new workflow if it does not exist yet.

Note:

- The `workflow push` command only pushes workflows into the `development` environment.
- You must be directly above the target workflow directory when running the `workflow push` command, so the CLI can locate the `workflow.json` file.
- You can also pass in the `--commit` flag (with an optional `--commit-message` flag) to commit the upserted changes immediately.

See how workflow files are structured in your system [here](/concepts/workflows#workflow-files-structure).

### Flags

<Attributes>
  <Attribute
    name="--commit"
    type="boolean"
    description="Push and commit the workflow(s) at the same time. Defaults to false."
  />
  <Attribute
    name="-m, --commit-message"
    type="string"
    description="The commit message to pass when using the `--commit` flag."
  />
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to push all workflows from the target directory path set by `--workflows-dir`. Defaults to false."
  />
  <Attribute
    name="--workflows-dir"
    type="directory"
    description="Specifies the target directory path to find and push all workflows from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow push my-workflow
```

```bash title="Pushing a workflow and committing with a message"
knock workflow push my-workflow \
  --commit \
  -m "Commit message"
```

```bash title="Pushing all workflows from ./workflows directory"
knock workflow push --all --workflows-dir=./workflows
```

</ExampleColumn>
</Section>

<Section title="knock workflow run <workflow_key> [flags]" slug="workflow-run" headingClassName="font-mono">
<ContentColumn>

You can run a workflow with the `workflow run` command. Knock will execute a run for the latest saved version of the workflow it finds with the given key and parameters you send it.

Note:

- Changes to the local version of the workflow in your file system will not be reflected in a workflow run; it will use the current version that is stored in Knock.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The slug of the environment in which to run this workflow. Defaults to development."
  />

  <Attribute
    name="--recipients"
    type="string[]"
    description="One or more recipient ids for this workflow run, maximum limit 5."
  />
  <Attribute
    name="--data"
    type="string"
    description="A JSON string of the data with which this workflow will run."
  />
  <Attribute
    name="--actor"
    type="string"
    description="An optional actor id for this workflow run."
  />
  <Attribute
    name="--tenant"
    type="string"
    description="An optional tenant id for this workflow run."
  />
</Attributes>

</ContentColumn>

<ExampleColumn>

```bash title="Basic usage"
knock workflow run my-workflow \
  --environment=production \
  --recipients=ellie
```

</ExampleColumn>
</Section>

<Section title="knock workflow validate <workflow_key> [flags]" slug="workflow-validate" headingClassName="font-mono">
<ContentColumn>

You can validate a new or updated workflow directory with the `workflow validate` command. Knock will validate the given workflow payload in the same way as it would with the `workflow push` command, except without persisting those changes.

Note: Validating a workflow is only done against the `development` environment.

### Flags

<Attributes>
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to validate all workflows from the target directory path set by `--workflows-dir`. Defaults to false."
  />
  <Attribute
    name="--workflows-dir"
    type="directory"
    description="Specifies the target directory path to find and validate all workflows from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow validate my-workflow
```

</ExampleColumn>
</Section>

<Section title="knock workflow activate [flags]" slug="workflow-activate" headingClassName="font-mono">
<ContentColumn>

You can activate or deactivate a workflow in a given environment with the `workflow activate` command.

Note:

- This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.
- By default, this command activates a given workflow. Pass in the `--status` flag with `false` in order to deactivate it.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string (required)"
    description="The environment to activate the workflow in."
  />
  <Attribute
    name="--force"
    type="boolean"
    description="Removes the confirmation prompt. Defaults to false."
  />
  <Attribute
    name="--status"
    type="boolean"
    description="The status to set. Defaults to `true`."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock workflow activate my-workflow \
  --environment=development
```

```bash Deactivating a workflow
knock workflow activate my-workflow \
  --environment=development \
  --status=false
```

</ExampleColumn>
</Section>

<Section title="knock layout list [flags]" slug="email-layout-list" headingClassName="font-mono">
<ContentColumn>

List all email layouts in the environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--limit"
    type="number"
    description="The total number to fetch per page."
  />
  <Attribute
    name="--after"
    type="string"
    description="Fetches all entries after this cursor."
  />
  <Attribute
    name="--before"
    type="string"
    description="Fetches all entries before this cursor."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock layout list
```

</ExampleColumn>
</Section>

<Section title="knock layout get <layout_key> [flags]" slug="email-layout-get" headingClassName="font-mono">
<ContentColumn>

Fetches a single email layout, using the `key` of the email layout.

Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash Get layout
knock layout get default
```

```bash Get layout in a different environment
knock layout get default --environment=production
```

</ExampleColumn>
</Section>

<Section title="knock layout pull <layout_key> [flags]" slug="email-layout-pull" headingClassName="font-mono">
<ContentColumn>

Pulls the contents of one or all email layouts from Knock into your local file system. Using `<layout_key>` you can pull a single email layout specified by the key, or use the `--all` flag to pull all email layouts from Knock at once.

See how layout files are structured in your system [here](/integrations/email/layouts#layout-files-structure).

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--all"
    type="boolean"
    description={
      <>
        <p>
          Whether to pull all email layouts from the specified environment into
          the target directory path set by `--email-layouts-dir`. Defaults to
          false.
        </p>
        <p>
          When used, all contents in the target directory will be erased and
          replaced with all email layouts from the specified environment.
        </p>
      </>
    }
  />
  <Attribute
    name="--email-layouts-dir"
    type="directory"
    description="Specifies which target directory path to pull all email layouts into. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash Pull a single email layout
knock layout pull default
```

```bash Pull all email layouts
knock layout pull --all
```

</ExampleColumn>
</Section>

<Section title="knock layout push <layout_key> [flags]" slug="email-layout-push" headingClassName="font-mono">
<ContentColumn>

Pushes local email layouts back to Knock and upserts them. Using `<layout_key>` you can push a single email layout specified by the key, or use the `--all` flag to push all email layouts from Knock at once.

See how layout files are structured in your system [here](/integrations/email/layouts#layout-files-structure).

### Flags

<Attributes>
  <Attribute
    name="--commit"
    type="boolean"
    description="Push and commit at the same time. Defaults to false."
  />
  <Attribute
    name="-m, --commit-message"
    type="string"
    description="The commit message to pass when using the `--commit` flag."
  />
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to push all email layouts to the target environment. Defaults to false."
  />
  <Attribute
    name="--email-layouts-dir"
    type="directory"
    description="Specifies the target directory path to find and push all email layouts from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash Push a single email layout
knock layout push
```

```bash Push all email layouts
knock layout push --all
```

</ExampleColumn>
</Section>

<Section title="knock layout validate <layout_key> [flags]" slug="email-layout-validate" headingClassName="font-mono">
<ContentColumn>

Validates one or more email layouts. Useful for checking if the layout is valid before running the `email_layout push` command.

The `<layout_key>` can be provided to validate a single email layout, or your can use the `--all` flag to validate all email layouts.

Can only be validated against the `development` environment.

### Flags

<Attributes>
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to validate all email layouts. Defaults to false."
  />
  <Attribute
    name="--email-layouts-dir"
    type="directory"
    description="Specifies the target directory path to find and validate all email layouts from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock layout validate --all
```

```bash title="Validate a single email layout"
knock layout validate default
```

</ExampleColumn>
</Section>

<Section title="knock translation list [flags]" slug="translation-list" headingClassName="font-mono">
<ContentColumn>

List all translations in the environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--limit"
    type="number"
    description="The total number to fetch per page."
  />
  <Attribute
    name="--after"
    type="string"
    description="Fetches all entries after this cursor."
  />
  <Attribute
    name="--before"
    type="string"
    description="Fetches all entries before this cursor."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock translation list
```

</ExampleColumn>
</Section>

<Section title="knock translation get <translation_ref> [flags]" slug="translation-get" headingClassName="font-mono">
<ContentColumn>

You can show the content of a given translation with the `translation get` command, followed by the target translation ref.

The `<translation_ref>` is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. `en`. If namespaced, it is formatted as `namespace.locale`, i.e. `admin.en`.

Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--format"
    type="string"
    description="Specify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Get translation without a namespace"
knock translation get en
```

```bash title="Get translation with a namespace"
knock translation get admin.en
```

```bash title="Get translation in a different environment"
knock translation get en --environment=production
```

</ExampleColumn>
</Section>

<Section title="knock translation pull <translation_ref> [flags]" slug="translation-pull" headingClassName="font-mono">
<ContentColumn>

You can pull and download translation files from Knock to a local file system with the `translation pull` command. Knock CLI will create a new translation file or update the existing file in the local file system.

The `<translation_ref>` is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. `en`. If namespaced, it is formatted as `namespace.locale`, i.e. `admin.en`.

When `<translation_ref>` is a locale code and specified with the `--all` flag, all translations for that locale are pulled.

See how translation files are structured in your system [here](/concepts/translations#translation-directory-structure).

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--format"
    type="string"
    description="Specify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'."
  />
  <Attribute
    name="--all"
    type="boolean"
    description={
      <>
        <p>
          Whether to pull all translations from the specified environment into
          the target directory path set by `--translations-dir`. Defaults to
          false.
        </p>
        <p>
          When used with a locale code, will pull all translations for that
          locale only.
        </p>
        <p>
          Note: all contents in the target directory will be erased and replaced
          with all translations from the specified environment.
        </p>
      </>
    }
  />
  <Attribute
    name="--translations-dir"
    type="directory"
    description="Specifies which target directory path to pull all translations into. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Pull a single translation without a namespace"
knock translation pull en
```

```bash title="Pull a single translation with a namespace"
knock translation pull admin.en
```

```bash title="Pull all translations for a locale"
knock translation pull en --all
```

```bash title="Pull all translations"
knock translation pull --all
```

```bash title="Pull all translations as PO files"
knock translation pull --all --format=po
```

</ExampleColumn>
</Section>

<Section title="knock translation push <translation_ref> [flags]" slug="translation-push" headingClassName="font-mono">
<ContentColumn>

Pushes local translation files back to Knock and upserts them.

The `<translation_ref>` is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. `en`. If namespaced, it is formatted as `namespace.locale`, i.e. `admin.en`.

When `<translation_ref>` is a locale code and specified with the `--all` flag, all translations for that locale are pushed.

See how translation files are structured in your system [here](/concepts/translations#translation-directory-structure).

### Flags

<Attributes>
  <Attribute
    name="--commit"
    type="boolean"
    description="Push and commit at the same time. Defaults to false."
  />
  <Attribute
    name="-m, --commit-message"
    type="string"
    description="The commit message to pass when using the `--commit` flag."
  />
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to push all translation files to the target environment. Defaults to false."
  />
  <Attribute
    name="--translations-dir"
    type="directory"
    description="Specifies the target directory path to find and push all translations from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Push a single translation without a namespace"
knock translation push en
```

```bash title="Push a single translation with a namespace"
knock translation push tasks.en
```

```bash title="Push all translation files for the en locale"
knock translation push en --all
```

```bash title="Push all translation files"
knock translation push --all
```

</ExampleColumn>
</Section>

<Section title="knock translation validate <translation_ref> [flags]" slug="translation-validate" headingClassName="font-mono">
<ContentColumn>

Validates one or more translation files. Useful for checking if the file is valid before running the `translation push` method.

The `<translation_ref>` is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. `en`. If namespaced, it is formatted as `namespace.locale`, i.e. `admin.en`.

Can only be validated against the `development` environment.

### Flags

<Attributes>
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to validate all translation files. Defaults to false."
  />
  <Attribute
    name="--translations-dir"
    type="directory"
    description="Specifies the target directory path to find and validate all translation files from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock translation validate --all
```

```bash title="Validate a single file"
knock translation validate admin.en
```

```bash title="Validate all translations for the en locale"
knock translation validate en --all
```

</ExampleColumn>
</Section>

<Section title="knock partial list [flags]" slug="partial-list" headingClassName="font-mono">
<ContentColumn>

List all partials in the environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--limit"
    type="number"
    description="The total number to fetch per page."
  />
  <Attribute
    name="--after"
    type="string"
    description="Fetches all entries after this cursor."
  />
  <Attribute
    name="--before"
    type="string"
    description="Fetches all entries before this cursor."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock partial list
```

</ExampleColumn>
</Section>

<Section title="knock partial get <partial_key> [flags]" slug="partial-get" headingClassName="font-mono">
<ContentColumn>

You can show more details about a given partial with the `partial get` command, followed by the target partial key.

Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Get partial"
knock partial get my-partial
```

```bash title="Get partial in a different environment"
knock partial get my-partial --environment=production
```

</ExampleColumn>
</Section>

<Section title="knock partial pull <partial_key> [flags]" slug="partial-pull" headingClassName="font-mono">
<ContentColumn>

You can pull and download partial files from Knock to a local file system with the `partial pull` command. Knock CLI will create a new partial directory or update the existing partial directory in the local file system.

Note: if pulling the target partial for the first time (or all partials), Knock CLI will ask to confirm before writing to the local file system.

See how partial files are structured in your system [here](/designing-workflows/partials#partial-files-structure).

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--all"
    type="boolean"
    description={
      <>
        <p>
          Whether to pull all partials from the specified environment into the
          target directory path set by `--partials-dir`. Defaults to false.
        </p>
        <p>
          Note: all contents in the target directory will be erased and replaced
          with all partials from the specified environment.
        </p>
      </>
    }
  />
  <Attribute
    name="--partials-dir"
    type="directory"
    description="Specifies which target directory path to pull all partials into. Only available to be used with --all, and defaults to the current working directory."
  />
  <Attribute
    name="--hide-uncommitted-changes"
    type="boolean"
    description="Should any uncommitted changes be hidden? Defaults to false."
  />
  <Attribute
    name="--force"
    type="boolean"
    description="Removes the confirmation prompt. Defaults to false."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Pull a single partial"
knock partial pull my-partial
```

```bash title="Pull all partials"
knock partial pull --all
```

</ExampleColumn>
</Section>

<Section title="knock partial push <partial_key> [flags]" slug="partial-push" headingClassName="font-mono">
<ContentColumn>

You can push and upload a partial directory to Knock with the `partial push` command. Knock will update an existing partial by the matching partial key, or create a new partial if it does not exist yet.

Note:

- The `partial push` command only pushes partials into the `development` environment.
- You must be directly above the target partial directory when running the `partial push` command, so the CLI can locate the `partial.json` file.
- You can also pass in the `--commit` flag (with an optional `--commit-message` flag) to commit the upserted changes immediately.

### Flags

<Attributes>
  <Attribute
    name="--commit"
    type="boolean"
    description="Push and commit at the same time. Defaults to false."
  />
  <Attribute
    name="-m, --commit-message"
    type="string"
    description="The commit message to pass when using the `--commit` flag."
  />
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to push all partial files to the target environment. Defaults to false."
  />
  <Attribute
    name="--partials-dir"
    type="directory"
    description="Specifies the target directory path to find and push all partials from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Push a single partial"
knock partial push my-partial
```

```bash title="Pushing a partial and committing with a message"
knock partial push my-partial \
  --commit \
  -m "Commit message"
```

```bash title="Pushing all partials from ./partials directory"
knock partial push --all --partials-dir=./partials
```

</ExampleColumn>
</Section>

<Section title="knock partial validate <partial_key> [flags]" slug="partial-validate" headingClassName="font-mono">
<ContentColumn>

Validates one or more partial files. Useful for checking if the file is valid before running the `partial push` method.

Can only be validated against the `development` environment.

### Flags

<Attributes>
  <Attribute
    name="--all"
    type="boolean"
    description="Whether to validate all partial files. Defaults to false."
  />
  <Attribute
    name="--partials-dir"
    type="directory"
    description="Specifies the target directory path to find and validate all partial files from. Only available to be used with --all, and defaults to the current working directory."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock partial validate --all
```

```bash title="Validate a single partial"
knock partial validate my-partial
```

</ExampleColumn>
</Section>

<Section title="knock commit list [flags]" slug="commit-list" headingClassName="font-mono">
<ContentColumn>

List all commits in the environment. Use an `--environment` flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

### Flags

<Attributes>
  <Attribute
    name="--environment"
    type="string"
    description="The environment to use. Defaults to development."
  />
  <Attribute
    name="--[no-]promoted"
    type="boolean"
    description="Show only promoted or unpromoted changes between the given environment and the subsequent environment."
  />
  <Attribute
    name="--limit"
    type="number"
    description="The total number to fetch per page."
  />
  <Attribute
    name="--after"
    type="string"
    description="Fetches all entries after this cursor."
  />
  <Attribute
    name="--before"
    type="string"
    description="Fetches all entries before this cursor."
  />
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock commit list
```

```bash title="List unpromoted commits in a different environment"
knock commit list --no-promoted --environment=staging
```

</ExampleColumn>
</Section>

<Section title="knock commit get <commit_id> [flags]" slug="commit-get" headingClassName="font-mono">
<ContentColumn>

Shows the details of a given commit, using the `id` of the commit.

### Flags

<Attributes>
  <Attribute name="--json" type="string" description="Format output as json." />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock commit get 69cdde18-830a-42e0-ad4b-a230943bdc90
```

</ExampleColumn>
</Section>

<Section title="knock commit [flags]" slug="commit-all" headingClassName="font-mono">
<ContentColumn>

You can commit all changes across all resources in the development environment with the commit command.

### Flags

<Attributes>
  <Attribute
    name="-m, --commit-message"
    type="string"
    description="The commit message to use for all changes."
  />
  <Attribute
    name="--force"
    type="boolean"
    description="Removes the confirmation prompt. Defaults to false."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Basic usage"
knock commit -m "Commit message"
```

</ExampleColumn>
</Section>

<Section title="knock commit promote [flags]" slug="commit-promote" headingClassName="font-mono">
<ContentColumn>

You can promote one change to the subsequent environment, or all changes across all resources to the target environment from its directly preceding environment, using the `commit promote` command.

Note:

- For example, if you have three environments “development”, “staging”, and “production” (in that order), setting the `--to` flag to `production` will promote all new changes from the staging environment to the production environment
- Following the same example, promoting one single commit from staging using the `--only` flag, will result in that commit being promoted to production.
- The `--to` environment must be a non-development environment.
- The `--to` and `--only` flags can't be used together.

### Flags

<Attributes>
  <Attribute
    name="--to"
    type="string"
    description="The destination environment."
  />
  <Attribute
    name="--only"
    type="string"
    description="The target commit id to promote to the subsequent environment."
  />
  <Attribute
    name="--force"
    type="boolean"
    description="Removes the confirmation prompt. Defaults to false."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```bash title="Promotes all changes"
knock commit promote --to=production
```

```bash title="Promotes one change"
knock commit promote --only=69cdde18-830a-42e0-ad4b-a230943bdc90
```

</ExampleColumn>
</Section>


## Management API Reference
Complete reference documentation for the Knock management API. Includes code snippets and examples for our Python, Elixir, PHP, Node.js, Go, Ruby, and .NET libraries.
---
title: Management API reference
description: Complete reference documentation for the Knock management API. Includes code snippets and examples for our Python, Elixir, PHP, Node.js, Go, Ruby, and .NET libraries.
showNav: false
layout: mapi
tags: ["api", "sdks", "api key", "keys", "errors"]
---

<a id="overview" className="absolute -top-8 invisible" />

<Section title="Management API Reference" slug="overview">
<ContentColumn>

<Callout
  emoji="🚨"
  text={
    <>
      <strong>Note:</strong> the Knock management API only provides access to
      the resources managed in <strong>the Knock dashboard</strong>, such as
      workflows, templates, translations and commits.
      <br />
      <br />
      All other concepts within the Knock notification engine are accessed through
      the <a href="/reference">Knock API</a>, which you use to trigger workflows,
      identify users, and manage preferences.
    </>
  }
/>

The Knock management API provides you with a programmatic way to interact with the resources you create and manage in your Knock dashboard, including workflows, templates, layouts, translations and commits. It's separate from the [Knock API](/reference) and only provides access to a limited subset of resources.

You can use the Knock management API to:

- Create, update, and manage your Knock workflows and the notification templates within those workflows.
- Create, update and manage your [email layouts](/integrations/email/layouts).
- Create and manage the [translations](/concepts/translations) used by your notification templates.
- Create, update, and manage your [partials](/designing-workflows/partials).
- Commit and promote changes between your Knock environments.

</ContentColumn>
<ExampleColumn>

```bash title="Base URL"
https://control.knock.app/v1
```

</ExampleColumn>
</Section>

<Section title="Authentication" slug="authentication">
<ContentColumn>

The management API authenticates with a Bearer authentication mechanism using a [service token](/developer-tools/service-tokens) generated on your account.

Note: [environment-level API keys](/developer-tools/api-keys) should never be used to authenticate with the management API. To authenticate with the management API, generate a [service token](/developer-tools/service-tokens).

</ContentColumn>
<ExampleColumn>

```
Authorization: Bearer knock_st_12345
```

</ExampleColumn>
</Section>

<Section title="Errors" slug="errors" direction="column">
<ContentColumn>

Knock uses standard [HTTP response codes](https://developer.mozilla.org/en-US/Web/HTTP/Status) to indicate the success or failure of your API requests.

- `2xx` success status codes confirm that your request worked as expected.
- `4xx` error status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key).
- `5xx` error status codes indicate a Knock server error.

</ContentColumn>
</Section>

<Section title="Postman" slug="postman" direction="column">
<ContentColumn>

You can use our [Management API Postman collection](https://www.postman.com/knock-labs/workspace/knock-public-workspace/collection/15616728-9ed6000c-13bc-43f5-a2cf-db6daea256bd?action=share&creator=15616728&active-environment=15616728-6df39335-c6f9-4c9d-99d5-73e3c7ffe524) to quickly get started testing our Management API.

</ContentColumn>
</Section>

<Section title="Workflows" slug="workflows-overview">
<ContentColumn>

To define a logical flow of your notifications, you create a workflow consisting of workflow steps. Workflow steps can be [functions](/designing-workflows#function-steps) or [channels](/designing-workflows#channel-steps), and can have conditional logic that determines whether to execute that step when the workflow is triggered.

You can retrieve, update, or create a workflow as well as list all workflows in a given [environment](/concepts/environments). Workflows are identified by their unique workflow key.

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="workflows-list" method="GET" path="/workflows" withLink />
  <Endpoint
    name="workflows-get"
    method="GET"
    path="/workflows/:workflow_key"
    withLink
  />
  <Endpoint
    name="workflows-update"
    method="PUT"
    path="/workflows/:workflow_key"
    withLink
  />
  <Endpoint
    name="workflows-validate"
    method="PUT"
    path="/workflows/:workflow_key/validate"
    withLink
  />
  <Endpoint
    name="workflows-activate"
    method="PUT"
    path="/workflows/:workflow_key/activate"
    withLink
  />
  <Endpoint
    name="workflows-preview-template"
    method="POST"
    path="/workflows/:workflow_key/steps/:step_ref/preview_template"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section title="Workflow definition" slug="workflows-object">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="active"
    type="boolean (read-only)"
    description="Whether the workflow is active in the current environment."
  />
  <Attribute
    name="categories"
    type="string[]"
    description="A list of categories that the workflow belongs to."
  />
  <Attribute
    name="conditions"
    type="object (optional)"
    typeSlug="/concepts/conditions#modeling-conditions"
    description="A conditions object that describes one or more conditions to be met for the workflow to be executed."
  />
  <Attribute
    name="created_at"
    type="timestamp (read-only)"
    description="A timestamp of when the workflow was created."
  />
  <Attribute
    name="description"
    type="string"
    description="An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed."
  />
  <Attribute
    name="environment"
    type="string (read-only)"
    description="The slug of the environment in which the workflow exists."
  />
  <Attribute
    name="key"
    type="string (mutable only at creation)"
    description="The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$."
  />
  <Attribute
    name="name"
    type="string"
    description="A name for the workflow. Must be at maximum 255 characters in length."
  />
  <Attribute
    name="sha"
    type="string (read-only)"
    description="The SHA hash of the workflow data."
  />
  <Attribute
    name="settings"
    type="WorkflowSettings"
    typeSlug="#workflowsettings-definition"
    description="A map of workflow settings."
  />
  <Attribute
    name="steps"
    type="WorkflowStep[]"
    typeSlug="#workflowstep-definition"
    description="A list of workflow step objects in the workflow, which may contain any of: channel step, delay step, batch step, fetch step."
  />
  <Attribute
    name="trigger_data_json_schema"
    type="object (optional)"
    typeSlug="/developer-tools/validating-trigger-data#example-schema"
    description="A JSON schema for the expected structure of the workflow trigger's data payload. Used to validate trigger requests."
  />
  <Attribute
    name="trigger_frequency"
    type="string"
    typeSlug="/send-notifications/triggering-workflows#controlling-workflow-trigger-frequency"
    description="The frequency at which the workflow should be triggered. One of: ”once_per_recipient”, ”once_per_recipient_per_tenant”, ”every_trigger”. Defaults to ”every_trigger”."
  />
  <Attribute
    name="updated_at"
    type="timestamp (read-only)"
    description="A timestamp of when the workflow was last updated."
  />
  <Attribute
    name="valid"
    type="boolean (read-only)"
    description="Whether the workflow and its steps are in a valid state."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Workflow object"
{
  "active": false,
  "categories": ["marketing", "black-friday"],
  "conditions": {
    "all": [
      {
        "variable": "recipient.role",
        "operator": "equal_to",
        "argument": "admin"
      }
    ]
  },
  "created_at": "2022-12-16T19:07:50.027113Z",
  "description": "This is a dummy workflow for demo purposes.",
  "environment": "development",
  "key": "december-16-demo",
  "name": "december-16-demo",
  "sha": "f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y",
  "settings": { "override_preferences": true },
  "steps": [
    {
      "channel_key": "in-app-feed",
      "description": "Main in-app feed",
      "name": "In-app step",
      "ref": "in_app_feed_1",
      "template": {
        "action_url": "{{ vars.app_url }}",
        "markdown_body": "Hello **{{ recipient.name }}**"
      },
      "type": "channel"
    }
  ],
  "trigger_data_json_schema": {
    "properties": {
      "name": {
        "type": "string"
      }
    },
    "required": ["name"],
    "type": "object"
  },
  "trigger_frequency": "every_trigger",
  "updated_at": "2023-02-08T22:15:19.846681Z",
  "valid": true
}
```

</ExampleColumn>
</Section>

<Section title="WorkflowSettings definition" slug="workflowsettings-definition">
<ContentColumn>

Optional settings for a workflow.

### Attributes

<Attributes>
  <Attribute
    name="override_preferences"
    type="boolean"
    description="Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Example workflow settings"
{
  "override_preferences": true
}
```

</ExampleColumn>
</Section>

<Section title="WorkflowStep definition" slug="workflowstep-definition">
<ContentColumn>

All workflow steps, regardless of its type, share a common set of core attributes.

### Common attributes

<Attributes>
  <Attribute
    name="type"
    type="string"
    description="The type of the workflow step. One of: ”channel”, “delay”, “batch”, ”branch”, ”throttle”, or “http_fetch”."
  />
  <Attribute
    name="ref"
    type="string"
    description="The reference key of the workflow step. Must be unique per workflow."
  />
  <Attribute
    name="name"
    type="string"
    description="A name for the workflow step."
  />
  <Attribute
    name="description"
    type="string"
    description="An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes."
  />
  <Attribute
    name="conditions"
    type="object (optional)"
    typeSlug="/concepts/conditions#modeling-conditions"
    description="A conditions object that describes one or more conditions to be met in order for the step to be executed."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Example step"
{
  "type": "delay",
  "ref": "delay_1",
  "name": "Delay step",
  "description": null,
  "conditions": {
    "all": [
      {
        "variable": "recipient.role",
        "operator": "equal_to",
        "argument": "admin"
      }
    ]
  }
}
```

</ExampleColumn>
</Section>

<Section title="ChannelStep definition" slug="channelstep-definition">
<ContentColumn>

Contains all properties of the <a href="#workflowstep-definition">`WorkflowStep`</a> and additionally:

### Attributes

<Attributes>
  <Attribute
    name="channel_key"
    type="string"
    description="The key of the channel to which the channel step will be sending a notification. A channel step can have either a channel key or a channel group key, but not both."
  />
  <Attribute
    name="channel_group_key"
    type="string"
    description="The key of the channel group to which the channel step will be sending a notification. A channel step can have either a channel key or a channel group key, but not both."
  />
  <Attribute
    name="template"
    type="object"
    description="The message template set up with the channel step. The shape of the template depends on the type of the channel you'll be sending to. See below for definitions of each channel type template: email, in-app, SMS, push, chat, and webhook."
  />
  <Attribute
    name="send_windows"
    type="SendWindow[]"
    typeSlug="#sendwindow-definition"
    description="A list of send window objects. Must include one send window object per day of the week."
  />
  <Attribute
    name="channel_overrides"
    type="ChannelSettings (optional)"
    typeSlug="#channelsettings-definition"
    description="A map of channel overrides for the channel step."
  />
</Attributes>

#### Email template attributes

<Attributes>
  <Attribute
    name="subject"
    type="string"
    description="A text template for the email subject line."
  />
  <Attribute
    name="html_body"
    type="string"
    description="An HTML template for the email body."
  />
  <Attribute
    name="text_body"
    type="string"
    description="A text template for the email body. Only present if opted out from autogenerating it from the HTML template."
  />
  <Attribute
    name="visual_blocks"
    type="object[]"
    description="A list of visual blocks for the email body. Only present if using the visual blocks template over the HTML template."
  />
  <Attribute
    name="settings.layout_key"
    type="string"
    description="The key of the email layout which the step is using."
  />
  <Attribute
    name="settings.pre_content"
    type="string"
    description="A liquid template that will be injected into the layout above the message template content."
  />
  <Attribute
    name="settings.attachment_key"
    type="string"
    description="The object path in the data payload (of the workflow trigger call) to resolve attachments."
  />
</Attributes>

#### In-app template attributes

<Attributes>
  <Attribute
    name="markdown_body"
    type="string"
    description="A markdown template for the in-app notification message."
  />
  <Attribute
    name="action_url"
    type="string"
    description="A text template for the URL of the in-app notification message."
  />
</Attributes>

#### SMS template attributes

<Attributes>
  <Attribute
    name="text_body"
    type="string"
    description="A text template for the SMS notification message."
  />
</Attributes>

#### Push template attributes

<Attributes>
  <Attribute
    name="title"
    type="string"
    description="A text template for the push notification message title."
  />
  <Attribute
    name="text_body"
    type="string"
    description="A text template for the push notification message body."
  />
  <Attribute
    name="settings.delivery_type"
    type="string"
    description="The delivery type for the push notification. One of: “content” or “silent”."
  />
  <Attribute
    name="settings.payload_overrides"
    type="string"
    typeSlug="/integrations/push/overview#push-overrides"
    description="A JSON template for any custom overrides to apply to the push notification payload."
  />
</Attributes>

#### Chat template attributes

<Attributes>
  <Attribute
    name="summary"
    type="string"
    description="A text template for the chat notification message summary."
  />
  <Attribute
    name="markdown_body"
    type="string"
    description="A markdown template for the chat notification message body."
  />
  <Attribute
    name="json_body"
    type="string"
    description="A JSON template for the chat notification message payload. Only present if not using the markdown body."
  />
</Attributes>

#### Webhook template attributes

<p className="block text-sm mt-0">
  By default, a webhook step will use the request settings you configured in
  your webhook channel. You can override this as you see fit on a per-step basis
  in the `template` field.
</p>

<Attributes>
  <Attribute
    name="template.method"
    type="string"
    description="An HTTP method of the request. One of: “get”, “post”, “put”."
  />
  <Attribute
    name="template.url"
    type="string"
    description="A URL of the request."
  />
  <Attribute
    name="template.body"
    type="string"
    description="A body of the request. Only used for POST or PUT requests."
  />
  <Attribute
    name="template.headers"
    type="object[]"
    description="A list of key-value pairs for the request headers. Each object should contain key and value fields with string values."
  />
  <Attribute
    name="template.query_params"
    type="object[]"
    description="A list of key-value pairs for the request query params. Each object should contain key and value fields with string values."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Email channel step"
{
  "channel_key": "email-postmark",
  "ref": "email_2",
  "template": {
    "html_body": "<p>Hello world!</p>",
    "settings": {
      "layout_key": "default"
    },
    "subject": "New activity"
  },
  "type": "channel"
}
```

```json title="In-app channel step"
{
  "channel_key": "in-app-feed",
  "description": "Some description",
  "name": "In-app step",
  "ref": "in_app_feed_1",
  "template": {
    "action_url": "{{ vars.app_url }}",
    "markdown_body": "Hello **{{ recipient.name }}**."
  },
  "type": "channel"
}
```

```json title="SMS channel step"
{
  "channel_key": "twilio",
  "ref": "sms_1",
  "template": {
    "text_body": "Hello {{ recipient.name }}."
  },
  "type": "channel"
}
```

```json title="Push channel step"
{
  "channel_key": "fcm",
  "ref": "push_2",
  "template": {
    "settings": {
      "delivery_type": "content"
    },
    "text_body": "Hi {{ actor.name }} completed an activity.",
    "title": "New activity"
  },
  "type": "channel"
}
```

```json title="Chat channel step"
{
  "channel_key": "whatsapp",
  "ref": "chat_2",
  "template": {
    "summary": "A short summary of the message",
    "markdown_body": "Hello **{{ recipient.name }}**."
  },
  "type": "channel"
}
```

</ExampleColumn>
</Section>

<Section title="ChannelSettings definition" slug="channelsettings-definition">
<ContentColumn>

Contains all settings that are applied to a channel integration. Used to override a channel's default settings at the <a href="#channelstep-definition">`ChannelStep`</a> level in a workflow.

#### Chat channel settings attributes

<Attributes>
  <Attribute
    name="link_tracking"
    type="boolean"
    description="Whether to track link clicks on chat notifications."
  />
</Attributes>

#### Email channel settings attributes

<Attributes>
  <Attribute
    name="from_address"
    type="string"
    description="The email address from which this channel will send."
  />
  <Attribute
    name="from_name"
    type="string"
    description="A name to show your recipient in place of an email address."
  />
  <Attribute
    name="reply_to_address"
    type="string"
    description="The Reply-to address on email notifications."
  />
  <Attribute
    name="cc_address"
    type="string"
    description="The Cc address on email notifications."
  />
  <Attribute
    name="bcc_address"
    type="string"
    description="The Bcc address on email notifications."
  />
  <Attribute
    name="link_tracking"
    type="boolean"
    description="Whether to track link clicks on email notifications."
  />
  <Attribute
    name="open_tracking"
    type="boolean"
    description="Whether to track opens on email notifications."
  />
  <Attribute
    name="json_overrides"
    type="string"
    typeSlug="/integrations/email/settings#provider-json-overrides"
    description="A JSON template for any custom overrides to merge into the API payload that is sent to the email provider."
  />
</Attributes>

#### In-app feed channel settings attributes

<Attributes>
  <Attribute
    name="link_tracking"
    type="boolean"
    description="Whether to track link clicks on in-app feed notifications."
  />
</Attributes>

#### SMS channel settings attributes

<Attributes>
  <Attribute
    name="link_tracking"
    type="boolean"
    description="Whether to track link clicks on SMS notifications."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Chat channel settings"
{
  "link_tracking": true
}
```

```json title="Email channel settings"
{
  "from_address": "noreply@example.com",
  "from_name": "Acme",
  "reply_to_address": "support@example.com",
  "cc_address": "cc@example.com",
  "bcc_address": "bcc@example.com",
  "link_tracking": true,
  "open_tracking": true,
  "json_overrides": "{\"custom\": \"value\"}"
}
```

```json title="In-app feed channel settings"
{
  "link_tracking": true
}
```

```json title="SMS channel settings"
{
  "link_tracking": true
}
```

</ExampleColumn>
</Section>

<Section title="SendWindow definition" slug="sendwindow-definition">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="day"
    type="string"
    description="Day of the week. One of: ”monday”, ”tuesday”, ”wednesday”, ”thursday”, ”friday”, ”saturday”, ”sunday”."
  />
  <Attribute
    name="type"
    type="string"
    description="Whether notifications should be sent or not sent for this send window. One of: ”send”, ”do_not_send”."
  />
  <Attribute
    name="from"
    type="string"
    description="An optional ISO-8601 time-only format string specifying the start of the window (defaults to 00:00:00). Only supported if type is set to ”send”."
  />
  <Attribute
    name="until"
    type="string"
    description="An optional ISO-8601 time-only format string specifying the end of the window (defaults to end of day). Only supported if type is set to ”send”."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json Example send window
{
  "day": "monday",
  "type": "send",
  "from": "09:00:00",
  "until": "17:00:00"
}
```

```json Example send window
{
  "day": "tuesday",
  "type": "send",
  "from": "10:15:00"
}
```

```json Example send window
{
  "day": "saturday",
  "type": "do_not_send"
}
```

</ExampleColumn>
</Section>

<Section title="Delay step definition" slug="delay-step-definition">
<ContentColumn>

Contains all properties of the <a href="#workflowstep-definition">`WorkflowStep`</a> and additionally:

### Attributes

Must set either `settings.delay_for` or `settings.delay_until_field_path`.

Use both to describe a <a href="/designing-workflows/delay-function#wait-until-a-relative-timestamp">relative delay</a>.

<Attributes>
  <Attribute
    name="settings.delay_for"
    type="object"
    description="A duration object that describes how long to wait before proceeding to the next step. When used in conjunction with `delay_until_field_path`, describes a delay relative to the specified timestamp."
  />
  <Attribute
    name="settings.delay_for.unit"
    type="string"
    description="One of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”."
  />
  <Attribute
    name="settings.delay_for.value"
    type="number"
    description="The count of units to delay for. Must be a non-negative integer unless used in conjunction with `delay_until_field_path` (where a negative integer describes a relative delay prior to the specified timestamp)."
  />
  <Attribute
    name="settings.delay_until_field_path"
    type="string"
    description="The data path to resolve the delay window. The resolved value must be an ISO-8601 timestamp."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Delay step"
// Delay for 30 seconds
{
  "ref": "delay_1",
  "settings": {
    "delay_for": {
      "unit": "seconds",
      "value": 30
    }
  },
  "type": "delay"
}
```

```json title="Delay step with relative delay"
// Delay until 3 days before the appointment time
{
  "ref": "delay_1",
  "settings": {
    "delay_for": {
      "unit": "days",
      "value": -3
    },
    "delay_until_field_path": "data.appointment_time"
  },
  "type": "delay"
}
```

</ExampleColumn>
</Section>

<Section title="Batch step definition" slug="batch-step-definition">
<ContentColumn>

Contains all properties of the <a href="#workflowstep-definition">`WorkflowStep`</a> and additionally:

### Attributes

Must set either `settings.batch_window` or `settings.batch_until_field_path`.

<Attributes>
  <Attribute
    name="batch_key"
    type="string"
    description="The data property to use to batch notifications per recipient."
  />
  <Attribute
    name="settings.batch_window"
    type="object"
    description="A duration object that describes how long the batch window should be open for."
  />
  <Attribute
    name="settings.batch_window.unit"
    type="string"
    description="One of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”."
  />
  <Attribute
    name="settings.batch_window.value"
    type="number"
    description="A non-negative integer."
  />
  <Attribute
    name="settings.batch_window_type"
    type="string"
    description="The type of the batch window used. One of: “fixed” or “sliding”."
  />
  <Attribute
    name="settings.batch_window_extension_limit"
    type="object"
    description="A duration object that describes the maximum duration a batch window can be extended to from opening when using a sliding batch window."
  />
  <Attribute
    name="settings.batch_window_extension_limit.unit"
    type="string"
    description="One of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”."
  />
  <Attribute
    name="settings.batch_window_extension_limit.value"
    type="number"
    description="A non-negative integer."
  />
  <Attribute
    name="settings.batch_items_max_limit"
    type="number"
    description="The maximum number of batch items allowed in a batch. Between: 2 and 1000."
  />
  <Attribute
    name="settings.batch_until_field_path"
    type="string"
    description="The data path to resolve the batch window. The resolved value must be an ISO-8601 timestamp."
  />
  <Attribute
    name="settings.batch_order"
    type="string"
    description="The order describing whether to return the first or last ten batch items in the activities variable. One of: “asc” or “desc”."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Batch step"
{
  "ref": "batch_1",
  "settings": {
    "batch_order": "asc",
    "batch_window": {
      "unit": "seconds",
      "value": 30
    }
  },
  "type": "batch"
}
```

</ExampleColumn>
</Section>

<Section title="Branch step definition" slug="branch-step-definition">
<ContentColumn>

Contains all properties of the <a href="#workflowstep-definition">`WorkflowStep`</a>, but **cannot have `conditions`** and additionally:

### Attributes

<Attributes>
  <Attribute
    name="branches"
    type="WorkflowBranch[]"
    typeSlug="#workflowbranch-definition"
    description="A list of workflow branches to be evaluated."
  />
</Attributes>

### WorkflowBranch definition

<Attributes>
  <Attribute
    name="steps"
    type="WorkflowStep[]"
    typeSlug="#workflowstep-definition"
    description="A list of steps that will be executed if the branch is chosen."
  />
  <Attribute name="name" type="string" description="The name of the branch." />
  <Attribute
    name="terminates"
    type="boolean"
    description="If the workflow should halt at the end of the branch."
  />
  <Attribute
    name="conditions"
    type="object"
    typeSlug="/concepts/conditions#modeling-conditions"
    description="A set of conditions to be evaluated for this branch."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Branch step"
{
  "ref": "branch_1",
  "branches": [
    {
      "name": "Pro plan",
      "terminates": false,
      "steps": [],
      "conditions": {
        "all": [
          {
            "variable": "recipient.role",
            "operator": "equal_to",
            "argument": "admin"
          }
        ]
      }
    },
    {
      "name": "Default",
      "terminates": false,
      "steps": [],
      "conditions": null
    }
  ],
  "type": "branch"
}
```

</ExampleColumn>
</Section>

<Section title="Fetch step definition" slug="fetch-step-definition">
<ContentColumn>

Contains all properties of the <a href="#workflowstep-definition">`WorkflowStep`</a> and additionally:

### Attributes

<Attributes>
  <Attribute
    name="settings.method"
    type="string"
    description="An HTTP method of the request. One of: “get”, “post”, “put”."
  />
  <Attribute
    name="settings.url"
    type="string"
    description="A URL of the request."
  />
  <Attribute
    name="settings.body"
    type="string"
    description="A body of the request. Only used for POST or PUT requests."
  />
  <Attribute
    name="settings.headers"
    type="object[]"
    description="A list of key-value pairs for the request headers. Each object should contain key and value fields with string values."
  />
  <Attribute
    name="settings.query_params"
    type="object[]"
    description="A list of key-value pairs for the request query params. Each object should contain key and value fields with string values."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="HTTP fetch step"
{
  "ref": "http_fetch_1",
  "settings": {
    "headers": [{ "key": "foo", "value": "bar" }],
    "method": "get",
    "url": "https://example.com/"
  },
  "type": "http_fetch"
}
```

</ExampleColumn>
</Section>

<Section title="List all workflows" slug="workflows-list">
<ContentColumn>

Returns a paginated list of workflows available in a given environment. The workflows are returned in alpha sorted order by its key.

### Endpoint

<Endpoint method="GET" path="/workflows" />

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query workflows."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before."
  />
  <Attribute
    name="limit"
    type="number"
    description="The total number to retrieve per page (defaults to 50, maximum of 100)."
  />
</Attributes>

### Returns

A paginated list of workflows

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "active": false,
      "created_at": "2022-11-07T21:45:43.086960Z",
      "environment": "development",
      "key": "sample-workflow-1",
      "name": "My first sample workflow",
      "steps": [
        {
          "channel_key": "sendgrid",
          "ref": "email_1",
          "template": {
            "html_body": "<p>Hello world!</p>",
            "settings": {
              "layout_key": "default"
            },
            "subject": "Hello world"
          },
          "type": "channel"
        }
      ],
      "updated_at": "2022-12-20T00:31:24.189381Z",
      "valid": true
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a workflow" slug="workflows-get">
<ContentColumn>

Retrieve a workflow by its key and namespace, in a given environment.

### Endpoint

<Endpoint method="GET" path="/workflows/:workflow_key" />

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query workflows."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
</Attributes>

### Returns

A complete workflow

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "active": false,
  "created_at": "2023-02-02T02:52:36.054397Z",
  "environment": "development",
  "key": "sample-workflow-1",
  "name": "My first sample workflow",
  "steps": [
    {
      "channel_key": "sendgrid",
      "ref": "email_1",
      "template": {
        "html_body": "<p>Hello world!</p>",
        "settings": {
          "layout_key": "default"
        },
        "subject": "New activity"
      },
      "type": "channel"
    }
  ],
  "updated_at": "2023-02-06T17:58:51.331103Z",
  "valid": true
}
```

</ExampleColumn>
</Section>

<Section title="Upsert a workflow" slug="workflows-update">
<ContentColumn>

Updates a workflow of a given key, or creates a new one if it does not yet exist.

Note: this endpoint only operates on workflows in the `development` environment.

### Endpoint

<Endpoint method="PUT" path="/workflows/:workflow_key" />

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="commit"
    type="boolean"
    description="Whether to commit the upserted workflow changes in the “development” environment. Set to “false” by default."
  />
  <Attribute
    name="commit_message"
    type="boolean"
    description="An optional message to include in a commit."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="workflow"
    type="Workflow"
    typeSlug="#workflows-object"
    description="A workflow object with attributes to update or create a workflow."
  />
</Attributes>

### Returns

An upserted workflow

</ContentColumn>
<ExampleColumn>

```json title="Response"
// Success
{
  "workflow": {
    "active": false,
    "created_at": "2023-02-02T02:52:36.054397Z",
    "environment": "development",
    "key": "sample-workflow-1",
    "name": "My first sample workflow",
    "steps": [
      {
        "channel_key": "sendgrid",
        "ref": "email_1",
        "template": {
          "html_body": "<p>Hello world!</p>",
          "settings": {
            "layout_key": "default"
          },
          "subject": "New activity"
        },
        "type": "channel"
      }
    ],
    "updated_at": "2023-02-06T17:58:51.331103Z",
    "valid": true
  }
}

// Failure
{
  "errors": [
    {
      "field": "name",
      "message": "must be a string"
    }
  ]
}
```

</ExampleColumn>
</Section>

<Section title="Run a workflow" slug="workflows-run">
<ContentColumn>

Runs the latest version of a saved workflow.

### Endpoint

<Endpoint method="PUT" path="/workflows/:workflow_key/run" />

### Rate limit

<RateLimit tier={2} />

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="The slug of the environment in which to run this workflow. Defaults to development."
  />
  <Attribute
    name="recipients"
    type="string[]"
    description="One or more recipient ids for this workflow run, maximum limit 5."
  />
  <Attribute
    name="data"
    type="string"
    description="A JSON string of the data with which this workflow will run."
  />
  <Attribute
    name="actor"
    type="string"
    description="An optional actor id for this workflow run."
  />
  <Attribute
    name="tenant"
    type="string"
    description="An optional tenant id for this workflow run."
  />
</Attributes>

### Returns

A workflow run ID

</ContentColumn>
<ExampleColumn>

```json title="Response"
// Success
{
  "workflow_run_id": "aa6f6fb8-d8a7-45d2-aa2a-d593764adc92"
}
// Failure
{
  "errors": [
    {
      "field": "recipients",
      "message": "is invalid",
      "type": "cast"
    }
  ],
}
```

</ExampleColumn>
</Section>

<Section title="Validate a workflow" slug="workflows-validate">
<ContentColumn>

Validates a workflow payload without persisting it.

Note: Validating a workflow is only done in the development environment context.

### Endpoint

<Endpoint method="PUT" path="/workflows/:workflow_key/validate" />

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="workflow"
    type="Workflow"
    typeSlug="#workflows-object"
    description="A workflow object with attributes to update or create a workflow."
  />
</Attributes>

### Returns

A validated workflow object, if valid. Note: some read-only fields will be empty as they are generated by the system when persisted.

</ContentColumn>
<ExampleColumn>

```json title="Response"
// Valid
{
  "workflow": {
    "active": null,
    "created_at": null,
    "environment": "development",
    "key": "sample-workflow-1",
    "name": "My first sample workflow",
    "steps": [
      {
        "channel_key": "sendgrid",
        "ref": "email_1",
        "template": {
          "html_body": "<p>Hello world!</p>",
          "settings": {
            "layout_key": "default"
          },
          "subject": "New activity"
          },
        "type": "channel"
      }
    ],
    "updated_at": null,
    "valid": null
  }
}

// Invalid
{
  "errors": [
    {
      "field": "name",
      "message": "must be a string"
    }
  ]
}
```

</ExampleColumn>
</Section>

<Section title="Activate a workflow" slug="workflows-activate">
<ContentColumn>

Activates (or deactivates) a workflow in a given environment.

Note: This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.

### Endpoint

<Endpoint method="PUT" path="/workflows/:workflow_key/activate" />

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
</Attributes>

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description='The environment slug. (Defaults to "development.")'
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="status"
    type="boolean"
    description="Whether to activate or deactivate the upserted workflow changes in the “development” environment. Set to “true” by default, which is to activate. Setting to “false” will deactivate."
  />
</Attributes>

### Returns

`workflow` A workflow object.

</ContentColumn>
<ExampleColumn>

```json title="Response"
// Valid
{
  "workflow": {
    "active": true,
    "created_at": "2023-02-02T02:52:36.054397Z",
    "environment": "development",
    "key": "sample-workflow-1",
    "name": "My first sample workflow",
    "steps": [
      {
        "channel_key": "sendgrid",
        "ref": "email_1",
        "template": {
          "html_body": "<p>Hello world!</p>",
          "settings": {
            "layout_key": "default"
          },
          "subject": "New activity"
        },
        "type": "channel"
      }
    ],
    "updated_at": "2023-02-06T17:58:51.331103Z",
    "valid": true
  }
}
```

</ExampleColumn>
</Section>

<Section title="Preview a workflow template" slug="workflows-preview-template">
<ContentColumn>

Generates a rendered template for a given channel step in a workflow.

### Endpoint

<Endpoint
  method="POST"
  path="/workflows/:workflow_key/steps/:step_ref/preview_template"
/>

### Path parameters

<Attributes>
  <Attribute
    name="workflow_key"
    type="string"
    description="The key of the workflow."
  />
  <Attribute
    name="step_ref"
    type="string"
    typeslug="/mapi#workflowstep-definition"
    description="The reference key of the channel step in the workflow to preview."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description='The environment slug. (Defaults to "development.")'
  />
  <Attribute
    name="recipient"
    type="string"
    description="The id of the recipient."
  />
  <Attribute
    name="actor"
    type="string (optional)"
    description="The id of the actor."
  />
  <Attribute
    name="tenant"
    type="string (optional)"
    description="The id of the tenant."
  />
  <Attribute
    name="data (optional)"
    type="map"
    description="The data to use for the template."
  />
</Attributes>

### Returns

A rendered template or a template error.

</ContentColumn>
<ExampleColumn>

```json title="Request"
{
  "environment": "development",
  "recipient": "user-id",
  "data": {
    "name": "John Doe"
  }
}
```

```json title="Successful response"
{
  "channel_type": "email",
  "result": "success",
  "template": {
    // ... see below
  }
}
```

```json title="Error response"
{
  "channel_type": "email",
  "result": "error",
  "error": {
    // details about the error
  }
}
```

<AccordionGroup>
  <Accordion title="Email template response">
    ```json
    {
      "result": "success",
      "content_type": "email",
      "template": {
        "html_content": "<p>Hello world!</p>",
        "text_content": "Hello world!",
        "subject": "New activity"
      }
    }
    ```
  </Accordion>
  <Accordion title="SMS template response">
    ```json
    {
      "result": "success",
      "content_type": "sms",
      "template": {
        "blocks": [
          {
            "content": "Hello world!",
            "label": null,
            "name": "body",
            "type": "text"
          }
        ]
      }
    }
    ```
  </Accordion>
  <Accordion title="Push template response">
    ```json
    {
      "result": "success",
      "content_type": "sms",
      "template": {
        "blocks": [
          {
            "content": "Hello world!",
            "label": null,
            "name": "body",
            "type": "text"
          }
        ],
        "title": "New activity"
      }
    }
    ```
  </Accordion>
  <Accordion title="Chat template response">
    ```json
    {
      "result": "success",
      "content_type": "chat",
      "template": {
        "blocks": [
          {
            "content": "<p>Hello world!</p>",
            "name": "body",
            "type": "markdown"
          }
        ],
        "json_content": null,
        "summary": "A generated summary"
      }
    }
    ```
  </Accordion>
  <Accordion title="In-app feed template response">
    ```json
    {
      "result": "success",
      "content_type": "in_app_feed",
      "template": {
        "blocks": [
          {
            "content": "Hello world!",
            "name": "body",
            "rendered": "<p>Hello world!</p>",
            "type": "markdown"
          },
          {
            "content": "{{ vars.app_url }}",
            "name": "action_url",
            "rendered": "http://example.com",
            "type": "text"
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

</ExampleColumn>
</Section>

<Section title="Email layouts" slug="email-layouts-overview">
<ContentColumn>

[Email layouts](/integrations/email/layouts) wrap email message templates to share consistent design components between the email notifications that your recipients receive.

You can retrieve, update, and create email layouts as well as listing all in a given [environment](/concepts/environments). Email layouts are identified by their unique key.

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="email-layouts-list"
    method="GET"
    path="/email_layouts"
    withLink
  />
  <Endpoint
    name="email-layouts-get"
    method="GET"
    path="/email_layouts/:key"
    withLink
  />
  <Endpoint
    name="email-layouts-upsert"
    method="PUT"
    path="/email_layouts/:key"
    withLink
  />
  <Endpoint
    name="email-layouts-validate"
    method="PUT"
    path="/email_layouts/:key/validate"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section title="EmailLayout definition" slug="email-layouts-object">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="The unique key for this email layout"
  />
  <Attribute
    name="name"
    type="string"
    description="The friendly name of this email layout"
  />
  <Attribute
    name="html_layout"
    type="string"
    description="The complete HTML content of the email"
  />
  <Attribute
    name="text_layout"
    type="string"
    description="The complete plain text content of the email layout"
  />
  <Attribute
    name="footer_links"
    type="EmailLayoutFooterLink[]"
    typeSlug="#emaillayoutfooterlink-attributes"
    description="A list of one or more items to show in the footer of the email layout."
  />
</Attributes>

### EmailLayoutFooterLink Attributes

<Attributes>
  <Attribute
    name="text"
    type="string"
    description="The text to display as the link"
  />
  <Attribute name="url" type="string" description="The URL to link to" />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Email layout object"
{
  "key": "default",
  "name": "Default",
  "html_content": "<html>{{ content }}</html>",
  "text_content": "{{ content }}",
  "footer_links": [{ "text": "My link", "url": "https://example.com" }]
}
```

</ExampleColumn>
</Section>

<Section title="List all email layouts" slug="email-layouts-list">
<ContentColumn>

Returns a paginated list of email layouts available in a given environment.

### Endpoint

<Endpoint method="GET" path="/email_layouts" />

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before."
  />
  <Attribute
    name="limit"
    type="number"
    description="The total number to retrieve per page (defaults to 50, maximum of 100)."
  />
</Attributes>

### Returns

A paginated list of email layouts

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "key": "default",
      "name": "Default",
      "html_content": "<html>{{ content }}</html>",
      "text_content": "{{ content }}",
      "footer_links": [{ "text": "My link", "url": "https://example.com" }]
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get an email layout" slug="email-layouts-get">
<ContentColumn>

Retrieve an email layout by its key, in a given environment.

### Endpoint

<Endpoint method="GET" path="/email_layouts/:key" />

### Path parameters

<Attributes>
  <Attribute
    name="key"
    type="string"
    description="The key of the email layout."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query translations."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
</Attributes>

### Returns

An email layout object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "default",
  "name": "Default",
  "html_content": "<html>{{ content }}</html>",
  "text_content": "{{ content }}",
  "footer_links": [{ "text": "My link", "url": "https://example.com" }]
}
```

</ExampleColumn>
</Section>

<Section title="Upsert an email layout" slug="email-layouts-upsert">
<ContentColumn>

Updates an email layout, or creates a new one if it does not yet exist.

Note: this endpoint only operates in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/email_layouts/:key" />

### Path parameters

<Attributes>
  <Attribute name="key" type="string" description="The email layout key." />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="commit"
    type="boolean"
    description="Whether to commit the upserted email layout changes in the “development” environment."
  />
  <Attribute
    name="commit_message"
    type="string"
    description="An optional message to include in a commit."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="email_layout"
    type="EmailLayout"
    typeSlug="#email-layouts-object"
    description="An email layout object with a content attribute used to update or create an email layout."
  />
</Attributes>

### Returns

An email layout.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "default",
  "name": "Default",
  "html_content": "<html>{{ content }}</html>",
  "text_content": "{{ content }}",
  "footer_links": [{ "text": "My link", "url": "https://example.com" }]
}
```

</ExampleColumn>
</Section>

<Section title="Validate an email layout" slug="email-layouts-validate">
<ContentColumn>

Validates an email layout payload without persisting it.

Note: this endpoint only operates in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/email_layouts/:key/validate" />

### Path parameters

<Attributes>
  <Attribute name="key" type="string" description="The email layout key." />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="email_layout"
    type="EmailLayout"
    typeSlug="#email-layouts-object"
    description="An email layout object to validate."
  />
</Attributes>

### Returns

An email layout

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "default",
  "name": "Default",
  "html_content": "<html>{{ content }}</html>",
  "text_content": "{{ content }}",
  "footer_links": [{ "text": "My link", "url": "https://example.com" }]
}
```

</ExampleColumn>
</Section>

<Section title="Translations" slug="translations-overview">
<ContentColumn>

[Translations](/concepts/translations) support localization in Knock. They hold the translated content for a given locale, which you can reference in your message templates with the `t` Liquid function filter.

You can retrieve, update, and create translations as well as list all translations in a given [environment](/concepts/environments). Translations are identified by their locale code + an optional namespace.

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint
    name="translations-list"
    method="GET"
    path="/translations"
    withLink
  />
  <Endpoint
    name="translations-get"
    method="GET"
    path="/translations/:locale_code"
    withLink
  />
  <Endpoint
    name="translations-upsert"
    method="PUT"
    path="/translations/:locale_code"
    withLink
  />
  <Endpoint
    name="translations-validate"
    method="PUT"
    path="/translations/:local_code/validate"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section title="Translation definition" slug="translations-object">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="locale_code"
    type="string"
    description="The locale code for the translation object."
  />
  <Attribute
    name="namespace"
    type="string"
    description="An optional namespace for the translation to help categorize your translations."
  />
  <Attribute
    name="content"
    type="string"
    description="A string containing the key-value pairs of translation references and translation strings."
  />
  <Attribute
    name="format"
    type="string"
    description="Indicates whether content is a JSON encoded object string or a string in the PO format."
  />
  <Attribute
    name="inserted_at"
    type="timestamp"
    description="A timestamp of when the translation was created."
  />
  <Attribute
    name="updated_at"
    type="timestamp"
    description="A timestamp of when the translation was updated."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Translation object"
{
  "content": "{\"welcome\":\"Hello, {{ name }}\"}",
  "created_at": "2023-05-08T02:10:29.880485Z",
  "environment": "development",
  "format": "json",
  "locale_code": "en-CA",
  "updated_at": "2023-05-08T02:10:29.880961Z"
}
```

</ExampleColumn>
</Section>

<Section title="List all translations" slug="translations-list">
<ContentColumn>

Returns a paginated list of translations available in a given environment. The translations are returned in alpha-sorted order by locale code.

### Endpoint

<Endpoint method="GET" path="/translations" />

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query translations."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="format"
    type="string"
    description="Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'."
  />
  <Attribute
    name="locale_code"
    type="string"
    description="A specific locale code to filter translations for."
  />
  <Attribute
    name="namespace"
    type="string"
    description="A specific namespace to filter translations for."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before."
  />
  <Attribute
    name="limit"
    type="number"
    description="The total number to retrieve per page (defaults to 50, maximum of 100)."
  />
</Attributes>

### Returns

A paginated list of translations

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "content": "{\"welcome\":\"Hello, {{ name }}\"}",
      "created_at": "2023-05-08T02:10:29.880485Z",
      "environment": "development",
      "format": "json",
      "locale_code": "en-CA",
      "updated_at": "2023-05-08T02:10:29.880961Z"
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a translation" slug="translations-get">
<ContentColumn>

Retrieve a translation by its locale and namespace, in a given environment.

### Endpoint

<Endpoint method="GET" path="/translations/:locale_code" />

### Path parameters

<Attributes>
  <Attribute
    name="locale_code"
    type="string"
    description="A locale code to retrieve translations for."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query translations."
  />
  <Attribute
    name="format"
    type="string"
    description="Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="namespace"
    type="string"
    description="A specific namespace to filter translations for."
  />
</Attributes>

### Returns

A translation object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "content": "{\"welcome\":\"Hello, {{ name }}\"}",
  "created_at": "2023-05-08T02:10:29.880485Z",
  "environment": "development",
  "format": "json",
  "locale_code": "en-CA",
  "updated_at": "2023-05-08T02:10:29.880961Z"
}
```

</ExampleColumn>
</Section>

<Section title="Upsert a translation" slug="translations-upsert">
<ContentColumn>

Updates a translation of a given locale code + namespace, or creates a new one if it does not yet exist.

Note: this endpoint only operates on translations in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/translations/:locale_code" />

### Path parameters

<Attributes>
  <Attribute
    name="locale_code"
    type="string"
    description="A locale code for the translation."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="namespace"
    type="string"
    description="An optional namespace that identifies the translation."
  />
  <Attribute
    name="commit"
    type="boolean"
    description="Whether to commit the upserted translation’s changes in the “development” environment."
  />
  <Attribute
    name="commit_message"
    type="string"
    description="An optional message to include in a commit."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="translation"
    type="Translation"
    typeSlug="#translations-object"
    description="A translation object with a content attribute used to update or create a translation."
  />
</Attributes>

### Returns

A translation object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "content": "{\"welcome\":\"Hello, {{ name }}\"}",
  "created_at": "2023-05-08T02:10:29.880485Z",
  "environment": "development",
  "locale_code": "en-CA",
  "format": "json",
  "updated_at": "2023-05-08T02:10:29.880961Z"
}
```

</ExampleColumn>
</Section>

<Section title="Validate a translation" slug="translations-validate">
<ContentColumn>

Validates a translation payload without persisting it.

Note: this endpoint only operates on translations in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/translations/:locale_code/validate" />

### Path parameters

<Attributes>
  <Attribute
    name="locale_code"
    type="string"
    description="A locale code of the translation."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="translation"
    type="Translation"
    typeSlug="#translations-object"
    description="A translation object to validate."
  />
</Attributes>

### Returns

A translation object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "content": "{\"welcome\":\"Hello, {{ name }}\"}",
  "created_at": "2023-05-08T02:10:29.880485Z",
  "environment": "development",
  "locale_code": "en-CA",
  "format": "json",
  "updated_at": "2023-05-08T02:10:29.880961Z"
}
```

</ExampleColumn>
</Section>

<Section title="Partials" slug="partials-overview">
<ContentColumn>

[Partials](/designing-workflows/partials) are reusable pieces of content you can use across your channel templates.

You can retrieve, update, and create partials as well as list all partials in a given [environment](/concepts/environments). Partials are identified by their unique partial key.

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="partials-list" method="GET" path="/partials" withLink />
  <Endpoint
    name="partials-get"
    method="GET"
    path="/partials/:partial_key"
    withLink
  />
  <Endpoint
    name="partials-upsert"
    method="PUT"
    path="/partials/:partial_key"
    withLink
  />
  <Endpoint
    name="partials-validate"
    method="PUT"
    path="/partials/:local_code/validate"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section title="Partial definition" slug="partials-object">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="key"
    type="string (mutable only at creation)"
    description="The unique key string for the partial object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$."
  />
  <Attribute
    name="type"
    type="string (mutable only at creation)"
    description="The partial type. One of 'html', 'json', 'markdown', 'text'."
  />
  <Attribute
    name="name"
    type="string"
    description="A name for the partial. Must be at maximum 255 characters in length."
  />
  <Attribute
    name="description"
    type="string"
    description="An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed."
  />
  <Attribute
    name="visual_block_enabled"
    type="boolean"
    description="Indicates whether the partial can be used in the visual editor. Only applies to HTML partials."
  />
  <Attribute
    name="environment"
    type="string (read-only)"
    description="The slug of the environment in which the partial exists."
  />
  <Attribute
    name="icon_name"
    type="string"
    description="The name of the icon to be used in the visual editor."
  />
  <Attribute name="content" type="string" description="The partial content." />
  <Attribute
    name="created_at"
    type="timestamp (read-only)"
    description="A timestamp of when the partial was created."
  />
  <Attribute
    name="updated_at"
    type="timestamp (read-only)"
    description="A timestamp of when the partial was updated."
  />
  <Attribute
    name="valid"
    type="boolean (read-only)"
    description="Whether the partial and its content are in a valid state."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Partial object"
{
  "key": "cta",
  "type": "html",
  "name": "Call to action",
  "description": "Call to action",
  "visual_block_enabled": false,
  "environment": "development",
  "icon_name": "BellDot",
  "content": "<div>{{heading}}<button>{{cta}}</button></div>",
  "created_at": "2022-12-31T12:00:00.000000Z",
  "updated_at": "2022-12-31T12:00:00.000000Z",
  "valid": false
}
```

</ExampleColumn>
</Section>

<Section title="List all partials" slug="partials-list">
<ContentColumn>

Returns a paginated list of partials available in a given environment. The partials are returned in alpha-sorted order by key.

### Endpoint

<Endpoint method="GET" path="/partials" />

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query partials."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before."
  />
  <Attribute
    name="limit"
    type="number"
    description="The total number to retrieve per page (defaults to 50, maximum of 100)."
  />
</Attributes>

### Returns

A paginated list of partials

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "key": "cta",
      "type": "html",
      "name": "Call to action",
      "description": "Call to action",
      "visual_block_enabled": false,
      "environment": "development",
      "icon_name": "BellDot",
      "content": "<div>{{heading}}<button>{{cta}}</button></div>",
      "created_at": "2022-12-31T12:00:00.000000Z",
      "updated_at": "2022-12-31T12:00:00.000000Z",
      "valid": false
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get a partial" slug="partials-get">
<ContentColumn>

Retrieve a partial by its locale and namespace, in a given environment.

### Endpoint

<Endpoint method="GET" path="/partials/:partial_key" />

### Path parameters

<Attributes>
  <Attribute
    name="partial_key"
    type="string"
    description="The key of the partial to retrieve."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query partials."
  />
  <Attribute
    name="hide_uncommitted_changes"
    type="boolean"
    description="Whether to hide saved but uncommitted changes. Only relevant for “development” environment."
  />
  <Attribute
    name="namespace"
    type="string"
    description="A specific namespace to filter partials for."
  />
</Attributes>

### Returns

A partial object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "cta",
  "type": "html",
  "name": "Call to action",
  "description": "Call to action",
  "visual_block_enabled": false,
  "environment": "development",
  "icon_name": "BellDot",
  "content": "<div>{{heading}}<button>{{cta}}</button></div>",
  "created_at": "2022-12-31T12:00:00.000000Z",
  "updated_at": "2022-12-31T12:00:00.000000Z",
  "valid": false
}
```

</ExampleColumn>
</Section>

<Section title="Upsert a partial" slug="partials-upsert">
<ContentColumn>

Updates a partial of a given key, or creates a new one if it does not yet exist.

Note: this endpoint only operates on partials in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/partials/:partial_key" />

### Path parameters

<Attributes>
  <Attribute
    name="partial_key"
    type="string"
    description="A partial key for the partial."
  />
</Attributes>

### Query parameters

<Attributes>
  <Attribute
    name="commit"
    type="boolean"
    description="Whether to commit the upserted partial’s changes in the “development” environment."
  />
  <Attribute
    name="commit_message"
    type="string"
    description="An optional message to include in a commit."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="partial"
    type="Partial"
    typeSlug="#partials-object"
    description="A partial object with attributes to update or create a partial."
  />
</Attributes>

### Returns

A partial object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "cta",
  "type": "html",
  "name": "Call to action",
  "description": "Call to action",
  "visual_block_enabled": false,
  "environment": "development",
  "icon_name": "BellDot",
  "content": "<div>{{heading}}<button>{{cta}}</button></div>",
  "created_at": "2022-12-31T12:00:00.000000Z",
  "updated_at": "2022-12-31T12:00:00.000000Z",
  "valid": false
}
```

</ExampleColumn>
</Section>

<Section title="Validate a partial" slug="partials-validate">
<ContentColumn>

Validates a partial payload without persisting it.

Note: this endpoint only operates on partials in the “development” environment.

### Endpoint

<Endpoint method="PUT" path="/partials/:partial_key/validate" />

### Path parameters

<Attributes>
  <Attribute
    name="partial_key"
    type="string"
    description="A partial key of the partial."
  />
</Attributes>

### Body parameters

<Attributes>
  <Attribute
    name="partial"
    type="Partial"
    typeSlug="#partials-object"
    description="A partial object to validate."
  />
</Attributes>

### Returns

A partial object

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "key": "cta",
  "type": "html",
  "name": "Call to action",
  "description": "Call to action",
  "visual_block_enabled": false,
  "environment": "development",
  "icon_name": "BellDot",
  "content": "<div>{{heading}}<button>{{cta}}</button></div>",
  "created_at": "2022-12-31T12:00:00.000000Z",
  "updated_at": "2022-12-31T12:00:00.000000Z",
  "valid": false
}
```

</ExampleColumn>
</Section>

<Section title="Commits" slug="commits-overview">
<ContentColumn>

To version the changes you make in your environments, Knock uses a commit model. When you make changes to a workflow, a layout, or a translation, you will need to commit them in your development environment, then promote to subsequent environments before those changes will appear in the respective environments.

You can retrieve all commits in a given environment, or show the details of one single commit based on the target commit id.

</ContentColumn>
<ExampleColumn>

<Endpoints>
  <Endpoint name="commits-list" method="GET" path="/commits" withLink />
  <Endpoint name="commits-get" method="GET" path="/commits/:id" withLink />
  <Endpoint name="commits-commit" method="PUT" path="/commits" withLink />
  <Endpoint
    name="commits-promote-all"
    method="PUT"
    path="/commits/promote"
    withLink
  />
  <Endpoint
    name="commits-promote-one"
    method="PUT"
    path="/commits/:id/promote"
    withLink
  />
</Endpoints>

</ExampleColumn>
</Section>

<Section title="Commit definition" slug="commits-object">
<ContentColumn>

### Attributes

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The unique id for this commit."
  />
  <Attribute
    name="resource"
    type="CommitResource"
    typeSlug="#commitresource-attributes"
    description="The resource object associated with the commit."
  />
  <Attribute
    name="author"
    type="CommitAuthor"
    typeSlug="#commitauthor-attributes"
    description="The author responsible for the commit."
  />
  <Attribute
    name="commit_message"
    type="string"
    description="The optional message about the commit."
  />
  <Attribute
    name="environment"
    type="string"
    description="The environment where the commit was made."
  />
  <Attribute
    name="created_at"
    type="timestamp"
    description="A timestamp of when the commit was created."
  />
</Attributes>

### CommitResource attributes

<Attributes>
  <Attribute
    name="identifier"
    type="string"
    description="The unique identifier for the resource."
  />
  <Attribute
    name="type"
    type="string"
    description="The type of the resource object."
  />
</Attributes>

### CommitAuthor attributes

<Attributes>
  <Attribute
    name="email"
    type="string"
    description="The email address of the commit author."
  />
  <Attribute
    name="name"
    type="string"
    description="The name of the commit author."
  />
</Attributes>

</ContentColumn>
<ExampleColumn>

```json title="Commit object"
{
  "id": "ce3e5457-34f2-4f53-94a2-2f316528d83f",
  "resource": {
    "identifier": "default",
    "type": "email_layout"
  },
  "author": {
    "email": "John@gmail.com",
    "name": "John Doe"
  },
  "commit_message": "Initial email layout",
  "environment": "development",
  "created_at": "2023-09-22T18:57:21.704602Z"
}
```

</ExampleColumn>
</Section>

<Section title="List all commits" slug="commits-list">
<ContentColumn>

Returns a paginated list of commits in a given environment. The commits are ordered from most recent first.

### Endpoint

<Endpoint method="GET" path="/commits" />

### Query parameters

<Attributes>
  <Attribute
    name="environment"
    type="string"
    description="A slug of the environment from which to query commits."
  />
  <Attribute
    name="promoted"
    type="boolean"
    description="Whether to show only promoted or unpromoted changes between the given environment and the subsequent environment."
  />
  <Attribute
    name="after"
    type="string"
    description="The cursor to retrieve items after."
  />
  <Attribute
    name="before"
    type="string"
    description="The cursor to retrieve items before."
  />
  <Attribute
    name="limit"
    type="number"
    description="The total number to retrieve per page (defaults to 50, maximum of 100)."
  />
</Attributes>

### Returns

A paginated list of commits

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "entries": [
    {
      "id": "ce3e5457-34f2-4f53-94a2-2f316528d83f",
      "resource": {
        "identifier": "default",
        "type": "email_layout"
      },
      "author": {
        "email": "John@gmail.com",
        "name": "John Doe"
      },
      "commit_message": "Initial email layout",
      "environment": "development",
      "created_at": "2023-09-22T18:57:21.704602Z"
    },
    {
      "id": "e4a22631-e05e-4d40-b323-4dc327c0670e",
      "resource": {
        "identifier": "new-comment",
        "type": "workflow"
      },
      "author": {
        "email": "franklin@gmail.com",
        "name": "Franklin Sierra"
      },
      "environment": "development",
      "created_at": "2023-11-13T19:28:25.090196Z"
    }
  ],
  "page_info": {
    "after": null,
    "before": null,
    "page_size": 50
  }
}
```

</ExampleColumn>
</Section>

<Section title="Get commit" slug="commits-get">
<ContentColumn>

Retrieve a single commit by its id.

### Endpoint

<Endpoint method="GET" path="/commits/:id" />

### Path parameters

<Attributes>
  <Attribute name="id" type="string" description="The id of the commit." />
</Attributes>

### Returns

A complete commit.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "id": "ce3e5457-34f2-4f53-94a2-2f316528d83f",
  "resource": {
    "identifier": "default",
    "type": "email_layout"
  },
  "author": {
    "email": "John@gmail.com",
    "name": "John Doe"
  },
  "commit_message": "Initial email layout",
  "environment": "development",
  "created_at": "2023-09-22T18:57:21.704602Z"
}
```

</ExampleColumn>
</Section>

<Section title="Commit all changes" slug="commits-commit">
<ContentColumn>

Commit all changes across all resources in the development environment.

### Endpoint

<Endpoint method="PUT" path="/commits" />

### Query parameters

<Attributes>
  <Attribute
    name="commit_message"
    type="string"
    description="An optional message to include in a commit."
  />
</Attributes>

### Returns

`result` A "success" message.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "result": "success"
}
```

</ExampleColumn>
</Section>

<Section title="Promote all changes" slug="commits-promote-all">
<ContentColumn>

Promote all changes across all resources to the target environment from its preceding environment.

### Endpoint

<Endpoint method="PUT" path="/commits/promote" />

### Query parameters

<Attributes>
  <Attribute
    name="to_environment"
    type="string"
    description={
      <>
        <p>A slug of the target environment to which you want to promote all changes from its directly preceding environment.</p>
        <p>For example, if you have three environments “development”, “staging”, and “production” (in that order), setting this param to “production” will promote all new changes from the staging environment.</p>
        <p><strong>Note:</strong> This must be a non-development environment.</p>
      </>
    }
/>

</Attributes>

### Returns

`result` A "success" message.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "result": "success"
}
```

</ExampleColumn>
</Section>

<Section title="Promote one change" slug="commits-promote-one">
<ContentColumn>

Promotes one change to the subsequent environment.

### Endpoint

<Endpoint method="PUT" path="/commits/:id/promote" />

### Query parameters

<Attributes>
  <Attribute
    name="id"
    type="string"
    description="The target commit id to promote to the subsequent environment."
  />
</Attributes>

### Returns

A promoted commit.

</ContentColumn>
<ExampleColumn>

```json title="Response"
{
  "commit": {
    "id": "e4a22631-e05e-4d40-b323-4dc327c0670e",
    "resource": {
      "identifier": "new-comment",
      "type": "workflow"
    },
    "author": {
      "email": "franklin@gmail.com",
      "name": "Franklin Sierra"
    },
    "environment": "staging"
  }
}
```

</ExampleColumn>
</Section>