# Add a new provider (/community/add-a-new-provider)

Steps to add a new provider to Novu

Interested in expanding Novu's capabilities? By contributing to our growing ecosystem, you can enhance Novu's reach and impact.

## How to add a new provider?

Novu currently supports five channels `in_app`, `push`, `email`, `chat` and `sms`.

For `in_app` we support only our own provider, so new providers cannot be added to this channel. For the other four channels, we support the integration of external providers. This guide will help in adding new providers for any of these 4 channels.

In this guide, we are adding a new provider for the email channel, but all of the mentioned steps are similar for other channels as well.

## Description

Providers allow us to handle message delivery over multiple channels.

We have multiple providers for each channel (SMS, Email, Push and Chat). To get started with adding a new provider let's look at setting up our repository.

## Requirements

* Node.js version v20.8.1
* MongoDB
* Redis
* **(Optional)** pnpm - Needed if you want to install new packages
* **(Optional)** localstack (required only in S3 related modules)

Need help installing the requirements? [Read more here](/community/run-in-local-machine)

<Callout type="info">
  We have used pnpm package manager in this guide. You can use npm as well.
</Callout>

## Initialization

Fork the novu repository and clone it in your local machine.

```shell
git clone https://github.com/<'YOUR_GITHUB_USER_NAME'>/novu.git
```

To set up the repository, run the initial setup command:

```shell
pnpm run setup:project
```

## Generate provider

After the project is initialized, a new provider can be generated using the below command.

```shell
pnpm run generate:provider
```

<Callout type="info">Use the above command at the root of the project.</Callout>

Choose the provider type.

```shell
? What type
❯ EMAIL
  SMS
  PUSH
  CHAT
```

Use `up` and `down` arrow to switch `channel` type and press `enter` to select.

For this example, we will be selecting `EMAIL` as our provider type. The name for our provider will be `example-provider`.

```
? Write the provider name`kebab-cased` (e.g. proton-mail, outlook365, yahoo-mail): example-provider
```

Make sure your selected name is not conflicting with our existing provider's name. Boilerplate files for this new `example-provider` is generated in your local machine project.

> In above example, we have given our provider name as example-provider for simplicity. If provider you want to add have name as twilio, don't use twilio-provider as name, instead use twilio only. If one provider supports multiple channels like infobip supports both sms and email channels, use infobip-email or infobip-sms to differentiate these providers.

Once our `example-provider` is generated we will need to begin working from `packages/providers/src/lib/email/example-provider` directory. Make sure to write the test for this new provider.

```typescript
import {
  ChannelTypeEnum,
  ISendMessageSuccessResponse,
  IEmailOptions,
  IEmailProvider,
} from '@novu/stateless';

export class ExampleProviderEmailProvider implements IEmailProvider {
  id = 'example-provider';
  channelType = ChannelTypeEnum.EMAIL as ChannelTypeEnum.EMAIL;

  constructor(
    private config: {
      apiKey: string;
    }
  ) {}

  async sendMessage(options: IEmailOptions): Promise<ISendMessageSuccessResponse> {
    return {
      id: 'id_returned_by_provider',
      date: 'current_time',
    };
  }
}
```

### Template test case for `example-provider`.

```ts packages/providers/src/lib/example-provider/example-provider.provider.sepc.ts
import { ExampleProviderEmailProvider } from './example-provider.provider';

test('should trigger example-provider library correctly', async () => {});
```

## Add provider logos

In order to present this new provider in the `integration store` we need logo in light mode. Add light color svg logo in `apps/dashboard/public/images/providers/light/square` directory.

Use the provider name as the file name. The sample name for our above-added provider is `example-provider.svg`.

## Add config items to the list

In order to build the UI integration store, we need to provide it list of all provider integrations. This part is made up of two parts:

* Create credentials config
* Add ProviderId Enum
* Add provider config to framework
* Add provider configuration to the providers list

### 1. Create credentials config

Every provider requires some credentials to create an instance. Novu will add these credentials fields in the integration store provider's form so that users can use their credentials to connect to their preferred provider to use for that channel notification. For example, in the above added `example-provider`, we have only one credential `ApiKey`. We will need to add a config object for `example-provider` with all existing provider's configs like below.

```ts title="packages/shared/src/consts/providers/credentials/provider-credentials.ts"
export const exampleProviderConfig: IConfigCredentials[] = [
  {
    key: CredentialsKeyEnum.ApiKey,
    displayName: 'API Key',
    description: 'This is API key for example provider',
    type: 'text',
    required: true,
  },
  ...mailConfigBase,
];
```

1. Here the `key` is of type `CredentialsKeyEnum`.

> If a new key is added, add this key at these 3 places:-
>
> * In `CredentialsKeyEnum` at file `packages/shared/src/types/providers.ts`
> * In `ICredentials` at file `packages/shared/src/entities/integration/credential.interface.ts`
> * In `CredentialsDto` at file `apps/api/src/app/integrations/dtos/credentials.dto.ts`
> * In `credentials` field of `integrationSchema` at file `libs/dal/src/repositories/integration/integration.schema.ts`

2. `displayName` is a human-friendly easy to understand name which will be shown in the provider integration form for this credential.
3. `description` is a field that can be used to share more information about the credential.
4. `type` here means text field type. this can be a string for text, text for text-area, or a switch for the toggle.
5. `required` is of boolean type.
6. `mailConfigBase` is an object having default credentials required by any `email` provider. Make sure not to add duplicate providers which are already there in `mailConfigBase`. In the case of another channel provider, we will use that channel config base in place of `mailConfigBase`.

> A credential can be made secret by adding in `./secure-credentials.ts` file.

### 2. Add ProviderId Enum

Add this new provider id in the respective channel provider id enum in file `packages/shared/src/types/providers.ts`. As our `example-provider` is of email type, add this in `EmailProviderIdEnum` with all existing providers like below

```ts title="packages/shared/src/types/providers.ts"
export enum EmailProviderIdEnum {
  ExampleProvider = 'example-provider',
}
```

### 3. Add provider config to framework

* Add provider in `EmailProviderIdEnum` at file `packages/framework/src/shared.ts`

```ts title="packages/framework/src/shared.ts"
export enum EmailProviderIdEnum {
  ExampleProvider = 'example-provider',
}
```

* Add provider schema at `packages/framework/src/schemas/providers/email/index.ts`

```ts title="packages/framework/src/schemas/providers/email/index.ts"

export const emailProviderSchema = {
  'example-provider': genericProviderSchemas,
}
```

### 4. Add provider to providers list

Now we need to add the provider data to the list located at `packages/shared/src/consts/providers/channels/email.ts`. Note that the `id` is the provider's name, `displayName` is the provider's name in Pascal's case, `credentials` are the ones we created in the previous step, `logoFileName` should be as it was on the adding logo step (with the format type included).

```ts title="packages/shared/src/consts/providers/channels/email.ts"
import { exampleProviderConfig } from '../credentials';

export const emailProviders: IProvider[] = [
  {
    id: 'example-provider',
    displayName: 'Example Provider',
    channel: ChannelTypeEnum.EMAIL,
    credentials: exampleProviderConfig,
    // Use valid documentation link
    docReference: 'https://docs.example-provider.com/',
    logoFileName: { light: 'example-provider.svg', dark: 'example-provider.svg' },
  },
];
```

## Add provider handler in the API

### 1. Create a provider handler

In order to map internally the different providers' credentials, we need to add a provider handler at the respective channel handlers located. For Email, it can be found at `libs/application-generic/src/factories/mail/handlers`. Other channel handlers can also be found here.

Create a new file `example-provider.handler.ts` here with the following code

```tsx libs/application-generic/src/factories/mail/handlers/example-provider.handler.ts
import { ChannelTypeEnum, EmailProviderIdEnum } from '@novu/shared';
import { ExampleProviderEmailProvider } from '@novu/providers';
import { BaseHandler } from './base.handler';

export class ExampleProviderHandler extends BaseHandler {
  constructor() {
    super(EmailProviderIdEnum.ExampleProvider, ChannelTypeEnum.EMAIL);
  }

  buildProvider(credentials, from: string) {
    const config: { apiKey: string } = { apiKey: credentials.apiKey };

    this.provider = new ExampleProviderEmailProvider(config);
  }
}
```

Add this line given below to export this handler

```tsx libs/application-generic/src/factories/mail/handlers/index.ts
export * from './example-provider.handler';
```

### 2. Add handler to factory

The last step is to initialize the handler in the factory located in `libs/application-generic/src/factories/mail/mail.factory.ts`

```tsx libs/application-generic/src/factories/mail/mail.factory.ts
import { ExampleProviderHandler } from './handlers';

export class MailFactory {
  handlers: IMailHandler[] = [new ExampleProviderHandler()];
}
```

### Final Steps

Now, build the project again using this command

```shell
pnpm run setup:project
```

Run novu in your local machine. Read [here](/community/run-in-local-machine) to learn on how to run novu on a local machine and test this new provider.

Run the below command in the root of the project to run the providers test

```shell
pnpm run test:providers
```

If everything is working fine without any error, commit your local branch changes, push this branch and create a new pull request to our main repo.

Hurray 🎉! You have successfully added a new provider in Novu!

<Callout type="info">
  In this guide, we have used only one credential `apiKey` for our `example-provider`. This is for reference purposes only. A provider can have more than one credential as per its `SDK` requirements. At each step, you will need to add all credentials carefully. Check providers references below for more information.
</Callout>

### Reference for Adding New Providers

* [SendGrid Email Provider](https://github.com/novuhq/novu/blob/next/packages/providers/src/lib/email/sendgrid/sendgrid.provider.ts)
* [Twilio SMS Provider](https://github.com/novuhq/novu/blob/next/packages/providers/src/lib/sms/twilio/twilio.provider.ts)
* [FCM Push Provider](https://github.com/novuhq/novu/blob/next/packages/providers/src/lib/push/fcm/fcm.provider.ts)
* [Slack Chat Provider](https://github.com/novuhq/novu/blob/next/packages/providers/src/lib/chat/slack/slack.provider.ts)


# Changelog (/community/changelog)

See the most recent changes and learn about how to shape Novu's future

import { Card, Cards } from 'fumadocs-ui/components/card';
import { MapIcon } from 'lucide-react';

<Cards>
  <Card title="Novu's Changelog" icon={<MapIcon className="w-4 h-4" />} href="https://go.novu.co/changelog?utm_source=docs">
    Learn about what's changed, new features, bug fixes, and see Novu's history across versions.
  </Card>
</Cards>

Using the changelog, you can:

* Keep an eye on the latest updates,
* Learn more about the newly added features and improvements, and
* Stay informed about bug fixes and enhancement

## Getting involved:

Community is at the heart of everything we do at Novu. To get more involved with the community, you can:

* **Fork and Contribute** to our open issues as well as suggest new ideas at our [github repository](https://github.com/novuhq/novu)
* **Join our community** to ask questions, engage with other users and share ideas. Here's the [joining link.](https://discord.gg/novu?ref=docs-join-our-community)
* **Participate in our office hours** to learn more and connect with our core team. Join us [here.](https://www.youtube.com/@novuhq/streams)

<Callout type="info">
  Remember, we're not building just another product, but a community of passionate developers who
  shape its evolution. Our changelog isn't just a list of updates but a reflection of our journey
  together. Your voice matters, and your ideas and feedback are what fuel our progress and shape our
  future. So, join us in this adventure, and – Let's build something amazing, one feature at a time!
</Callout>


# Novu Community Code of conduct (/community/code-of-conduct)

The set of rules and guidelines that govern interaction among community members

As a community-driven company, Novu is committed to creating an inclusive and welcoming environment for all members, regardless of factors such as age, body size, disability, ethnicity, gender identity, experience level, education, socio-economic status, nationality, personal appearance, race, religion, or sexual orientation.

However, diverse communities may face challenges, such as potential misunderstandings and miscommunications. To ensure respectful interactions, free from behaviour that may create an unsafe environment, we have established this Code of Conduct.

These guidelines do not cover every possible scenario comprehensively but serve as a guiding light towards courteous interactions among community members, aligning with the overarching principle of avoiding unprofessional behaviour. This Code of Conduct applies to all events and participants, aiming to maintain a welcoming and healthy environment for our community.

Traits of a Novu community member include:

## Being considerate and using appropriate channels

Contributions of every kind have far-ranging consequences. Just as your work depends on the work of others, decisions you make surrounding your contributions to the Novu community will affect your fellow community members. Use appropriate channels for what you're about to say and refrain from tagging a role that sends out a lot of pings. You are strongly encouraged to take those consequences into account while making decisions.

## Adhering to these standards

It's crucial to keep in mind that our community members are from all kinds of backgrounds, so the members are expected to:

* Demonstrate empathy and kindness toward other people
* Be respectful of differing opinions, viewpoints, and experiences
* Give and accept constructive feedback gracefully
* Accept responsibility and apologise to those affected by mistakes, and learn from such experiences
* Focus on what is best not just for us as individuals, but for the overall community!

## Patience

Our community thrives on the generosity of volunteered time. Questions, contributions, and support requests may embark on a time-travelling journey before finding their destination. Repeated "bumps" or persistent "reminders" don't display patience and are looked down upon. Lastly, it is a bad practice to ask general questions to a specific person (in direct messages for example). Try to ask in public as much as you can, and patiently wait for the response

## Inclusivity, kindness and respectfulness

Please be courteous and respectful to fellow members. Avoid offensive comments related to age, body size, disability, ethnicity, gender identity, experience level, education, socio-economic status, nationality, personal appearance, race, religion, or sexual orientation.

Strictly prohibited are sexualized imagery, violence, intimidation, stalking, disruptions, sharing personal information without explicit permission, unwanted physical contact, and unwelcome sexual attention.

Use inclusive language respecting our community's diversity.

Avoid assumptions about others' backgrounds. Maintain a positive and professional demeanour, refraining from threatening or inappropriate behaviour.

**We have zero tolerance for discrimination**. Any form of discrimination, including harassment, will lead to immediate consequences, potentially expulsion.

## Inquisitive

***The only stupid question is the one that does not get asked***.

We encourage our users to ask early and ask often. Rather than asking whether you can ask a question (the answer is always yes!), instead, simply ask your question. You are encouraged to provide as many specifics as possible.

Code snippets in the form of images are bad practice. Instead, use text formatted as code (using backticks) on Discord or simply send a gist. Refrain from pasting multiple lines of code directly into the chat channels - instead use [gist.github.com](https://gist.github.com/) or another paste site to provide code snippets.

## Helpful

Novu welcomes users of all skill levels. We were all beginners once, and a supportive environment is essential for the community to thrive. While it can be repetitive to answer the same questions, members are expected to be courteous and helpful to everyone.

Avoid sarcastic responses and prioritize useful information. Everyone should read the provided documentation. We're here to answer questions, offer guidance, and suggest workflows, but not to do your job for you.

## Anti-harassment policy

Harassment includes (but is not limited to) all of the following behaviors:

* Offensive comments related to gender (including gender expression and identity), age, sexual orientation, disability, physical appearance, body size, race, and religion.
* Derogatory terminology including words commonly known to be slurs
* Posting sexualized images or imagery in public spaces
* Deliberate intimidation
* Stalking
* Posting others' personal information without explicit permission
* Sustained disruption of talks or other events
* Inappropriate physical contact
* Unwelcome sexual attention

Immediate compliance is expected from participants asked to cease harassing behaviour. Sponsors must adhere to the anti-harassment policy, refraining from using sexualized images or creating a sexualized environment at events. Volunteer organizers, including meetup staff, should also avoid sexualized attire.

Continuing inappropriate behaviour after being asked to stop constitutes harassment, even if not explicitly mentioned in this policy. It is respectful to stop doing something when asked to do so, and all community members are expected to promptly comply with such requests.

## Reporting policy violations

Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to anyone with administrative power in the community (Admins or Moderators on Discord, members of the 'DevRel' role), or to the local organizers of an event or to [support@novu.co](mailto:support@novu.co). Meetup organizers are encouraged to prominently display points of contact for reporting unacceptable behaviour at local events.

If a participant engages in harassing behaviour, the meetup organizers may take any action they deem appropriate. These actions may include but are not limited to warning the offender, expelling the offender from the event, and barring the offender from future community events.

Organizers will be happy to help participants contact security or local law enforcement, provide escorts to an alternate location, or otherwise assist those experiencing harassment to feel safe during the meetup. We value the safety and well-being of our community members and want everyone to feel welcome at our events, both online and offline.

We expect all participants, organizers, speakers, and attendees to follow these policies at all of our event venues and event-related social events.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. **Correction**

* `Community Impact`: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome in the community.
* `Consequence`: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested.

2. **Warning**

* `Community Impact`: A violation through a single incident or series of actions.
* `Consequence`: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. **Temporary Ban**

* `Community Impact`: A serious violation of community standards, including sustained inappropriate behaviour.
* `Consequence`: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. **Permanent Ban**

* `Community Impact`: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals.
* `Consequence`: A permanent ban from any sort of public interaction within the community.

The Novu Community Code of Conduct is licensed under the Creative Commons Attribution-Share Alike 3.0 license.

Our Code of Conduct was adapted from Codes of Conduct of other open-source projects, including:

* **Contributor Covenant**
* **Elastic**
* **The Fedora Project**
* **OpenStack**
* **Ansible**
* **Puppet Labs**
* **Ubuntu**

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).

Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).


# Feature Flags (/community/feature-flags)

Learn how to enable/disable specific features in Novu

Feature flags allow to turn certain functionality on and off based on configuration. In this way, users can preview beta features in their deployments.

To enable the specific feature, you need to pass an environment variable to all services:

<Callout type="info">
  Feature flag environment variable accepts boolean values: `true` or `false`.
</Callout>

* `IS_MULTI_PROVIDER_CONFIGURATION_ENABLED` adds ability to connect multiple providers per channel and make them active. It also shows redesigned integrations store page.

  <figure>
    <img src="/images/community/feature-flags/multi-provider-feature.png" alt="Redesigned Integrations store page" />

    <figcaption>Redesigned Integrations store page.</figcaption>
  </figure>

* `IS_MULTI_TENANCY_ENABLED` adds ability to manage tenants from dashboard.

  <figure>
    <img src="/images/community/feature-flags/tenants-feature.png" alt="Tenants page" />

    <figcaption>Once multi-tenancy is enabled, the Tenants page will appear.</figcaption>
  </figure>

* `IS_TEMPLATE_STORE_ENABLED` enables template store which contains pre-made workflows for common use cases (like **Password Reset** workflow etc).
  <figure>
    <img src="/images/community/feature-flags/template-store-feature.png" alt="Template store" />

    <figcaption>With template store enabled, you can choose from pre-made workflows.</figcaption>
  </figure>


# Get involved with the Novu Community (/community/get-involved)

Your guide for engaging with the Novu Community

## Our Community

At Novu, we're a vibrant, open-source community driven by passion, collaboration, and a shared love for pushing boundaries. We believe in the power of community-driven development, where every voice matters and every contribution counts. As such, contributions are at the heart of how we evolve and progress forward.

## Join the conversation

* Read our [code of conduct](/community/code-of-conduct)
* Say "Hi!" in our [Discord Server](https://discord.gg/novu?ref=docs-community-introduction)
* Explore our [open issues](https://github.com/novuhq/novu/issues)
* Subscribe to our newsletter [to stay in the know](https://novu.co/novu-community-2-0/?utm_campaign=docs-comm2-get-involved)

## Getting help

Our fellow community members are always ready to help you get past a blocker. However, you can take a few things into consideration to help them help you:

* Share as many details as you can share. It will help us in debugging the issue.
* If there is any bug, please share steps to reproduce that bug.
* If there is any issue in running Novu on a local machine, please share system details like operating system, RAM size, npm version and node version.
* If there is any issue in our backend SDKs, please mention the SDK version and relevant details.
* If looking for self-hosting support, please share `Novu Version` and remote server details. Our latest version is `0.24.0`. Please be patient with self-hosting help. We are a small team and we will try our best to help you.

<Callout type="info">
  Use Discord #community-self-host channel for questions related to self hosting.
</Callout>

## Contributing

All community members are of one of the following four types:

1. Open source users
2. Active member
3. Power member
4. Novu Ambassador

### Become an active community member

* Everyone who joins our community becomes an open-source user automatically.
* You can become an active community member by:
  * Submitting >2 PRs
  * Opening >2 issues
  * Sending >5 messages on Github
  * Commenting >3 times on Github
* Active community members are one step closer to becoming Power community members and then an active moderator.

### Become a power community member

* All active community members are eligible to become a power community member and can become so by having at least one of the following:
  * Submitting 3 PRs
  * Opening 3 Issues
  * Sending 10 Discord messages
  * Commenting >10 times on Github
* Power community members are just one step away from becoming a Novu ambassador.

### Become a Novu Ambassador

A Novu ambassador is a trusted power member of the community that can do the following:

* Love exploring and sharing their knowledge of any technology with other developers.
* Often write and speak about Novu.
* Possess strong Novu expertise and often help and support Novu users within the community.
* Socially influence developers with some knowledge of Novu.
* Consistently contribute to Novu OSS product.

We are launching the Novu Ambassador program soon with amazing perks. Stay tuned!

## Activities

Are you passionate about notifications like we are? There are many different—and easy—ways to get involved.

### Help in onboarding and answering questions.

* Welcome new users into the community
* Answer questions in the [community support channel](https://discord.com/channels/895029566685462578/1019663407915483176).
* Offer input and opinions about various solutions you have tried.

### Improve our documentation

* Check out our [GitHub repo](https://github.com/novuhq/docs)
* No documentation is perfect, and neither is ours
* Help us improve our docs by
  * Updating outdated examples
  * Correcting typos and language for clarity
  * Find and fix broken links, etc.

### Help with the SDKs

* Link to [contributors guide](https://github.com/novuhq/novu/blob/next/CONTRIBUTING.md)
* We have SDKs in various languages and frameworks, most written and maintained by community members.
* You can either become a maintainer there or help the existing maintainers by bringing the SDK up to speed with the latest features present in the core product.
  * We have backend SDKs in the following: [Node.js](https://github.com/novuhq/novu/tree/next/packages/node), [PHP](https://github.com/novuhq/novu-php), [.NET](https://github.com/novuhq/novu-dotnet), [Elixir](https://github.com/novuhq/novu-elixir), [Go](https://github.com/novuhq/go-novu), [Ruby](https://github.com/novuhq/novu-ruby), [Python](https://github.com/novuhq/novu-python) [Laravel](https://github.com/novuhq/novu-laravel), and [Kotlin](https://github.com/novuhq/novu-kotlin)
  * And Inbox SDKs: [React](https://github.com/novuhq/novu/tree/next/packages/react), [JavaScript](https://github.com/novuhq/novu/tree/next/packages/js)

### Create content

* Content writers program: Apply to become a content writer with us and get paid to write about use-cases highlighting how you solved a problem using Novu
* Write an article about what you built with Novu and share it with the community. We'll give you a shout out!

### PRs, issues, and bug reports

* Check out our [contributors guide](https://github.com/novuhq/novu/blob/next/CONTRIBUTING.md)
* Once you've gone through our [development process](/community/run-in-local-machine), you can contribute directly to open issues.
* Open a new issue if a relevant one isn't already open.
* Also, you can create bug reports if you find a bug somewhere.
* Or a feature request if you find something that should be a feature but isn't.

<Callout type="info">
  At Novu, we believe that no contribution is small, and the only wrong question is the one that
  doesn't get asked. So feel free to ask any question or raise that Pull Request. You're always
  welcome here! 🤗
</Callout>

### Participate in office hours

* We have frequent (replace with interval— twice weekly, weekly, etc.) and topic-specific office hours that offer the ability to engage in real-time with Novu staff and other community members
* In these sessions, offer input, opinions, examples, etc. to contribute!

We're excited to have you on board and look forward to your valuable contributions!

Together, we'll shape the future of Novu. 🫂


# Community (/community)

Get started and get involved with the Novu Project

Welcome to the Novu community! As the leading open-source notification infrastructure, Novu enables developers and product teams to manage notifications across multiple channels seamlessly. Whether you're building in-app notifications, email alerts, or SMS updates, Novu provides the tools to simplify integration and enhance your communication strategy.

Our mission is to create a platform where every developer can easily implement notifications, with a strong, growing community to support you in every step.

## Community details

The Novu community is built on collaboration. Whether you're contributing code, helping with documentation, or supporting others in Discord, we welcome everyone. We have dedicated teams across various areas:

* **Developers:** Working on the core project and building new features.
* **Contributors:** Writing documentation, reporting bugs, and suggesting improvements.
* **Maintainers:** Ensuring the health of the project by reviewing and merging contributions.
* **Ambassadors**: The most involved contributors and community members nominated by the Community and approved by Novu.

You can find our official community communication channels on Discord. Whether you're a seasoned developer or just getting started, there's a place for you here.

### Getting involved

There are many ways to get involved:

* Contribute code, raise issues, or request features on [GitHub](https://github.com/novuhq/novu).
* Join discussions in the community on [Discord](https://discord.gg/novu).
* Attend Novu events and participate in hackathons to connect with other community members.

[Learn how to get involved with your new favorite open source project](/community/get-involved)

## Novu Cloud, or Novu Project?

The Novu Project is our fully open source, community backed project. It is a complete notifications infrastructure platform that offers all the core components you need to implement notifications.

Novu Cloud is our commercial service offering. It is a superset of the Novu Project that includes additional features and capabilities businesses require to succeed with notifications at scale.

[See the full list of differences between Novu Cloud and Novu.](/community/self-hosted-and-novu-cloud)

## Using Novu

There are two ways to get started with Novu.

### 1. Create a free account in our hosted Novu Cloud service

**Who it's for:** Most businesses, smaller organizations and teams, businesses that do not want to architect and host their own infrastructure, and businesses that do not want to worry about upgrades and system maintenance.

**Who it's not for:** Organizations that want to self-host their own instance of Novu, or plan on making customizations to their Novu installation.

[Learn more about Novu Cloud's features, capabilities, and pricing.](https://novu.co/pricing)

### 2. Self-host

Self-hosting Novu is a great way to rapidly test new custom providers, or to test your contributions.

**Use the Community Docker instances**

* **Who it's for:** Individuals and organizations that want to experiment with more advanced notifications infrastructure architectures, businesses that have a strict requirement to run notifications on premises or inside their own network boundary.
* **Who it's not for:** Non-technical users or teams that are not familiar with implementation and management of container infrastructure. Organizations that require rapid scale-up out-of-the-box, and that don't have the skills and knowledge required to implement and adjust deployments.

[Learn how to deploy Novu with Docker](/community/self-hosting-novu/deploy-with-docker)

**Build it yourself**

* **Who it's for:** Highly technical users that are deeply familiar with the required infrastructure components and technologies required to run it either locally or in your own cloud. Developers that want to experiment. Builders that are actively contributing to the Novu Project, and are testing new functionality.
* **Who it's not for:** Nearly everyone else. ;)

[Learn how to run Novu on your local machine](/community/run-in-local-machine)

## Get help

<Callout type="info">
  For assistance with a Paid or Trial Novu Cloud account? Please use the in-app chat widget which is
  available in the lower right hand corner of the Novu Dashboard after you sign in. 🙂
</Callout>

Should you encounter an issue with either your free Novu Cloud account, or your Novu Project instance, the community is here to help. Our primary channel for community support is our Discord community.

[Learn how to get help with your Novu Project or Free-tier Novu Cloud account](/community/get-involved#getting-help)

### Events

Staying in tune with our upcoming community events, workshops, and hackathons is easy. Keep an eye out for new announcements in the [announcement](https://discord.com/channels/895029566685462578/1040040454906986578) channel in our [Discord community.](https://discord.gg/novu) That's the best way to stay updated about new events. You can also subscribe to our [youtube channel](https://www.youtube.com/@novuhq) and follow us on [dev.to](https://dev.to/novu).


# Product Roadmap (/community/roadmap)

Learn about our roadmap

import { Card, Cards } from 'fumadocs-ui/components/card';
import { MapIcon } from 'lucide-react';

<Cards>
  <Card title="Novu's Roadmap" icon={<MapIcon className="w-4 h-4" />} href="https://roadmap.novu.co/roadmap">
    Learn about ongoing developments, upcoming plans, and items in our backlog..
  </Card>
</Cards>

Your involvement in shaping the future of our notification infrastructure solution is highly encouraged.

## Get involved

**Submit Ideas:** If you have a new feature idea or an enhancement suggestion, don't hesitate to submit it through our [roadmap page](https://roadmap.novu.co/roadmap). Your creativity fuels our innovation!

**Upvote and Comment:** Review the existing feature requests and upvote the ones that resonate with you. Feel free to provide additional insights or use-cases through comments.

**Contribute:** If you're a developer, you can actively contribute to the development of the features in progress or even the backlog ones. [Join our community of contributors](https://discord.gg/novu?ref=docs-contribute) and help us bring these enhancements to life.

<Callout type="info">
  Remember, this roadmap is a living document that evolves based on your input and the direction the
  community decides to take. Your voice matters, and we're excited to work together in building a
  robust notification infrastructure solution that meets everyone's needs.
</Callout>


# Run Novu in local machine (/community/run-in-local-machine)

Prerequisites and steps to run Novu in local machine. Learn how to set up Novu on your local environment for testing and development.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/novuhq/novu)

## Requirements

* Node.js version v20.8.1
* MongoDB
* Redis
* **(Optional)** pnpm - Needed if you want to install new packages
* **(Optional)** localstack (required only in S3 related modules)

<Callout type="info">
  We recommend having at least 8GB of RAM to run Novu on a local machine as Novu has multiple
  services running together with external services like redis, mongodb etc.
</Callout>

## Setup the project

After installing the required services on your machine, you can clone and set up your forked version of the project:

1. Clone the repository

<Tabs items={['Novu Org', 'Forked Repo']}>
  <Tab value="Novu Org">
    ```shell
    git clone https://github.com/novuhq/novu.git
    ```
  </Tab>

  <Tab value="Forked Repo">
    ```shell
    git clone https://github.com/{YOUR_GITHUB_USER_NAME}/novu.git
    ```
  </Tab>
</Tabs>

2. Install all dependencies

```shell
cd novu && npm run setup:project
```

3. Run the project

```shell
npm run start
```

The `npm run start` will start the Jarvis CLI tool which allows you to run the whole project with ease. If you only want to run parts of the platform, you can use the following run commands from the root project:

* **start:dev** - Synonym to `npm run start`
* **start:dashboard** - Only starts the dashboard management platform
* **start:ws** - Only starts the WebSocket service for notification center updates
* **start:widget** - Starts the widget wrapper project that hosts the notification center inside an iframe
* **start:api** - Runs the API in watch mode
* **start:worker** - Runs the worker application in watch mode
* **start:dal** - Runs the Data Access Layer package in watch mode
* **start:shared** - Starts the watch mode for the shared client and API library
* **start:notification-center** - Runs and builds the React package for the Novu notification center

## Set up your environment variables

If you have used Jarvis CLI tool from the previous step you don't need to setup the env variables as Jarvis will do that on the first run if setup wasn't done before.

The command `npm run setup:project` creates default environment variables that are required to run Novu in a development environment. However, if you want to test certain parts of Novu or run it in production mode, you need to change some of them. These are all the available environment variables:

<Accordions>
  <Accordion title="API Backend">
    * `NODE_ENV` (default: local)The environment of the app. Possible values are: dev, test, production, ci, local
    * `S3_LOCAL_STACK`The AWS endpoint for the S3 Bucket required for storing various media
    * `S3_BUCKET_NAME`The name of the S3 Bucket
    * `S3_REGION`The AWS region of the S3 Bucket
    * `PORT`The port on which the API backend should listen on
    * `FRONT_BASE_URL`The base url on which your frontend is accessible for the user. (e.g. dashboard.novu.co)
    * `DISABLE_USER_REGISTRATION` (default: false)If users should not be able to create new accounts. Possible values are: true, false
    * `REDIS_HOST`The domain / IP of your redis instance
    * `REDIS_PORT`The port of your redis instance
    * `REDIS_PASSWORD`Optional password of your redis instance
    * `REDIS_DB_INDEX`The Redis database index
    * `REDIS_CACHE_SERVICE_HOST`The domain / IP of your redis instance for caching
    * `REDIS_CACHE_SERVICE_PORT`The port of your redis instance for caching
    * `REDIS_CACHE_DB_INDEX`The Redis cache database index
    * `REDIS_CACHE_TTL`The Redis cache ttl
    * `REDIS_CACHE_PASSWORD`The Redis cache password
    * `REDIS_CACHE_CONNECTION_TIMEOUT`The Redis cache connection timeout
    * `REDIS_CACHE_KEEP_ALIVE`The Redis cache TCP keep alive on the socket timeout
    * `REDIS_CACHE_FAMILY`The Redis cache IP stack version
    * `REDIS_CACHE_KEY_PREFIX`The Redis cache prefix prepend to all keys
    * `REDIS_CACHE_SERVICE_TLS`The Redis cache TLS connection support
    * `IN_MEMORY_CLUSTER_MODE_ENABLED`The flag that enables the cluster mode. It might be Redis or ElastiCache cluster, depending on the env variables set for either service.
    * `ELASTICACHE_CLUSTER_SERVICE_HOST`ElastiCache cluster host
    * `ELASTICACHE_CLUSTER_SERVICE_PORT`ElastiCache cluster port
    * `REDIS_CLUSTER_SERVICE_HOST`Redis cluster host
    * `REDIS_CLUSTER_SERVICE_PORTS`Redis cluster ports
    * `REDIS_CLUSTER_DB_INDEX`Redis cluster database index
    * `REDIS_CLUSTER_TTL`Redis cluster ttl
    * `REDIS_CLUSTER_PASSWORD`Redis cluster password
    * `REDIS_CLUSTER_CONNECTION_TIMEOUT`Redis cluster connection timeout
    * `REDIS_CLUSTER_KEEP_ALIVE`Redis cluster TCP keep alive on the socket timeout
    * `REDIS_CLUSTER_FAMILY`Redis cluster IP stack version
    * `REDIS_CLUSTER_KEY_PREFIX`Redis cluster prefix prepend to all keys
    * `JWT_SECRET`The secret keybase which is used to encrypt / verify the tokens issued for authentication
    * `SENDGRID_API_KEY`The api key of the Sendgrid account used to send various emails
    * `MONGO_URL`The URL of your MongoDB instance
    * `MONGO_MAX_POOL_SIZE`The max pool size of the MongoDB connection
    * `NOVU_SECRET_KEY`The api key of dashboard.novu.co used to send various emails
    * `SENTRY_DSN`The DSN of sentry.io used to report errors happening in production
  </Accordion>

  <Accordion title="Worker">
    * `NODE_ENV` (default: local) - The environment of the app. Possible values are: dev, test, production, ci, local
    * `PORT` - The port on which the Worker app should listen on
    * `STORE_ENCRYPTION_KEY` - The encryption key used to encrypt/decrypt provider credentials
    * `MAX_NOVU_INTEGRATION_MAIL_REQUESTS` - The number of free emails that can be sent with the Novu email provider
    * `NOVU_EMAIL_INTEGRATION_API_KEY` - The Novu email provider Sentry API key
    * `STORAGE_SERVICE` - The storage service name: AWS, GCS, or AZURE
    * `S3_LOCAL_STACK` - The LocalStack service URL
    * `S3_BUCKET_NAME` - The name of the S3 Bucket
    * `S3_REGION` - The AWS region of the S3 Bucket
    * `GCS_BUCKET_NAME` - The name of the GCS Bucket
    * `AZURE_ACCOUNT_NAME` - The name of the Azure account
    * `AZURE_ACCOUNT_KEY` - The Azure account key
    * `AZURE_HOST_NAME` - The Azure host name
    * `AZURE_CONTAINER_NAME` - The Azure container name
    * `AWS_ACCESS_KEY_ID` - The AWS access key
    * `AWS_SECRET_ACCESS_KEY` - The AWS secret access key
    * `REDIS_HOST` - The domain / IP of your redis instance
    * `REDIS_PORT` - The port of your redis instance
    * `REDIS_PASSWORD` - Optional password of your redis instance
    * `REDIS_DB_INDEX` - The Redis database index
    * `REDIS_CACHE_SERVICE_HOST` - The domain / IP of your redis instance for caching
    * `REDIS_CACHE_SERVICE_PORT` - The port of your redis instance for caching
    * `REDIS_CACHE_DB_INDEX` - The Redis cache database index
    * `REDIS_CACHE_TTL` - The Redis cache ttl
    * `REDIS_CACHE_PASSWORD` - The Redis cache password
    * `REDIS_CACHE_CONNECTION_TIMEOUT` - The Redis cache connection timeout
    * `REDIS_CACHE_KEEP_ALIVE` - The Redis cache TCP keep alive on the socket timeout
    * `REDIS_CACHE_FAMILY` - The Redis cache IP stack version
    * `REDIS_CACHE_KEY_PREFIX` - The Redis cache prefix prepend to all keys
    * `REDIS_CACHE_SERVICE_TLS` - The Redis cache TLS connection support
    * `IN_MEMORY_CLUSTER_MODE_ENABLED` - The flag that enables the cluster mode. It might be Redis or ElastiCache cluster, depending on the env variables set for either service.
    * `ELASTICACHE_CLUSTER_SERVICE_HOST` - ElastiCache cluster host
    * `ELASTICACHE_CLUSTER_SERVICE_PORT` - ElastiCache cluster port
    * `REDIS_CLUSTER_SERVICE_HOST` - Redis cluster host
    * `REDIS_CLUSTER_SERVICE_PORTS` - Redis cluster ports
    * `REDIS_CLUSTER_DB_INDEX` - Redis cluster database index
    * `REDIS_CLUSTER_TTL` - Redis cluster ttl
    * `REDIS_CLUSTER_PASSWORD` - Redis cluster password
    * `REDIS_CLUSTER_CONNECTION_TIMEOUT` - Redis cluster connection timeout
    * `REDIS_CLUSTER_KEEP_ALIVE` - Redis cluster TCP keep alive on the socket timeout
    * `REDIS_CLUSTER_FAMILY` - Redis cluster IP stack version
    * `REDIS_CLUSTER_KEY_PREFIX` - Redis cluster prefix prepend to all keys
    * `MONGO_URL` - The URL of your MongoDB instance
    * `MONGO_MAX_POOL_SIZE` - The max pool size of the MongoDB connection
    * `NEW_RELIC_APP_NAME` - The New Relic app name
    * `NEW_RELIC_LICENSE_KEY` - The New Relic license key
    * `SEGMENT_TOKEN` - The Segment Analytics token
  </Accordion>

  <Accordion title="Web Client">
    * `REACT_APP_ENVIRONMENT` The environment of the app. Possible values are: dev, test, production, ci, local
    * `REACT_APP_API_URL` The base url on which your API backend would be accessible
    * `REACT_APP_WS_URL` The base url on which your WebSocket service would be accessible
    * `SKIP_PREFLIGHT_CHECK` (default: true)Solves a problem with React App dependency tree.

    <Callout type="warn">
      When configuring different than default values for the API and WebSocket URLs, in order for the Web app to apply the changes done to the `./env` file, it is needed to run the script `pnpm envsetup`. This will generate a file called `env-config.js` that will be copied inside of the `public` folder of the application. Its purpose is to inject in the `window._env_`object the chosen environment variables that manage the URLs the Web client will call to access to the API backend and the WebSocket service.
    </Callout>
  </Accordion>

  <Accordion title="Web Socket">
    * `NODE_ENV` (default: local)The environment of the app. Possible values are: dev, test, production, ci, local
    * `SENTRY_DSN`The DSN of sentry.io used to report errors happening in production
    * `REDIS_HOST`The domain / IP of your redis instance
    * `REDIS_PORT`The port of your redis instance
    * `REDIS_DB_INDEX`The database index of your redis instance
    * `REDIS_PASSWORD`Optional password of your redis instance
    * `JWT_SECRET`The secret keybase which is used to encrypt / verify the tokens issued for authentication
    * `MONGO_URL`The URL of your MongoDB instance
    * `MONGO_MAX_POOL_SIZE`The max pool size of the MongoDB connection
    * `PORT`The port on which the WebSocket service should listen on
  </Accordion>
</Accordions>

## Running tests

After making changes, you can run the tests for the respective package using the appropriate CLI commands:

## API

To run the API tests, run the following command:

```shell
npm run start:worker:test
npm run start:e2e:api
```

The tests create a new instance of Novu and a test db and run the tests against it. The test db is removed after all tests have finished running.

## Dashboard

To run the front end tests for the dashboard project using cypress you need to install localstack. The cypress tests perform E2E tests. To be able to perform E2E tests, you need to run the API service in the appropriate test environment.

Run the services in test env with the following commands:

```shell
npm run start:dashboard
npm run start:api:test
npm run start:worker:test
npm run start:ws:test
```

Run the cypress test suite with the following command:

```shell
cd apps/dashboard && npm run cypress:run
```

To open the cypress management window to debug tests, run the following commands:

```shell
cd apps/dashboard && npm run cypress:open
```

## Different ports used by the services

* **3000** - API
* **3002** - WebSocket Service
* **3003** - Webhook Service
* **3004** - Worker Service
* **4200** - Dashboard Management UI
* **4701** - Iframe embed for notification center
* **4500** - Widget Service

## Testing providers

To run tests against the providers' folder, you can use the `npm run test:providers` command.

## Local environment setup script (beta)

As an option in our script runner `Jarvis` we have made available an option to run [this script](https://github.com/novuhq/novu/blob/2f2abdcaaad8a7735e0a2d488607c3276c8975fd/scripts/dev-environment-setup.sh) that will automatically try to install all the dependencies needed to be able to run Novu locally, as the previous step of installing the project dependencies through `pnpm install`. When executing it inside `Jarvis`, you will need to have previously installed by yourself `git` and `node`, as we mentioned earlier on this page.

The script can be run on its own without any previous dependency installed, as it is prepared to execute the following tasks:

* Check the running OS in the local machine (currently only MacOSx and [GNU Linux](https://en.wikipedia.org/wiki/GNU/Linux_naming_controversy)supported)
* Install of OS dependencies (currently only MacOSx supported) -- MacOSx: It will execute the following tasks --- Will try to install or update [XCode](https://developer.apple.com/xcode/) (skippable step; though XCode installs `[git](https://git-scm.com/)` that is a required dependency for later) --- Will install [Rosetta](https://support.apple.com/en-gb/HT211861) for Apple CPUs --- Will set up some opinionated OS settings
* Will check if `[git](https://git-scm.com/)` is installed and if not will abort the operation
* Will make [ZSH](https://en.wikipedia.org/wiki/Z_shell) the default shell to be able to execute the next task
* Will (opinionatedly) install [Oh My Zsh!](https://ohmyz.sh/) (skippable task)
* Will (opinionatedly) install the [Homebrew](https://brew.sh/) package manager and will set up your local environment to execute it besides adding some casks
* Will (opinionatedly) install [NVM](https://github.com/nvm-sh/nvm) as a Node.js version manager
* Will install the required [Node.js](https://nodejs.org/en/) version to be able to [run Novu](https://github.com/novuhq/novu/blob/2f2abdcaaad8a7735e0a2d488607c3276c8975fd/package.json#L180)
* Will install [PNPM](https://pnpm.io/) as a package manager, required dependency for some of the tasks inside Novu's scripts
* Will install [Docker](https://www.docker.com/) as containerized application development tool
* Will install required databases [MongoDB](https://www.mongodb.com/) (Community version) and [Redis](https://redis.io/) through Homebrew
* Will install the [AWS CLI](https://aws.amazon.com/cli/) tool (not required to run Novu; it is a core maintainer used tool)
* Will create a local development domain `local.novu.co` in your local machine
* Will clone the Novu repository in your local machine (skippable step) to a selected folder `$HOME/Dev`

<Callout type="warn">
  This script has only been thoroughly tested in MacOSx. Little testing has been run in GNU Linux.
</Callout>

<Callout type="info">
  This script is not bullet-proof and some of the tasks have intertwined dependencies with each
  other. We have tried to make it as idempotent as possible but some loose knots will probably show
  because of conflicts between versions of the different dependencies. Please report to us any
  problem found and we will try to fix or assist though we do not have the resources to make it
  idempotent in every potential system and potential combinations
</Callout>


# Self-Hosted and Novu Cloud (/community/self-hosted-and-novu-cloud)

Understand the difference between Self-Hosted and Novu Cloud

## Better together

Community Self-Hosted is where the community comes together with our development teams to improve notifications for everyone. Novu Cloud is our commercial offering, and where we extend the capabilities of the Community Self-Hosted and make them accessible and consumable by all teams and businesses. Most simply, the Community Self-Hosted is how you test and experiment with notifications infrastructure, and Novu Cloud is how you press the easy button for all things notifications.

## Key differences

Our goal is always provide a functional, powerful, and complete notifications infrastructure platform, whether you opt to self host or use our cloud offering. However, certain features we build into Novu Cloud are not available in the Community Self-Hosted. When this happens, it's for several reasons:

* We rely on a paid third-party service provider
* The feature is complex and requires significant investment (read: money!) time to build and maintain
* The feature is primarily targeted at the largest and most sophisticated of use cases, and supporting these in self-hosted environments is challenging

## Current matrix

Below you will find a table that outlines the best available Novu Cloud Tier, compared to the available Community Self-Hosted capabilities.

### General Capabilities

| Features                                 | Community Self-Hosted    | Novu Cloud |
| :--------------------------------------- | :----------------------- | :--------- |
| Activity feed retention                  | Infrastructure dependent | ✅          |
| Block-based email editor                 | ✅                        | ✅          |
| Channels: Email, In-app, SMS, Chat, Push | ✅                        | ✅          |
| Code-based Framework workflows           | ✅                        | ✅          |
| Custom environments                      | ❌                        | ✅          |
| Digest                                   | ✅                        | ✅          |
| GUI-based workflows                      | ✅                        | ✅          |
| Max workflows                            | Infrastructure dependent | Custom     |
| Provider integrations                    | Infrastructure dependent | Unlimited  |
| Subscribers                              | Infrastructure dependent | Unlimited  |
| More than 2 environments                 | ❌                        | Custom     |
| Environment variables                    | ❌                        | ✅          |

### Inbox

| Features                   | Community Self-Hosted | Novu Cloud |
| -------------------------- | --------------------- | ---------- |
| Bell component             | ✅                     | ✅          |
| Inbox component            | ✅                     | ✅          |
| Inbox content component    | ✅                     | ✅          |
| Notifications component    | ✅                     | ✅          |
| Remove Novu branding       | ❌                     | ✅          |
| Snooze                     | ❌                     | ✅          |
| User preferences component | ✅                     | ✅          |

### Email

| Features                 | Community Self-Hosted | Novu Cloud |
| ------------------------ | --------------------- | ---------- |
| Remove Novu branding     | ❌                     | ✅          |
| Multiple email layouts   | ✅                     | ✅          |
| Block-based email editor | ✅                     | ✅          |
| HTML email editor        | ✅                     | ✅          |

### Account Administration and Security

| Features                          | Community Self-Hosted | Novu Cloud |
| --------------------------------- | --------------------- | ---------- |
| Built-In authentication           | ❌                     | ✅          |
| Custom SAML SSO, OIDC providers   | ❌                     | ✅          |
| Max team members                  | 1                     | Custom     |
| Multi-Factor Authentication (MFA) | ❌                     | ✅          |
| Role-Based Access Control (RBAC)  | ❌                     | ✅          |
| Standard SAML (Google, Github)    | ❌                     | ✅          |

### Compliance

| Features                   | Community Self-Hosted  | Novu Cloud |   |
| -------------------------- | ---------------------- | ---------- | - |
| Custom security reviews    | ❌                      | ✅          |   |
| Data Processing Agreements | ❌                      | Custom     |   |
| GDPR                       | Installation dependent | ✅          |   |
| HIPAA BAA                  | ❌                      | ✅          |   |
| SOC 2 / ISO 27001          | ❌                      | ✅          |   |

## Ready to Scale? Upgrade to Novu Cloud

If you're currently self-hosting Novu, Novu offers an Enterprise Edition offering for self-hosted users and a managed cloud based deployment. [Contact Us](https://novu.co/contact-us) to learn more.

### Why Upgrade to Novu Cloud?

* **Zero Infrastructure Management**
  * No server maintenance, scaling headaches, and deployment complexities
  * Focus on what matters most - building your product
  * Let our team handle the heavy lifting

* **Enterprise-Grade Features at Your Fingertips**
  * Access advanced security features including SAML SSO and MFA
  * Benefit from enterprise compliance (SOC 2, ISO 27001, HIPAA)

* **Always Up-to-Date**
  * Automatic updates and improvements
  * Access to the latest features and security patches
  * No more manual upgrades or maintenance windows

* **Support**
  * Expert assistance for seamless migration
  * Priority support for your team
  * Custom security reviews and compliance guidance


# Novu Guides and Tutorials (/guides)

Step-by-step guides for integrating Novu with popular services like Clerk, Stripe, and Segment.

import { Card, Cards } from 'fumadocs-ui/components/card';
import ClerkIcon from '@/components/icons/home-page/clerk';
import { StripeIcon } from '@/components/icons/stripe';
import { SegmentIcon } from '@/components/icons/segment';

## Integration Guides

Novu provides various ways to integrate with external services to trigger notification workflows. Here are the main integration approaches:

### Webhook Integration Guides

Webhooks enable real-time event-driven communication between applications, making integrations more efficient and responsive.

In Novu, webhooks trigger notification workflows whenever specific events occur in external applications. This ensures notifications are delivered exactly when they're needed, keeping users informed without delay.

For example, when a user signs up via Clerk or completes a payment through Stripe, a webhook delivers the event payload to Novu, which then processes it and triggers the appropriate workflow.

This allows for real-time notifications—whether it's a welcome email, payment confirmation SMS, or in-app alert—without the need for constant polling, ensuring efficiency and a seamless user experience.

<Cards>
  <Card title="Clerk" icon={<ClerkIcon />} href="/guides/webhooks/clerk">
    <p>
      Use Clerks webhooks events to trigger authentication related notifications workflows.
    </p>
  </Card>

  <Card title="Stripe" icon={<StripeIcon />} href="/guides/webhooks/stripe">
    <p>
      Use Stripe webhooks events to trigger payment related notifications workflows.
    </p>
  </Card>
</Cards>

### Analytics & Data Platform Integrations

Some integrations use different mechanisms than webhooks to send data to Novu. For example, analytics and data platforms often use custom destinations or functions to forward events.

<Cards>
  <Card title="Segment" icon={<SegmentIcon />} href="/guides/webhooks/segment">
    <p>
      Use Segment's Destination Functions to forward user events and traits to trigger notification workflows.
    </p>
  </Card>
</Cards>

### Workflow Automation Platform Integrations

Workflow automation platforms help orchestrate complex business processes and event-driven workflows. Integrating Novu with these platforms allows you to trigger notifications as part of your automated workflows.

<Cards>
  <Card title="Inngest" href="/guides/inngest">
    <p>
      Use Inngest's event-driven workflows to trigger notifications at specific steps in your automation pipeline.
    </p>
  </Card>

  <Card title="Trigger.dev" href="/guides/triggerdotdev">
    <p>
      Leverage Trigger.dev's developer-friendly workflow engine to send notifications based on scheduled or event-driven triggers.
    </p>
  </Card>
</Cards>


# Novu and Inngest integration guide (/guides/inngest)

This guide walks you through integrating Inngest with Novu notifications

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Why Use Novu with Inngest?

By combining these tools, you can:

* **Trigger Smart Notifications**: Send notifications across multiple channels (email, SMS, push, in-app) based on complex event triggers
* **Build Reliable Workflows**: Create robust notification pipelines with Inngest's state management and retry capabilities
* **Scale Effortlessly**: Handle high-volume notification workloads with Inngest's queue management
* **Maintain Observability**: Monitor your notification workflows in real-time through Inngest's dashboard

## What You'll Learn

This guide teaches you how to:

* Configure Novu and Inngest in your project
* Manage notification subscribers via Novu's API
* Create event-driven notification workflows with Inngest
* Use dynamic data to personalize your notifications

<Callout type="info">
  New to Inngest? We recommend starting with their [quickstart guide](https://www.inngest.com/docs/getting-started) before continuing.
</Callout>

1. Install Novu's SDK in our project

   ```json
   npm i @novu/api
   ```

2. Create a new task

   <Callout>
     You can also add this trigger to an existing one or multiple tasks
   </Callout>

   Import Novu's SDK and provide the credentials to initialize the Novu instance.

   ```typescript
   import { Novu } from "@novu/api";

   const novu = new Novu({ 
     secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
   });
   ```

   For the sake of this guide, we will create a new dedicated functions for 2 common Novu actions:

   * Trigger Notification Workflow
   * Add New Subscriber

## Trigger Notification Workflow from an Inngest function

You can trigger Novu notification workflows directly from your Ingest function. This allows you to send notifications based on events or completions within your background jobs.

To trigger a Novu workflow, you'll use the Novu Node.js SDK within your Inngest's `createFunction` method.

### Core Requirements

When calling Novu's `trigger` method, you must provide the following information:

1. `workflowId` **(string):** This identifies the specific notification workflow you want to execute.
   * **Note:** Ensure this workflow ID corresponds to an existing, active workflow in your Novu dashboard.
2. `to` **(object):** This object specifies the recipient of the notification. At a minimum, it requires:
   * `subscriberId` **(string):** A unique identifier for the notification recipient within your system (e.g., a user ID).
   **Note:** If a subscriber with this `subscriberId` doesn't already exist in Novu, Novu will automatically create one when the workflow is triggered. You can also pass other identifiers like `email`, `phone`, etc., within the `to` object, depending on your workflow steps.

### Basic Trigger Example

Here's a simple Inngest function that triggers a Novu workflow when the function is being invoked. It assumes the function invoke receives a `userId` and `email` in its payload.

```tsx
import { inngest } from "./client";
import { Novu } from "@novu/api";

const novu = new Novu({ 
    secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
  });

export const sendNotification = inngest.createFunction(
  { id: "send-notification" },
  { event: "test/hello.world" },
  async ({ event, step }) => {
    await step.run("send-welcome-email", async () => {
        await novu.trigger({
            workflowId: "welcome-email",
            to: {
                subscriberId: event.data.userId,
                email: event.data.email,
            },
            payload: {},
        });
    });

    return { message: `Welcome email sent to ${event.data.email}!` };
  },
);
```

### Adding Dynamic Content with `payload`

Often, you'll want your notifications to include dynamic data related to the event that triggered them (e.g., a user's name, an order number, job details).

This is done using the `payload` property in the `novu.trigger` call.

The `payload` is an object containing key-value pairs that you can reference within your Novu notification templates using Handlebars syntax (e.g., `{{ name }}`, `{{ order.id }}`).

**Use Case Example:**

Imagine you want to send an email confirming a background job's completion:

* **Subject:** `Function {{ functionName }} Completed Successfully!`
* **Body:** `Hi {{ userName }}, your function '{{ functionName }}' finished processing.`

To achieve this, you would pass the `userName` and `functionName` in the `payload` object when triggering the workflow.

### Trigger Example with Payload

Let's modify the previous function to accept more data (like a user's `name`) in its own payload and pass relevant parts to the Novu `trigger` payload.

```typescript
import { inngest } from "./client";
import { Novu } from "@novu/api";

const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});

export const sendNotification = inngest.createFunction(  
  { id: "send-notification" },
  { event: "test/hello.world" },
  async ({ event, step }) => {
    await step.run("send-welcome-email", async () => {
      try {
        // Construct the payload specifically for Novu
        const novuPayload = {
          userName: event.data.userName,   // Map 'name' from task payload to 'userName' for the template
          functionName: `Data Processing Function #${event.id}`, // Can include static text or transform data
        };

        await novu.trigger({
          workflowId: "inbox-test", // Use the appropriate workflow ID
          to: {
            subscriberId: event.data.userId,
            email: event.data.email,
          },
          payload: {
            ...novuPayload,
          },
        });

        console.log("Novu workflow triggered successfully with payload:", novuPayload);
        return novuPayload;

      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error triggering Novu';
        console.error("Failed to trigger Novu workflow with payload:", errorMessage, error);
        throw new Error(`Novu trigger failed: ${errorMessage}`);
      }
    });
  },
);
```

## Add a New Subscriber to Novu

Before sending notifications, Novu needs to know *who* to notify. That's where subscribers come in. A **subscriber** in Novu represents a user (or entity) that can receive notifications through one or more channels (in-app, email, SMS, etc.).

You can create a new subscriber programmatically from a Inngest's task using Novu's SDK.

***

### When Should You Create Subscribers?

Create or update a subscriber in Novu when:

* A new user signs up or is added to your system
* A user becomes eligible to receive notifications
* You want to ensure subscriber metadata (name, phone, etc.) is up-to-date

<Callout>
  If you trigger a workflow with a `subscriberId` that doesn't exist, Novu will auto-create the subscriber. However, doing it explicitly ensures full control over subscriber data.
</Callout>

### Create a Subscriber in a Task

Below is a task that creates a Novu subscriber using a Inngest task. It also supports optional fields like `phone` and `avatar`.

```typescript
import { inngest } from "./client";
import { Novu } from "@novu/api";

const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});

export const createSubscriber = inngest.createFunction(  
  { id: "create-subscriber" },
  { event: "app/account.created" },
  async ({ event, step }) => {
    await step.run("create-subscriber", async () => {
      try {
        // Construct the payload specifically for Novu
        const subscriberPayload = Object.fromEntries(
          Object.entries({
            subscriberId: event.data.userId,
            email: event.data.email,
            firstName: event.data.firstName,
            lastName: event.data.lastName,
            phone: event.data.phone,
            avatar: event.data.avatar,
            locale: event.data.locale,
            data: event.data.userName ? { userName: event.data.userName } : undefined
          }).filter(([, value]) => value !== undefined)
        ) as {
          subscriberId: string;
          email?: string;
          firstName?: string;
          lastName?: string;
          phone?: string;
          avatar?: string;
          locale?: string;
          data?: { userName: string };
        };

        await novu.subscribers.create(subscriberPayload);

        console.log("Novu subscriber created successfully with payload:", subscriberPayload);
        return subscriberPayload;

      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error creating Novu subscriber';
        console.error("Failed to create Novu subscriber with payload:", errorMessage, error);
        throw new Error(`Novu subscriber creation failed: ${errorMessage}`);
      }
    });
  },
);
```

***

## Implementation Example

This example assumes:

1. You have an event named `video/uploaded` that is being sent to Inngest when a user uploads a video.
2. This event's `data` payload includes at least `videoUrl`, `videoId`, `userId`, `email`, and `userName`.
3. You have external services/functions mocked or implemented: `deepgram.transcribe`, `llm.createCompletion`, `createSummaryPrompt`, and `db.videoSummaries.upsert`.
4. You have a Novu account, API Key (`NOVU_SECRET_KEY` environment variable), and a Novu workflow created with the ID `video-processed-notification`.
   This workflow should expect variables like `userName`, `videoId`, and potentially `summarySnippet` in its payload.

```typescript
import { Inngest } from "inngest";
import { Novu } from "@novu/api";

// --- Mock/Placeholder External Services ---
// Replace these with your actual implementations
const deepgram = {
  transcribe: async (url: string): Promise<string> => {
    console.log(`Mock Transcribing: ${url}`);
    await new Promise(resolve => setTimeout(resolve, 1500)); // Simulate network delay
    return `This is a mock transcript for the video at ${url}. It contains several sentences explaining the content.`;
  }
};

const llm = {
  createCompletion: async (params: { model: string; prompt: string }): Promise<string> => {
    console.log(`Mock Summarizing with ${params.model}`);
    await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate LLM processing time
    const transcriptSnippet = params.prompt.substring(params.prompt.indexOf(":") + 1, 70);
    return `Mock summary of the transcript starting with: ${transcriptSnippet}...`;
  }
};

const createSummaryPrompt = (transcript: string): string => {
  return `Please summarize the following transcript:\n\n${transcript}`;
};

const db = {
  videoSummaries: {
    upsert: async (data: { videoId: string; transcript: string; summary: string }): Promise<void> => {
      console.log(`Mock DB Upsert for videoId: ${data.videoId}`);
      // In a real scenario, save data.transcript and data.summary linked to data.videoId
      await new Promise(resolve => setTimeout(resolve, 500)); // Simulate DB write delay
    }
  }
};
// --- End Mock Services ---

// --- Inngest Client Setup ---
// Assumes you have your Inngest client initialized elsewhere (e.g., './inngest/client')
// For this example, we'll initialize it here. Replace with your actual client setup.
export const inngest = new Inngest({ id: "video-processing-app" });
// --- End Inngest Client Setup ---

// --- Novu Client Setup ---
const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});
// --- End Novu Client Setup ---

// --- Combined Inngest Function ---
export const processVideoAndNotify = inngest.createFunction(
  {
    id: "process-video-and-notify",
    name: "Process Uploaded Video and Notify User",
    // Apply concurrency limits per user to avoid overwhelming resources
    concurrency: {
      limit: 3, // Allow up to 3 concurrent processing jobs per user
      key: "event.data.userId"
    }
  },
  { event: "video/uploaded" }, // Triggered when a video upload event occurs
  async ({ event, step }) => {
    const { videoUrl, videoId, userId, email, userName } = event.data;

    // Validate required data from the event
    if (!videoUrl || !videoId || !userId || !email || !userName) {
        throw new Error(`Missing required data in 'video/uploaded' event payload for event ID: ${event.id}`);
    }

    // --- Step 1: Transcribe Video ---
    // step.run ensures this block retries on failure and runs exactly once on success.
    const transcript = await step.run('transcribe-video', async () => {
      console.log(`Starting transcription for videoId: ${videoId}, url: ${videoUrl}`);
      try {
        const result = await deepgram.transcribe(videoUrl);
        console.log(`Transcription successful for videoId: ${videoId}`);
        return result;
      } catch (error) {
        console.error(`Transcription failed for videoId: ${videoId}`, error);
        throw error; // Re-throw to enable Inngest retries
      }
    });

    // --- Step 2: Summarize Transcript ---
    // The 'transcript' result from the previous step is automatically available here.
    const summary = await step.run('summarize-transcript', async () => {
      console.log(`Starting summarization for videoId: ${videoId}`);
      try {
        const result = await llm.createCompletion({
          model: "gpt-4o", // Or your preferred model
          prompt: createSummaryPrompt(transcript),
        });
        console.log(`Summarization successful for videoId: ${videoId}`);
        return result;
      } catch (error) {
        console.error(`Summarization failed for videoId: ${videoId}`, error);
        throw error; // Re-throw for retries
      }
    });

    // --- Step 3: Write Results to Database ---
    await step.run('write-summary-to-db', async () => {
      console.log(`Writing transcript and summary to DB for videoId: ${videoId}`);
      try {
        await db.videoSummaries.upsert({
          videoId: videoId,
          transcript,
          summary,
        });
        console.log(`DB write successful for videoId: ${videoId}`);
      } catch (error) {
        console.error(`DB write failed for videoId: ${videoId}`, error);
        throw error; // Re-throw for retries
      }
    });

    // --- Step 4: Send Completion Notification via Novu ---
    // This step runs only after the previous steps have succeeded.
    await step.run("send-completion-notification", async () => {
      if (!novuApiKey) {
        console.warn(`Skipping notification for videoId ${videoId} as NOVU_SECRET_KEY is not set.`);
        return { skipped: true, reason: "NOVU_SECRET_KEY not set" };
      }

      console.log(`Attempting to send Novu notification for videoId: ${videoId} to user: ${userId}`);

      // Construct a relevant payload for your Novu template
      const novuPayload = {
        userName: userName,
        videoId: videoId,
        summarySnippet: summary.substring(0, 100) + (summary.length > 100 ? "..." : ""), // Send a preview
        // Add any other data your Novu template needs, e.g., a link to view the full video/summary
        // videoUrl: `https://yourapp.com/videos/${videoId}`
      };

      try {
        const triggerResult = await novu.trigger({
          // Ensure this workflow ID exists in your Novu dashboard
          workflowId: "video-processed-notification",
          to: {
            subscriberId: userId, // Crucial for identifying the user in Novu
            email: email, // Can be used by Novu email channel
            // Add other channels like phone if needed and available
          },
          payload: novuPayload,
        });

        console.log(`Novu workflow 'video-processed-notification' triggered successfully for videoId: ${videoId}`, triggerResult);
        return { success: true, novuPayload: novuPayload, triggerResult };

      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error triggering Novu';
        console.error(`Failed to trigger Novu workflow for videoId: ${videoId}: ${errorMessage}`, error);
        // Decide if notification failure should cause the step to fail and retry
        // For notifications, often you might want to log the error but not fail the whole function
        // throw new Error(`Novu trigger failed: ${errorMessage}`); // Uncomment to make it retry
         return { success: false, error: errorMessage }; // Log and continue
      }
    });

    // --- Function Completion ---
    // Optional: return a final status or summary
    return {
      message: `Video processing and notification steps completed for videoId: ${videoId}`,
      videoId: videoId,
      userId: userId,
      summaryLength: summary.length,
    };
  }
);

// --- How to Trigger (Example) ---
/*
Somewhere else in your application (e.g., after a file upload completes):

import { inngest } from "./path/to/inngest/client"; // Your initialized Inngest client

async function handleVideoUpload(uploadResult: { url: string, id: string, user: { id: string, email: string, name: string } }) {
  await inngest.send({
    name: "video/uploaded", // The event name our function listens to
    data: {
      videoUrl: uploadResult.url,
      videoId: uploadResult.id,
      userId: uploadResult.user.id,
      email: uploadResult.user.email,
      userName: uploadResult.user.name,
    },
    user: { // Optionally pass user context if needed for event metadata/tracking
        id: uploadResult.user.id,
        email: uploadResult.user.email,
    }
  });
  console.log(`Sent 'video/uploaded' event for videoId: ${uploadResult.id}`);
}

// Example usage:
handleVideoUpload({
    url: "https://example.com/videos/123.mp4",
    id: "vid_12345abc",
    user: { id: "user_67890def", email: "test@example.com", name: "Alice" }
});
*/
```

***

### Template Usage Example

Once you've added custom fields (like `firstName`, `userName`, or `phone`) to a subscriber, you can use them in Novu templates using Handlebars:

* Hi `{{subsciber.firstName}}`, welcome!
* We'll reach you at `{{subsciber.phone}}` if needed.
* Your account is set up under `{{subscriber.data.userName}}`.

***

### Best Practices

* Store your Novu `subscriberId` as part of your user model — so you always have a reference.
* Create/update subscribers proactively when user data changes (e.g., phone number updates).
* Use `data` to store additional info like roles, tags for more personalized notifications.


# Migrate from Courier to Novu (/guides/migrate-from-courier-to-novu)

Learn how to migrate your notification infrastructure from Courier to Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

This guide helps you plan and execute a migration from Courier to Novu. It covers how the two platforms compare, what changes when moving to Novu, and a step-by-step approach for migrating your notification workflows, templates, providers, and user data.

## Why Novu?

* **Unified Workflows:** Courier separates "Templates" (content) and "Automations" (logic). Novu unifies routing, timing (delays/digests), and content into a single **Workflow**, making it much easier to manage the entire lifecycle of a message.
* **Choose How You Build:**
  * **Visual Builder:** A powerful drag-and-drop dashboard for teams that want a no-code UI to design content and orchestration.
  * **Novu Framework:** An optional code-first approach that lets developers write workflows in TypeScript, version-control them, and test them locally.
* **Unrivaled React Ecosystem:** Novu's in-app Inbox comes with pre-built React components for a drop-in experience, plus powerful headless hooks if you want to build a completely bespoke UI.
* **Data Sovereignty:** Because Novu is open-source, you can use our fully managed Cloud platform or self-host it on your own infrastructure to meet strict compliance requirements.
* **Translations:** Novu supports translations for your notifications, making it easier to localize your notifications for your users. Use translation keys in channel step editor to localize your notifications and Novu will send the notifications in the subscriber's locale. Read more on how to [use translations](/platform/workflow/advanced-features/translations) in the Novu Dashboard.
* **Multi-tenancy:** Send notifications to different tenants or organizations within the same Novu project and let users manage their notification preferences for each tenant. Read more on how to [use multitenancy](/platform/workflow/advanced-features/contexts) in the Novu Dashboard.

## Mapping Courier concepts to Novu concepts

Before you dive into the migration steps, here is a quick cheat sheet for translating your Courier setup into Novu's terminology.

| Courier Concept             | Novu Equivalent  | How they compare                                                                                                                                                                                                                                                                                  |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Automations + Templates** | **Workflows**    | Novu combines your message content and delivery logic (like delays or digests) into a single, easy-to-manage Workflow.                                                                                                                                                                            |
| **Profiles / Users**        | **Subscribers**  | The core entity receiving the notification. Just like Courier, Novu allows you to pass user data inline, meaning you don't have to sync users beforehand.                                                                                                                                         |
| **Lists / Audiences**       | **Topics**       | Used for broadcasting. In Novu, you trigger a workflow to a Topic, and Novu automatically fans it out to all subscribed users.                                                                                                                                                                    |
| **Preferences**             | **Preferences**  | Novu categorizes user opt-in/opt-out states natively by Workflow or via global channel settings. End user can manage their preference for each workflow or globally.                                                                                                                              |
| **Integrations**            | **Integrations** | Both platforms connect to external providers (Twilio, SendGrid, etc.). Novu lets you define multiple active integrations for each channel provider and set a primary integration per environment.                                                                                                 |
| **Inbox**                   | **Inbox**        | Novu's in-app Inbox comes with pre-built React components for a drop-in experience, plus powerful headless hooks, javascript and react native support if you want to build custom Inbox UI.                                                                                                       |
| **Tenants**                 | **Context**      | Novu supports multitenancy out of the box, the most simple way to implement tenant separation sending context information while triggering a workflow. Novu will automatically filter the notifications for the tenant and the end user will see only the notifications relevant to their tenant. |

## Migration steps

We recommend a phased approach to migrate safely without dropping any messages.

<Steps>
  <Step title="Phase 1: Set up your workspace and providers">
    1. **Create your workspace:** Sign up for [Novu Cloud](https://dashboard.novu.co/auth/signup). You'll automatically get isolated **Development** and **Production** environments.
    2. **Connect your providers:** In the Novu Dashboard, navigate to the **Integrations Store**. Reconnect the ESPs (SendGrid, Postmark), SMS gateways (Twilio), and Push providers (FCM, APNS) you were using in Courier.
  </Step>

  <Step title="Phase 2: Migrate audience data">
    You need to sync your Courier `Profiles` to Novu `Subscribers`. The easiest way to handle this is a **Lazy Migration**:

    Instead of exporting and importing thousands of users manually, simply update your backend to pass the user's details (email, phone, name) inline when you trigger a notification. Novu will automatically create or update the Subscriber on the fly.

    *If you prefer to sync ahead of time, you can easily script it:*

    ```typescript
    import { Novu } from '@novu/api';
    const novu = new Novu({ secretKey: 'YOUR_NOVU_API_KEY' });

    // Translating a Courier profile to a Novu subscriber
    await novu.subscribers.create({
      subscriberId: 'usr_123', // Your internal user ID
      email: 'alex@example.com',
      phone: '+15551234567',
      data: {
        subscriptionTier: 'premium' // Custom data
      }
    });
    ```

    You can also use the [Bulk Import API](/api-reference/subscribers/bulk-create-subscribers) to import your subscribers in bulk.
  </Step>

  <Step title="Phase 3: Translate automations to workflows">
    In Courier, you link Automations to Templates. In Novu, you recreate these as **Workflows**. You have two great options for building them:

    **Option A: The Dashboard Visual Builder**
    If your product or marketing team loves managing notifications visually, they will feel right at home in the Novu Dashboard. You can drag and drop Email, SMS, and In-App steps, add Delays and Digests, and edit message content directly in the browser. Read more on how to [manage workflows](/platform/workflow/overview) in the Novu Dashboard.

    **Option B: Code-First with Novu Framework**
    If your engineering team wants more control, you can use `@novu/framework` to define the same workflows directly in your codebase using TypeScript.

    *A simple code-first example:*

    ```typescript
    import { workflow } from "@novu/framework";

    export const weeklyDigestWorkflow = workflow('weekly-digest', async ({ step }) => {
      // Replaces Courier's digest node
      const digestResult = await step.digest('batch-events', () => ({ amount: 7, unit: 'days' }));

      // Replaces Courier's send node + template
      await step.email('send-summary', async (controls) => {
        return {
          subject: `Your Weekly Activity Summary`,
          body: `You have ${digestResult.events.length} new updates this week.`,
        };
      });
    });

    ```
  </Step>

  <Step title="Phase 4: Swap out the in-app Inbox">
    If your app uses Courier's Inbox component, swapping it for Novu's is incredibly simple. Novu's Inbox provides out-of-the-box real-time updates and unread counts.

    ```bash
    npm install @novu/react
    ```

    ```tsx
    import { Inbox } from "@novu/react";

    export default function NotificationCenter() {
      return (
        <Inbox
          applicationIdentifier="YOUR_NOVU_APP_ID"
          subscriberId="usr_123"
          // We recommend using HMAC encryption in production for security
          subscriberHash="HMAC_HASH_GENERATED_ON_BACKEND" 
        />
      );
    }
    ```
  </Step>

  <Step title="Phase 5: Update API calls">
    With your workflows ready and integrations connected, it's time to replace your `courier.send()` API calls with Novu `trigger` calls.

    <Tabs items={['Node.js', 'Python', 'cURL']}>
      <Tab value="Node.js">
        ```javascript
        import { Novu } from '@novu/api';
        const novu = new Novu({ secretKey: 'YOUR_SECRET_KEY' });

        // Replaces courier.send()
        await novu.trigger({
          workflowId: 'weekly-digest',
          to: { 
            subscriberId: 'usr_123',
            // Pass details inline for easy lazy migration
            email: 'alex@example.com' 
          },
          payload: {
            activityType: 'login'
          }
        });
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import novu_py
        from novu_py import Novu
        import os
         
        with Novu(
        secret_key=os.getenv("NOVU_SECRET_KEY", ""),
        ) as novu:
         
            res = novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
                workflow_id="workflow_identifier",
                to={
                    "subscriber_id": "subscriber_unique_identifier",
                    "first_name": "Albert",
                    "last_name": "Einstein",
                    "email": "albert@einstein.com",
                },
                payload={
                    "comment_id": "string",
                    "post": {
                        "text": "string",
                    },
                },
                overrides={
                  "email": {
                    "bcc": "no-reply@novu.co"
                  }
                },
            ))
         
            # Handle response
            print(res)
        ```
      </Tab>

      <Tab value="cURL">
        ```bash
        curl -X POST https://api.novu.co/v1/events/trigger \
          -H "Authorization: ApiKey YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "weekly-digest",
            "to": { "subscriberId": "usr_123" },
            "payload": {
              "activityType": "login"
            }
          }'
        ```
      </Tab>
    </Tabs>

    **Final Validation:** Send test events using your Novu Development API key. Monitor the **Execution Logs** in the Dashboard to verify everything works flawlessly. Once you're confident, switch to your Production API key and you're fully migrated!
  </Step>
</Steps>

## API endpoint quick reference

Need to update your backend API requests? Use this mapping to find the Novu equivalent of your Courier endpoints.

| Action                  | Courier Endpoint                    | Novu Equivalent                                                                                               |
| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Trigger a Message**   | `POST /send`                        | [`POST /v1/events/trigger`](/api-reference/events/trigger-event)                                              |
| **Send to Many**        | `POST /bulk`                        | [`POST /v1/events/trigger/bulk`](/api-reference/events/bulk-trigger-event)                                    |
| **Update User**         | `PUT /profiles/:id`                 | [`PUT /v2/subscribers/:subscriberId`](/api-reference/subscribers/update-a-subscriber)                         |
| **Fetch User Data**     | `GET /profiles/:id`                 | [`GET /v2/subscribers/:subscriberId`](/api-reference/subscribers/retrieve-a-subscriber)                       |
| **Modify Opt-Ins**      | `PUT /users/:id/preferences/:topic` | [`PATCH /v2/subscribers/:subscriberId/preferences`](/api-reference/subscribers/update-subscriber-preferences) |
| **Manage Lists/Groups** | `PUT /lists/:id`                    | [`POST /v2/topics`](/api-reference/topics/create-a-topic)                                                     |
| **View Logs**           | `GET /messages`                     | [`GET /v1/notifications`](/api-reference/notifications/list-all-notifications)                                |

## Next steps

<Cards cols={2}>
  <Card title="Quickstart Guide" href="/platform/quickstart/react">
    Get up and running with Novu in under 5 minutes.
  </Card>

  <Card title="Inbox Integration" href="/platform/inbox">
    Add a real-time notification center to your application.
  </Card>

  <Card title="Explore Novu Framework" href="/framework">
    Learn more about the code-first approach to building workflows.
  </Card>

  <Card title="API Reference" href="/api-reference">
    Explore Novu's REST endpoints and SDKs.
  </Card>
</Cards>


# Novu and Trigger.dev integration guide (/guides/triggerdotdev)

Integrate Novu with Trigger.dev to send notifications from background jobs. Covers setup, subscribers, and practical examples.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { NextjsIcon } from '@/components/icons/nextjs';
import { ExpressjsIcon } from '@/components/icons/expressjs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { File, Folder, Files } from 'fumadocs-ui/components/files';

This guide walks you through integrating [Novu](https://novu.co/), the open-source notification infrastructure, with [Trigger.dev](https://trigger.dev/), a powerful open-source background jobs framework for TypeScript.

By combining Novu's robust notification workflows with Trigger.Dev's event-driven background job system allows you to send notifications across multiple channels (in-app, email, SMS, push, etc.) in response to events or background tasks — all within a seamless developer experience.

Whether you're processing payments, handling user onboarding, or running scheduled tasks, Trigger.dev lets you define workflows with fine-grained control and real-time observability. Novu plugs into those workflows to manage notification content and delivery, ensuring your service / product-to-user communication has a standard.

## What You'll Learn

In this guide, you'll learn how to:

* Set up both Novu and Trigger.dev in your project
* Create and update subscribers via Novu's API
* Trigger Novu notification workflows from a Trigger.dev job
* Pass dynamic payload data to power your notification templates

<Callout type="info">
  If you haven't used or are unfamiliar with Trigger.dev, we recommend following [the quickstart guide in their docs](https://trigger.dev/docs/quick-start). This guide assumes you are familiar with the fundamentals.
</Callout>

## Getting Started

<Steps>
  <Step>
    Install Novu's SDK in your project:

    ```bash
    npm i @novu/api
    ```
  </Step>

  <Step>
    Import Novu's SDK and provide the credentials to initialize the Novu instance:

    ```typescript
    import { Novu } from "@novu/api";

    const novu = new Novu({ 
      secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
    });
    ```
  </Step>
</Steps>

For the sake of this guide, we will create a new dedicated task for 2 common Novu actions:

* Trigger Notification Workflow
* Add New Subscriber

## Triggering Notifications

### Core Requirements

When calling Novu's `trigger` method, you must provide the following information:

<Steps>
  <Step>
    **Workflow ID**

    `workflowId` **(string):** This identifies the specific notification workflow you want to execute.

    **Note:** Ensure this workflow ID corresponds to an existing, active workflow in your Novu dashboard.
  </Step>

  <Step>
    **Recipient Information**

    `to` **(object):** This object specifies the recipient of the notification. At a minimum, it requires:

    * `subscriberId` **(string):** A unique identifier for the notification recipient within your system (e.g., a user ID).

    **Note:** If a subscriber with this `subscriberId` doesn't already exist in Novu, Novu will automatically create one when the workflow is triggered. You can also pass other identifiers like `email`, `phone`, etc., within the `to` object, depending on your workflow steps.
  </Step>
</Steps>

### Basic Trigger Example

Here's a simple Trigger.dev task that triggers a Novu workflow when the task runs.

```typescript
import { task, retry } from "@trigger.dev/sdk/v3";
import { Novu } from "@novu/api";

// Initialize the Novu client with your API key
// It's recommended to store your secret key securely, e.g., in environment variables.
const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
}); // Add '!' if you're sure it's defined, or handle potential undefined case

export const notifyUserTask = task({
  id: "notify-user-task",
  run: async (
    payload: { // Payload received by the Trigger.dev task
      userId: string;
      email: string;
    },
    { ctx } // Access context if needed, e.g., for logging
  ) => {
    const { userId, email } = payload;

    console.log(`Attempting to trigger Novu workflow for subscriber: ${userId}`);

    // Use retry logic for resilience against transient network issues or brief API unavailability
    await retry.onThrow(
      async () => {
        try {
          const triggerResult = await novu.trigger({
            // 1. Specify the workflow to trigger
            workflowId: "your-workflow-id", // Replace with your actual workflow ID

            // 2. Specify the recipient
            to: {
              subscriberId: userId,
              email: email, // Include other identifiers if needed by your workflow
            },

            // 3. Payload (optional) - see next section
            payload: {}, // Empty payload for this basic example
          });

          console.log("Novu workflow triggered successfully:", triggerResult.data);
          return triggerResult.data; // Return data if needed elsewhere

        } catch (error: unknown) {
          // Log the specific error for better debugging
          const errorMessage = error instanceof Error ? error.message : 'Unknown error triggering Novu';
          console.error("Failed to trigger Novu workflow:", errorMessage, error);
          // Throw a new error to ensure retry logic catches it
          throw new Error(`Novu trigger failed: ${errorMessage}`);
        }
      },
      {
        maxAttempts: 3, // Configure retry attempts
        factor: 2,      // Configure backoff strategy
        minTimeoutInMs: 1000, // Wait at least 1 second before first retry
        // Add more retry options as needed
      }
    );
  },
});
```

## Working with Dynamic Content

### Using Payloads

Often, you'll want your notifications to include dynamic data related to the event that triggered them. This is done using the `payload` property in the `novu.trigger` call.

<Accordions>
  <Accordion title="Understanding Payloads">
    The `payload` is an object containing key-value pairs that you can reference within your Novu notification templates using Handlebars syntax (e.g., `{{ name }}`, `{{ order.id }}`).
  </Accordion>
</Accordions>

### Example Use Case

Imagine you want to send an email confirming a background job's completion:

<Cards>
  <Card title="Email Template Variables">
    * **Subject:** `Job {{ jobName }} Completed Successfully!`
    * **Body:** `Hi {{ userName }}, your job '{{ jobName }}' finished processing.`
  </Card>
</Cards>

To achieve this, you would pass the `userName` and `jobName` in the `payload` object when triggering the workflow.

### Advanced Trigger Example

```typescript
import { task, retry } from "@trigger.dev/sdk/v3";
import { Novu } from "@novu/api";

const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});

export const notifyOnJobCompletion = task({
  id: "notify-on-job-completion",
  run: async (
    payload: {
      userId: string;
      email: string;
      name: string;
      jobId: string;
    }
  ) => {
    const { userId, email, name, jobId } = payload;

    await retry.onThrow(
      async () => {
        try {
          // Construct the payload specifically for Novu
          // This often uses data from the task's payload, but can include other computed values
          const novuPayload = {
            userName: name,   // Map 'name' from task payload to 'userName' for the template
            jobName: `Data Processing Job #${jobId}`, // Can include static text or transform data
          };

          await novu.trigger({
            workflowId: "inbox-test", // Use the appropriate workflow ID
            to: {
              subscriberId: userId,
              email: email,
            },
            payload: { // Pass the constructed payload to Novu
              ...novuPayload,
            },
          });
          
          console.log("Novu workflow triggered successfully with payload:", novuPayload);
          return novuPayload;

        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : 'Unknown error triggering Novu';
          console.error("Failed to trigger Novu workflow with payload:", errorMessage, error);
          throw new Error(`Novu trigger failed: ${errorMessage}`);
        }
      },
      { maxAttempts: 2 } // Retry the task up to 2 times
    );
  },
});
```

### Key Points about Payloads

<Cards>
  <Card title="Trigger.dev Task Payload">
    This is the data your Trigger.dev task receives when it's invoked. It contains the context needed for the task to run.
  </Card>

  <Card title="Novu Trigger Payload">
    This is the data you *specifically send to Novu* via the `payload` property in the `novu.trigger()` call. It's used for populating variables in your notification templates.
  </Card>
</Cards>

## Implementation Examples

### AI Tasks

This example demonstrates how to build a reliable AI content generation system that keeps users informed throughout the process using Novu notifications.

```typescript

import { task, event, eventTrigger, retry } from "@trigger.dev/sdk/v3";
import { Novu } from "@novu/api";
import OpenAI from "openai";

// Initialize clients
const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});

const openai = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'],
});

// Helper functions for prompt generation
function generateTextPrompt(theme: string, description: string) {
  return [
    { role: "system", content: "You are a creative writer crafting marketing content." },
    { role: "user", content: `Write a short, engaging paragraph about ${theme}. Key points: ${description}` }
  ];
}

function generateImagePrompt(theme: string, description: string) {
  return `Create a professional marketing image that represents ${theme}. Style: modern, clean. Details: ${description}`;
}

// Event trigger for content generation
export const contentGenerationRequested = event({
  id: "content-generation-requested",
  trigger: eventTrigger({
    name: "content.generation.requested",
  }),
});

// Notification task for successful completion
export const notifyContentReady = task({
  id: "notify-content-ready",
  run: async ({ 
    userId, 
    email, 
    theme, 
    contentId,
    contentPreview,
    imageUrl
  }: { 
    userId: string;
    email: string;
    theme: string;
    contentId: string;
    contentPreview: string;
    imageUrl: string;
  }) => {
    await retry.onThrow(
      async () => {
        try {
          await novu.trigger({
            workflowId: "ai-generation-completed",
            to: {
              subscriberId: userId,
              email: email,
            },
            payload: {
              userName: email.split('@')[0],
              theme: theme,
              contentId: contentId,
              contentPreview: contentPreview,
              imageUrl: imageUrl,
              viewUrl: `https://yourapp.com/content/${contentId}`
            },
          });
          
          console.log("Content ready notification sent successfully");
        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
          console.error("Failed to send content ready notification:", errorMessage);
          throw new Error(`Final notification failed: ${errorMessage}`);
        }
      },
      { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000 }
    );
  },
});

// Error notification task
export const notifyError = task({
  id: "notify-error",
  run: async ({ 
    userId, 
    email, 
    theme, 
    errorMessage 
  }: { 
    userId: string;
    email: string;
    theme: string;
    errorMessage: string;
  }) => {
    await retry.onThrow(
      async () => {
        try {
          await novu.trigger({
            workflowId: "ai-generation-error",
            to: {
              subscriberId: userId,
              email: email,
            },
            payload: {
              userName: email.split('@')[0],
              theme: theme,
              errorMessage: errorMessage,
              supportEmail: "support@yourapp.com"
            },
          });
          
          console.log("Error notification sent successfully");
        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
          console.error("Failed to send error notification:", errorMessage);
          // Not rethrowing here to prevent infinite loops when error notifications fail
        }
      },
      { maxAttempts: 2 }
    );
  },
});

// Main AI content generation task
export const generateContent = task({
  id: "generate-content",
  retry: {
    maxAttempts: 3,
  },
  run: async ({ userId, email, theme, description }: { 
    userId: string;
    email: string;
    theme: string;
    description: string; 
  }) => {
    console.log(`Starting AI content generation for theme: ${theme}`);
    
    // Generate text content
    const textResult = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [{ role: "user", content: description }]
    });

    if (!textResult.choices[0]?.message?.content) {
      throw new Error("No text content generated, retrying...");
    }
    
    // Generate image content
    const imageResult = await openai.images.generate({
      model: "dall-e-3",
      prompt: description,
      size: "1024x1024"
    });

    if (!imageResult.data[0]?.url) {
      throw new Error("No image generated, retrying...");
    }

    return {
      text: textResult.choices[0].message.content,
      imageUrl: imageResult.data[0].url,
    };
  },
});

// Main job that orchestrates the entire workflow
export const processContentRequest = task({
  id: "process-content-request",
  events: [contentGenerationRequested],
  run: async (payload: { 
    userId: string;
    email: string;
    theme: string;
    description: string;
  }) => {
    try {
      // Validate input
      if (!payload.theme || !payload.description) {
        throw new Error("Missing required parameters");
      }

      // Generate content
      const result = await generateContent.run(payload);
      
      const contentId = payload.userId + '-' + Date.now();
      
      // Send completion notification
      await notifyContentReady.run({ 
        userId,
        email,
        theme,
        contentId,
        contentPreview: result.text.substring(0, 100) + "...",
        imageUrl: result.imageUrl
      });
      
      return {
        success: true,
        contentId: contentId,
        ...result
      };
    } catch (error) {
      // If anything fails, ensure user gets notified
      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
      console.error("Content generation failed:", errorMessage);
      
      await notifyError.run({
        userId,
        email,
        theme,
        errorMessage: errorMessage
      });
      
      return {
        success: false,
        error: errorMessage
      };
    }
  },
});

```

<Accordions>
  <Accordion title="Breakdown">
    **The Key Components**

    1. **The AI Generation Task**

    ```typescript
    export const generateContent = task({
    id: "generate-content",
    retry: { maxAttempts: 3 },
    run: async ({ userId, email, theme, description }) => {
      // Generate text using GPT-4
      const textResult = await openai.chat.completions.create({
        model: "gpt-4",
        messages: [{ role: "user", content: description }]
      });
      
      // Generate image using DALL-E 3
      const imageResult = await openai.images.generate({
        model: "dall-e-3",
        prompt: description,
        size: "1024x1024"
      });
      
      return {
        text: textResult.choices[0].message.content,
        imageUrl: imageResult.data[0].url,
      };
    },
    });
    ```

    <Callout>
      This task handles the actual AI content generation:

      * It creates text content using GPT-4
      * It creates an image using DALL-E 3
      * It has built-in retry logic (will try up to 3 times if it fails)
    </Callout>

    ***

    2. **The Two Notification Tasks**

    **Completion Notification**

    ```typescript
    export const notifyContentReady = task({
      id: "notify-content-ready",
      run: async ({ userId, email, theme, contentId, contentPreview, imageUrl }) => {
        await novu.trigger({
          workflowId: "ai-generation-completed",
          to: { subscriberId: userId, email: email },
          payload: {
            userName: email.split('@')[0],
            theme: theme,
            contentPreview: contentPreview,
            // Other details...
          },
        });
      },
    });
    ```

    **Error Notification**

    ```typescript
    export const notifyError = task({
      id: "notify-error",
      run: async ({ userId, email, theme, errorMessage }) => {
        await novu.trigger({
          workflowId: "ai-generation-error",
          to: { subscriberId: userId, email: email },
          payload: {
            userName: email.split('@')[0],
            theme: theme,
            errorMessage: errorMessage,
            // Other details...
          },
        });
      },
    });
    ```

    ***

    3. **The Main Workflow Orchestrator**

    ```typescript
    export const processContentRequest = task({
      id: "process-content-request",
      events: [contentGenerationRequested],
      run: async (payload) => {
        try {
          // 1. Generate the content
          const result = await generateContent.run(payload);
          
          // 2. Send success notification
          await notifyContentReady.run({
            userId: payload.userId,
            email: payload.email,
            theme: payload.theme,
            contentId: payload.userId + '-' + Date.now(),
            contentPreview: result.text.substring(0, 100) + "...",
            imageUrl: result.imageUrl
          });
          
          return { success: true, ...result };
        } catch (error) {
          // 3. Send error notification if anything fails
          await notifyError.run({
            userId: payload.userId,
            email: payload.email,
            theme: payload.theme,
            errorMessage: error instanceof Error ? error.message : "Unknown error occurred"
          });
          
          return { success: false, error: error instanceof Error ? error.message : "Unknown error occurred" };
        }
      },
    });
    ```

    <Callout>
      This task:

      * Responds to the content generation event
      * Tries to generate content
      * Sends appropriate notifications based on success or failure
    </Callout>

    ***

    **Notification Workflows You Would Need in Novu**

    1. **ai-generation-completed**: Sent when content is successfully generated

    Workflow `payload` variables: `{{userName}}`, `{{theme}}`, `{{contentPreview}}`, `{{imageUrl}}`, `{{viewUrl}}`

    2. **ai-generation-error**: Sent when content generation fails

    Workflow `payload` variables: `{{userName}}`, `{{theme}}`, `{{errorMessage}}`, `{{supportEmail}}`
  </Accordion>
</Accordions>

### Video processing

This example shows how to build a video transcription service that notifies users when their video has been transcribed or if an error occurs during processing.

```typescript

import { task, event, eventTrigger, retry } from "@trigger.dev/sdk/v3";
import { Novu } from "@novu/api";
import fs from "fs";
import { Deepgram } from "@deepgram/sdk";

// Initialize clients
const novu = new Novu({ 
  secretKey: 'ApiKey ' + process.env['NOVU_SECRET_KEY']
});

const deepgram = new Deepgram(process.env['DEEPGRAM_API_KEY']);

// Utility functions for video processing
async function downloadFile(url: string): Promise<string> {
  // Implementation of file download logic
  console.log(`Downloading file from ${url}`);
  // This would be the actual implementation to download a file
  return "/tmp/downloaded-video.mp4";
}

async function convertToWav(filePath: string): Promise<string> {
  // Implementation of conversion logic
  console.log(`Converting ${filePath} to WAV format`);
  // This would be the actual implementation to convert video to WAV
  return "/tmp/audio-extract.wav";
}

// Event trigger for transcription request
export const transcriptionRequested = event({
  id: "transcription-requested",
  trigger: eventTrigger({
    name: "video.transcription.requested",
  }),
});

// Notification task for successful transcription
export const notifyTranscriptionComplete = task({
  id: "notify-transcription-complete",
  run: async ({ 
    userId, 
    email, 
    videoName,
    transcriptionId,
    wordCount,
    duration
  }: { 
    userId: string;
    email: string;
    videoName: string;
    transcriptionId: string;
    wordCount: number;
    duration: string;
  }) => {
    await retry.onThrow(
      async () => {
        try {
          await novu.trigger({
            workflowId: "transcription-completed",
            to: {
              subscriberId: userId,
              email: email,
            },
            payload: {
              userName: email.split('@')[0],
              videoName: videoName,
              transcriptionId: transcriptionId,
              wordCount: wordCount,
              duration: duration,
              viewUrl: `https://yourapp.com/transcriptions/${transcriptionId}`
            },
          });
          
          console.log("Transcription complete notification sent successfully");
        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
          console.error("Failed to send transcription complete notification:", errorMessage);
          throw new Error(`Notification failed: ${errorMessage}`);
        }
      },
      { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000 }
    );
  },
});

// Error notification task
export const notifyTranscriptionError = task({
  id: "notify-transcription-error",
  run: async ({ 
    userId, 
    email, 
    videoName, 
    errorMessage 
  }: { 
    userId: string;
    email: string;
    videoName: string;
    errorMessage: string;
  }) => {
    await retry.onThrow(
      async () => {
        try {
          await novu.trigger({
            workflowId: "transcription-error",
            to: {
              subscriberId: userId,
              email: email,
            },
            payload: {
              userName: email.split('@')[0],
              videoName: videoName,
              errorMessage: errorMessage,
              supportEmail: "support@yourapp.com"
            },
          });
          
          console.log("Transcription error notification sent successfully");
        } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : 'Unknown error';
          console.error("Failed to send error notification:", errorMessage);
          // Not rethrowing here to prevent infinite loops when error notifications fail
        }
      },
      { maxAttempts: 2 }
    );
  },
});

// Main transcription task
export const transcribeVideo = task({
  id: "transcribe",
  retry: {
    maxAttempts: 3,
  },
  machine: { preset: "large-2x" }, // Use larger machine for faster processing
  run: async (payload: { 
    id: string; 
    url: string;
    userId?: string;
    email?: string;
    videoName?: string;
  }) => {
    try {
      console.log(`Starting transcription for video: ${payload.videoName || payload.id}`);
      
      // Download and process the video
      const downloadedFile = await downloadFile(payload.url);
      const extractedAudio = await convertToWav(downloadedFile);

      // Transcribe using Deepgram
      const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
        fs.createReadStream(extractedAudio),
        {
          model: "nova",
          language: "en-US",
          smart_format: true,
          diarize: true
        }
      );

      if (error || !result) {
        throw new Error(error || "Failed to transcribe video");
      }

      // Calculate some metadata from the result
      const wordCount = result.results?.utterances?.reduce((count, utterance) => count + utterance.words.length, 0) || 0;
      const duration = result.metadata?.duration 
        ? `${Math.floor(result.metadata.duration / 60)}:${Math.floor(result.metadata.duration % 60).toString().padStart(2, '0')}`
        : "Unknown";

      // Store in database
      const dbResult = await db.transcriptions.create(payload.id, result.results);
      
      return {
        transcriptionId: dbResult.id,
        wordCount,
        duration,
        transcript: result.results
      };
    } catch (error) {
      console.error("Error in transcription process:", error);
      throw error; // Rethrow to trigger retry
    }
  },
});

// Main job that orchestrates the entire workflow
export const processTranscriptionRequest = task({
  id: "process-transcription-request",
  events: [transcriptionRequested],
  run: async (payload: { 
    id: string;
    url: string;
    userId: string;
    email: string;
    videoName: string;
  }) => {
    try {
      // Validate input
      if (!payload.url) {
        throw new Error("Missing video URL");
      }

      // Transcribe video
      const result = await transcribeVideo.run(payload);
      
      // Send completion notification
      await notifyTranscriptionComplete.run({
        userId: payload.userId,
        email: payload.email,
        videoName: payload.videoName || "Your video",
        transcriptionId: result.transcriptionId,
        wordCount: result.wordCount,
        duration: result.duration
      });
      
      return {
        success: true,
        transcriptionId: result.transcriptionId,
        transcript: result.transcript
      };
    } catch (error) {
      // If anything fails, ensure user gets notified
      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
      console.error("Transcription failed:", errorMessage);
      
      await notifyTranscriptionError.run({
        userId: payload.userId,
        email: payload.email,
        videoName: payload.videoName || "Your video",
        errorMessage: errorMessage
      });
      
      return {
        success: false,
        error: errorMessage
      };
    }
  },
});

// Type declaration for database operations (mock)
const db = {
  transcriptions: {
    create: async (id: string, results: unknown) => {
      console.log(`Storing transcription results for ${id} in database`);
      return { id, created: new Date() };
    }
  }
};

```

<Accordions>
  <Accordion title="Breakdown">
    **How It Works**

    * A user uploads a video for transcription
    * The system processes the video using Deepgram's API
    * The user receives a notification when transcription is complete or if an error occurs

    **The Key Components**

    1. **Transcription Task**

    The core of this workflow is the `transcribeVideo` task that handles the actual transcription:

    ```typescript
    export const transcribeVideo = task({
      id: "transcribe",
      retry: { maxAttempts: 3 },
      machine: { preset: "large-2x" }, // Use larger machine for faster processing
      run: async (payload) => {
        // Download the video file
        const downloadedFile = await downloadFile(payload.url);
        
        // Extract and convert audio to WAV format
        const extractedAudio = await convertToWav(downloadedFile);

        // Transcribe using Deepgram
        const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
          fs.createReadStream(extractedAudio),
          { model: "nova" }
        );

        // Store results in database
        return await db.transcriptions.create(payload.id, result?.results);
      },
    });
    ```

    <Callout>
      **This task:**

      * Downloads the video file from a URL
      * Extracts audio and converts it to WAV format
      * Sends the audio to Deepgram for transcription
      * Stores the results in a database
    </Callout>

    ***

    2. **Notification Tasks**

    There are two notification tasks:

    **Success Notification**

    ```typescript
    export const notifyTranscriptionComplete = task({
      id: "notify-transcription-complete",
      run: async ({ userId, email, videoName, transcriptionId, wordCount, duration }) => {
        await novu.trigger({
          workflowId: "transcription-completed",
          to: { subscriberId: userId, email },
          payload: {
            userName: email.split('@')[0],
            videoName,
            wordCount,
            duration,
            viewUrl: `https://yourapp.com/transcriptions/${transcriptionId}`
          },
        });
      },
    });
    ```

    **Error Notification**

    ```typescript
    export const notifyTranscriptionError = task({
      id: "notify-transcription-error",
      run: async ({ userId, email, videoName, errorMessage }) => {
        await novu.trigger({
          workflowId: "transcription-error",
          to: { subscriberId: userId, email },
          payload: {
            userName: email.split('@')[0],
            videoName,
            errorMessage,
            supportEmail: "support@yourapp.com"
          },
        });
      },
    });
    ```

    ***

    3. **Main Workflow Orchestrator**

    ```typescript
    export const processTranscriptionRequest = task({
      id: "process-transcription-request",
      events: [transcriptionRequested],
      run: async (payload) => {
        try {
          // 1. Validate and transcribe video
          const result = await transcribeVideo.run(payload);
          
          // 2. Send success notification
          await notifyTranscriptionComplete.run({
            userId: payload.userId,
            email: payload.email,
            videoName: payload.videoName || "Your video",
            transcriptionId: result.transcriptionId,
            wordCount: result.wordCount,
            duration: result.duration
          });
          
          return { success: true, transcriptionId: result.transcriptionId };
        } catch (error) {
          // 3. Send error notification if anything fails
          await notifyTranscriptionError.run({
            userId: payload.userId,
            email: payload.email,
            videoName: payload.videoName || "Your video",
            errorMessage: error instanceof Error ? error.message : "Unknown error occurred"
          });
          
          return { success: false, error: error instanceof Error ? error.message : "Unknown error occurred" };
        }
      },
    });
    ```

    ***

    **Usage**

    1. **Create two notification workflows in Novu:**

    * transcription-completed with `payload` variables: `{{userName}}`, `{{videoName}}`, `{{wordCount}}`, `{{duration}}`, `{{viewUrl}}`
    * transcription-error with `payload` variables: `{{userName}}`, `{{videoName}}`, `{{errorMessage}}`, `{{supportEmail}}`

    2. **Trigger the workflow by sending an event:**

    ```typescript
    // Example of triggering the workflow
    await client.triggerEvent({
      name: "video.transcription.requested",
      payload: {
        id: "video-123",
        url: "https://storage.example.com/videos/meeting-recording.mp4",
        userId: "user-456",
        email: "user@example.com",
        videoName: "Weekly Team Meeting"
      }
    });
    ```

    **Example Notifications**

    Success notification email:

    <Callout>
      **Subject**: Your video "Weekly Team Meeting" has been transcribed

      Hello John,

      Good news! We've finished transcribing your video "Weekly Team Meeting".

      Details:

      * Duration: 32:15
      * Word count: 4,320

      You can view and edit your transcription here:
      [https://yourapp.com/transcriptions/transcript-789](https://yourapp.com/transcriptions/transcript-789)

      Thanks for using our service!
    </Callout>

    Error notification email:

    <Callout>
      **Subject**: Issue with transcribing "Weekly Team Meeting"

      Hello John,

      We encountered a problem while transcribing your video "Weekly Team Meeting".

      Error details: The audio quality was too low for accurate transcription.

      Please try uploading your video again with improved audio, or contact [support@yourapp.com](mailto:support@yourapp.com) if you need assistance.

      We apologize for the inconvenience.
    </Callout>

    This workflow provides a complete solution for transcribing videos and keeping users informed about the process status, all while handling errors gracefully.
  </Accordion>
</Accordions>

## Managing Subscribers

Before triggering notifications, Novu needs to know *who* to notify. That's where subscribers come in. A **subscriber** in Novu represents a user (or entity) that can receive notifications through one or more channels (in-app, email, SMS, etc.).

### When to Create Subscribers

Create or update a subscriber in Novu when:

<Steps>
  <Step>
    **New User Registration**

    When a new user signs up or is added to your system
  </Step>

  <Step>
    **Notification Eligibility**

    When a user becomes eligible to receive notifications
  </Step>

  <Step>
    **Data Updates**

    When you want to ensure subscriber metadata (name, phone, etc.) is up-to-date
  </Step>
</Steps>

<Callout type="info">
  If you trigger a workflow with a `subscriberId` that doesn't exist, Novu will auto-create the subscriber. However, doing it explicitly ensures full control over subscriber data.
</Callout>

### Subscriber Creation Example

```typescript
import { task, retry } from "@trigger.dev/sdk/v3";
import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: 'ApiKey ' + process.env["NOVU_SECRET_KEY"]
});

export const createSubscriberTask = task({
  id: "create-subscriber-task",
  run: async (payload: {
    userId: string;
    email?: string;
    firtName?: string;
    lastName?: string;
    phone?: string;
    locale?: string;
    avatar?: string;
    data?: object;
  }) => {
    const { userId, email, name, phone, avatar } = payload;

    // Split full name into first and last (fallback to empty string)
    const [firstName, lastName = ""] = name.split(" ");

    // Create subscriber object for Novu
    const subscriber = {
      subscriberId: userId,
      email,
      firstName,
      lastName,
      phone,
      locale,
      avatar,
      data,
    };

    await retry.onThrow(
      async () => {
        console.log("Creating Novu subscriber:", subscriber);

        const result = await novu.subscribers.create(subscriber);

        console.log("Subscriber created successfully:", result);
        return result;
      },
      {
        maxAttempts: 2,
      }
    );
  },
});
```

### Using Subscriber Data in Templates

Once you've added custom fields to a subscriber, you can use them in Novu templates using Handlebars:

<Tabs items={['Basic Fields', 'Contact Info', 'Custom Data']}>
  <Tab value="Basic Fields">Hi `{{subscriber.firstName}}`, welcome!</Tab>
  <Tab value="Contact Info">We'll reach you at `{{subscriber.phone}}` if needed.</Tab>
  <Tab value="Custom Data">Your account is set up under `{{subscriber.data.userName}}`.</Tab>
</Tabs>

## Best Practices

<Accordions>
  <Accordion title="Data Management Best Practices">
    As a best practice, maintain consistent subscriber identification:

    * Use your internal `userId` as the `subscriberId` in Novu
    * Keep this mapping consistent across all integrations
    * Store notification preferences and settings in your user model
    * Consider adding a reference field in your user table: `novuSubscriberId`

    Example user model:

    ```typescript
    interface User {
      id: string;
      email: string;
      novuSubscriberId: string; // Same as user.id
      notificationPreferences: {
        marketing: boolean;
        updates: boolean;
        // ... other preferences
      }
    }
    ```

    This ensures reliable user tracking and simplifies debugging notification issues.
  </Accordion>

  <Accordion title="Proactive Data Synchronization">
    Keep subscriber data synchronized by:

    * Updating Novu whenever user contact info changes
    * Implementing webhooks to handle notification delivery status
    * Setting up retry mechanisms for failed updates

    ```typescript
    // Example of proactive update
    async function updateUserProfile(userId: string, newData: UserUpdateData) {
      // Update your database
      await db.users.update(userId, newData);
      
      // Sync with Novu
      await novu.subscribers.update(userId, {
        email: newData.email,
        phone: newData.phone,
        data: { lastUpdated: new Date() }
      });
    }
    ```
  </Accordion>

  <Accordion title="Enriching Subscriber Data">
    Enhance notifications with contextual data:

    * Store user preferences, roles, and settings
    * Include relevant business logic flags
    * Add metadata for analytics and tracking

    ```typescript
    // Example of rich subscriber data
    await novu.subscribers.update(userId, {
      data: {
        role: 'admin',
        subscriptionTier: 'premium',
        features: ['advanced-analytics', 'priority-support']
      }
    });
    ```
  </Accordion>
</Accordions>


# API Idempotency (/api-reference/idempotency)

Learn how to use idempotency keys to safely retry API requests without causing duplicate operations

Idempotency is a crucial feature for building reliable integrations with Novu's API. It allows you to safely retry requests without worrying about duplicate operations, which is especially important for critical actions like triggering workflows.

An idempotent request is one that can be made multiple times with the same effect as making it once. This is achieved by including a unique idempotency key with your request.

<Callout type="info">
  Idempotency feature is currently not enabled for all organizations. Please contact us at [support@novu.co](mailto:support@novu.co) to enable it for your organization.
</Callout>

## How It Works

When you send a request with an idempotency key:

1. Novu checks if a request with the same key has been processed before
2. If it's a new key, the request is processed normally and the response is cached
3. If the key was seen before, Novu returns the cached response without reprocessing the request

This mechanism protects against network issues, timeouts, and other scenarios where a request might be retried.

## Using Idempotency Keys

To make an idempotent request, include the `Idempotency-Key` header with a unique identifier:

```bash
curl -X POST https://api.novu.co/v1/events/trigger \
  --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
  --header 'Idempotency-Key: unique-request-id-12345' \
  --header 'Content-Type: application/json' \
  --data '{"name": "workflow-id", "to": {"subscriberId": "subscriber-123"}}'
```

### Key Requirements

* **Maximum length**: 255 characters
* **Uniqueness**: Keys should be unique per organization
* **Format**: Any string value (UUIDs are recommended)

<Callout type="info">
  We recommend using UUIDs or other unique identifiers that include context about the operation, such as `order-confirmation-{orderId}-{timestamp}`.
</Callout>

## Supported Methods

Idempotency is supported for the following HTTP methods:

| Method | Supported |
| ------ | --------- |
| POST   | ✅ Yes     |
| PATCH  | ✅ Yes     |
| GET    | ❌ No      |
| PUT    | ❌ No      |
| DELETE | ❌ No      |

<Callout>
  GET, PUT, and DELETE methods are inherently idempotent by design and don't require idempotency keys.
</Callout>

## Authentication Requirements

Idempotency is only available when authenticating with an API Key:

```bash
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>'
```

Requests using other authentication methods will be processed normally without idempotency support.

## Cache Duration

| Scenario            | Cache TTL |
| ------------------- | --------- |
| Successful response | 24 hours  |
| Error response      | 24 hours  |
| In-progress request | 5 minutes |

After the cache expires, the same idempotency key can be reused.

## HTTP Response Headers

When making idempotent requests, Novu includes helpful headers in the response:

### Idempotency-Key

Confirms the idempotency key that was used for the request:

```
Idempotency-Key: unique-request-id-12345
```

### Idempotency-Replay

Indicates that the response was served from the cache rather than processing a new request:

```
Idempotency-Replay: true
```

This header is only present when returning a cached response.

## Error Handling

### Request In Progress (409 Conflict)

If you send a request with an idempotency key while a previous request with the same key is still being processed:

```json
{
  "statusCode": 409,
  "message": "Request with key \"unique-request-id-12345\" is currently being processed. Please retry after 1 second"
}
```

The response includes a `Retry-After` header indicating when to retry:

```
Retry-After: 1
```

### Key Reused with Different Body (422 Unprocessable Entity)

If you send a request with an idempotency key that was previously used with a different request body:

```json
{
  "statusCode": 422,
  "message": "Request with key \"unique-request-id-12345\" is being reused for a different body"
}
```

<Callout type="warn">
  Each idempotency key must be associated with a specific request body. Using the same key with different payloads will result in an error.
</Callout>

### Key Too Long (400 Bad Request)

If the idempotency key exceeds 255 characters:

```json
{
  "statusCode": 400,
  "message": "idempotencyKey \"...\" has exceeded the maximum allowed length of 255 characters"
}
```

## Best Practices

1. **Generate unique keys**: Use UUIDs or combine entity IDs with timestamps to ensure uniqueness
2. **Store keys**: Keep track of idempotency keys you've used in case you need to retry requests
3. **Handle 409 responses**: Implement retry logic with exponential backoff when you receive a conflict response
4. **Don't reuse keys for different operations**: Each unique operation should have its own idempotency key
5. **Include meaningful context**: Consider including the operation type and relevant IDs in your key for easier debugging

## Example: Safe Retry Logic

Here's an example of implementing safe retry logic with idempotency:

```javascript
import { Novu } from '@novu/api';
import { v4 as uuidv4 } from 'uuid';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>"
});

async function triggerNotificationWithRetry(workflowId, subscriberId, payload, maxRetries = 3) {

  const uniqueId = uuidv4();
  const idempotencyKey = `trigger-${workflowId}-${subscriberId}-${uniqueId}`;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await novu.trigger({
        workflowId: workflowId,
        to: { subscriberId: subscriberId },
        payload,
      }, idempotencyKey);
        
      return response;
    } catch (error) {
      if (error.statusCode === 409 && attempt < maxRetries) {
        // Request in progress, wait and retry
        const retryAfter = error.headers?.['retry-after'] || 1;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
}
```


# Novu API Reference Overview (/api-reference)

Complete Novu API reference covering authentication, endpoints, rate limits, and server-side integration for notifications.

<Callout>
  It's important to note that our API and backend SDK are intended for use exclusively in
  server-side applications. **Attempting to use them in a client-side application will result in
  Cross-Origin Resource Sharing (CORS) errors.** This restriction ensures the security and integrity
  of our services.
</Callout>

## Authentication

Authentication for the Novu API involves the use of an API Key, which is a secure credential that is tied to your Novu account. This key should be included in the header of the request in the Authorization field as a string prefixed with 'ApiKey '.

```bash
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>'
```

For example, when using Novu in a Node.js application, the Novu package should be imported and initialized with the API key, as shown in this snippet:

```javascript
import { Novu } from '@novu/api';
const novu = new Novu({
  secretKey: "NOVU_SECRET_KEY",
});
```

Replace `<NOVU_SECRET_KEY>` with your actual API Key, available in the API Key section of the Novu Dashboard.

<Callout type="warn">
  It is advised not to hardcode your credentials in a file in production environments. Use
  environment variables instead.
</Callout>

## API Endpoints

Novu provides a multitude of API endpoints that enable a variety of functionalities. the base URL for the Novu API is `https://api.novu.co/v1`.

<Callout>
  We offer two API options: the US API and the EU API. By default, our API documentation refers to the US API, which can be accessed at: [https://api.novu.co/v1](https://api.novu.co/v1).

  If you require the EU version, you can access it here: [https://eu.api.novu.co/v1](https://eu.api.novu.co/v1).
</Callout>

For instance, to get tenant information, the endpoint to use would include the tenant's identifier and look like this `https://api.novu.co/v1/tenants/{identifier}`.


# API Payload Limits (/api-reference/payload-limits)

Understand payload size limits for Novu API requests and workflow triggers. Structure event payloads to avoid validation failures and rejected requests.

Payload size limits are an essential functionality for ensuring optimal performance and reliability of the system. They safeguard system resources by preventing oversized payloads from impacting API performance and ensure efficient processing of event triggers.

## Payload size limit

All event trigger operations have a **512KB (524,288 bytes)** payload size limit. This limit applies to the following endpoints:

* **Trigger event** - Single event triggers
* **Bulk trigger event** - Batch event triggers
* **Broadcast event** - Events sent to all subscribers

<Callout type="info">
  Attachments are excluded from the payload size calculation and have a separate size limit.
</Callout>

## What counts towards the limit

The payload size limit includes:

* Event payload data
* Custom data and properties
* All other request body content

## Error messages

When your payload exceeds the 512KB limit, you'll receive an error response indicating the exact size and the limit exceeded.

### Single event trigger

For single event triggers (`/events/trigger`), the error response will be:

```json
{
  "statusCode": 413,
  "message": "Payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

### Bulk trigger event

For bulk event triggers (`/events/trigger/bulk`), the error response includes the index of the event that exceeded the limit:

```json
{
  "statusCode": 413,
  "message": "Event at index 1 (workflow: \"workflow-name\") has payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

<Callout type="info">
  When using bulk trigger, each event in the array is validated individually against the 512KB limit. Ensure that every event payload stays within the limit.
</Callout>

### Broadcast event

For broadcast events (`/events/trigger/broadcast`), the error response will be:

```json
{
  "statusCode": 413,
  "message": "Payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

## Attachment size limit

Email attachments have a separate size limit:

* **Total attachment size**: 20MB for all attachments included in an email.
  Attachments do not count towards the 512KB payload limit

<Callout>For more information about sending email attachments, refer to the [Sending Attachments](/platform/integrations/email#sending-attachments) documentation.</Callout>

## Related documentation

* [Rate Limiting](/api-reference/rate-limiting) - Learn about API rate limits
* [Trigger Event](/api-reference/events/trigger-event) - Single event trigger API
* [Bulk Trigger Event](/api-reference/events/bulk-trigger-event) - Batch event trigger API
* [Broadcast Event](/api-reference/events/broadcast-event-to-all) - Broadcast to all subscribers


# API Rate Limiting (/api-reference/rate-limiting)

In this page you can learn about how rate limiting works with Novu's API

Rate limiting is an essential functionality for establishing a robust and resilient system. It safeguards system resources from being misused by malicious actors or being monopolized by one client.

A variable-cost token bucket rate limited algorithm has been added to provide the capability for different API controllers and methods to have a varying cost. It also lays a foundation for dynamic costing of resource consumption.

## Limits

The following limits apply to each category of the Novu system. Each category has an independent bucket of request tokens to consume from.
Standard requests cost 1 request token and bulk requests cost 100 request tokens. Both standard and bulk requests consume from the same token pool.

Each category has a different limit of requests per second (RPS), with the endpoints in each category shown below.

| Category      | Free   | Pro     | Team    | Enterprise | Endpoints                                                                                 |
| ------------- | ------ | ------- | ------- | ---------- | ----------------------------------------------------------------------------------------- |
| Events        | 60 RPS | 240 RPS | 600 RPS | 6K RPS     | Trigger                                                                                   |
| Configuration | 20 RPS | 80 RPS  | 200 RPS | 2k RPS     | Subscribers, Topics, Channel Connections, Channel Endpoints, Workflows                    |
| Global        | 30 RPS | 120 RPS | 300 RPS | 3K RPS     | All other endpoints including context endpoints consume request tokens from this category |

### HTTP response headers

When integrating with Novu API, it’s important to consider the rate limiting HTTP headers included in the response. These headers help you manage your API usage and avoid hitting rate limits.

```
RateLimit-Remaining: 219
RateLimit-Limit: 300
RateLimit-Reset: 2
RateLimit-Policy: 300;w=5;burst=330;comment="token bucket";category="trigger";cost="bulk";serviceLevel="free"
```

* `RateLimit-Remaining` - Indicates the remaining number of request tokens in the current window.
* `RateLimit-Limit` - Indicates the total number of request tokens available in the current window.
* `RateLimit-Reset` - Indicates the number of seconds until the current window resets and the request token limit is fully replenished.
* `RateLimit-Policy` - Defines the details of the applied rate limiting policy.
* `Retry-After` - Specifies the number of seconds to wait before making another request.


# Novu Framework Chat Channel (/framework/chat-channel)

Learn the process of configuring and using chat providers with Novu

Novu brings chat notifications into your development workflow, giving you a unified way to manage messaging across platforms and apps. Whether you're working with tools like Slack or Microsoft Teams or apps like WhatsApp, Telegram, and Discord, Novu lets you integrate, manage, and scale chat notifications without unnecessary complexity.

Learn more about the [Chat Channel](/platform/integrations/chat).

```tsx
await step.chat('chat', async () => {
  return {
    body: 'A new post has been created',
  };
});
```


# Novu Framework Controls (/framework/controls)

Learn how to use Controls in your notification workflows

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Controls are defined using [JSON Schema](/framework/schema/json-schema) or [Zod](https://zod.dev), providing a strong run-time validation system for your workflows.

This ensures that you as the developer and your non-technical peers are speaking the same language. Those responsible for styling and copy can edit with confidence, knowing their changes are tested in code.

## Controls vs Payload

**Control Schema** - For Non-Technical Peers and Developers. Managed in the Novu Dashboard UI, defined by developers and used by non-technical peers.

**Payload Schema** - For Developers. Passed during the `novu.trigger` method, and controlled by the developer.

## Common usecases

* **Content** - Modify any static content: email subject, email body, push notification title, etc...
* **Styling** - Modify the styling of the content: button color, background color, font size, etc...
* **Behaviour** - Modify the behaviour of the content: show/hide a section, show/hide a button, etc...
* **Order** - Modify the order of the content: the order of the email sections, the order of the buttons, etc...
* **Actions** - Modify the behaviour of actions: digest duration, etc...
* **Other** - Any other use case that should be controller without modifying code

## Step Controls

Step Control schema defines the control passed during the `step` method. These controls can be modified and persisted in the Novu Dashboard UI. The snippet below shows a configuration for the Step Control schema. If you don't provide a schema, Typescript will infer the data type to `unknown`, reminding you of the best practice to specify your schema.

<Tabs items={['Zod Schema', 'Class-Validator Schema', 'JSON Schema']}>
  <Tab value="Zod Schema">
    ```tsx
    import { z } from 'zod';
    import { render } from 'react-email';
    import { ReactEmailContent } from './ReactEmailContent';

    workflow('new-signup', async ({ step, payload }) => {
      await step.email(
        'send-email',
        async (controls) => {
          return {
            subject: controls.subject,
            body: render(
              <ReactEmailContent hideBanner={controls.hideBanner} components={controls.components} />
            ),
          };
        },
        {
          controlSchema: z.object({
            hideBanner: z.boolean().default(false),
            subject: z.string().default('Hi {{subscriber.firstName | capitalize}}'),
            components: z.array(
              z.object({
                type: z.enum(['header', 'cta-row', 'footer']),
                content: z.string(),
              })
            ),
          }),
        }
      );
    });
    ```
  </Tab>

  <Tab value="Class-Validator Schema">
    ```tsx
    import { IsString, IsNotEmpty, IsOptional, IsBoolean } from 'class-validator';
    import { Type } from 'class-transformer';
    import { render } from 'react-email';
    import { ReactEmailContent } from './ReactEmailContent';

    class NewSignUpComponent {
      @IsString()
      subject: string;

      @IsString()
      content: string;
    }
    class NewSignUpControlSchema {
      @IsBoolean()
      hideBanner: boolean;

      @IsString()
      @IsNotEmpty()
      @IsOptional()
      subject?: string;

      // Allowing no code control over the component in the Dashboard UI
      @Type(() => NewSignUpComponent)
      @NestedValidation({ each: true })
      @IsOptional()
      components?: NewSignUpComponent[];
    }

    workflow('new-signup', async ({ step, payload }) => {
      await step.email(
        'send-email',
        async (controls) => {
          return {
            subject: controls.subject,
            body: render(
              <ReactEmailContent hideBanner={controls.hideBanner} components={controls.components} />
            ),
          };
        },
        {
          // Learn about Class-Validator Schema here: https://github.com/typestack/class-validator
          controlSchema: NewSignUpControlSchema,
        }
      );
    });
    ```
  </Tab>

  <Tab value="JSON Schema">
    ```tsx
    workflow("new-signup", async ({ step, payload }) => {
      await step.email(
        "send-email",
        async (controls) => {
          return {
            subject: controls.subject,
            body: render(
              <ReactEmailContent
                hideBanner={controls.hideBanner}
                components={controls.components}
              />
            ),
          };
        },
        {
          // Learn about JSON Schema here: https://json-schema.org/specification
          controlSchema: {
            // Always `object`
            type: "object",
            // Specify the properties to validate. Supports deep nesting.
            properties: {
              hideBanner: { type: "boolean", default: false },
              subject: { type: "string", default: 'Hi {{subscriber.firstName | capitalize}}' },
              // Allowing no code control over the component in the Dashboard UI
              components: {
                type: "array",
                items: {
                  type: "object",
                },
                properties: {
                  subject: { type: "string" },
                  content: { type: "string" },
                }
              },
            },
            // Specify the array of which properties are required.
            required: ["hideBanner"],
            // Used to enforce full type strictness, with no rogue properties.
            additionalProperties: false,
            // The `as const` is important to let Typescript know that this
            // type won't change, enabling strong typing on `inputs` via type
            // inference of the provided JSON Schema.
          } as const,
        }
      );
    });
    ```
  </Tab>
</Tabs>

For the full list of parameters, check out the [full SDK reference](/framework/typescript/steps).

## Schema Validation & IDE IntelliSense

You can use **Zod, Class-Validator or JSON Schema** based on your needs.

* **[Zod](https://zod.dev/)** - A TypeScript-first schema declaration and validation library. *(Novu supports Zod v3)*
* **[Class-Validator](https://github.com/typestack/class-validator)** - A TypeScript-first validation library using decorators for OOP-style applications.
* **[JSON Schema](/framework/schema/json-schema)** - The most popular schema language for defining JSON data structures.

If you only want local IDE IntelliSense, you are able to pass plain JS Classes, which will not provide any Schema Definition useable by Novu Platform.

All provided **Zod** and **Class-Transformer** Schemas are compiled into **JSON Schema** which is passed to Novu. This ensures a consistent validation approach and UX by managing Payload and Control Data directly from the Platform.

<Callout type="warn">
  There may be inconsistencies when using Class-Transformer especially with nested schema objects.
  Please check out the guidelines on converting Class-Transformer classes to JSON Schema before
  using it here:
  [class-validator-jsonschema](https://www.npmjs.com/package/class-validator-jsonschema).
</Callout>

## Using Variables

To facilitate the use of variables in the control schema, enclose the variable name in double curly braces using the `{{variableName}}` syntax. For example, `{{subscriber.firstName | capitalize}}` will be dynamically replaced with the actual value of the subscriber's first name at runtime. You can use variables in any step control value, whether set by the developer or within the Novu Dashboard UI. To facilitate this, the Novu Dashboard UI offers auto-completion for variables. Simply start typing `{{` to view a list of all available variables.

![Example for variables autocomplete in dashboard](/images/controls-autocomplete.gif)

### Variable Options

* **Subscriber Attributes**: Access all [subscriber attributes](/platform/concepts/subscribers#subscriber-attributes). Example: `{{subscriber.firstName}}`
* **Payload Variables**: Use all payload variables defined in the `payloadSchema`. Example: `{{payload.userId}}`
* **Liquid Filters**: Apply [liquid filters](https://liquidjs.com/filters/overview.html) to format or manipulate variable values. Examples: `{{subscriber.firstName | append: ': ' | append: payload.status | capitalize}}` or `{{payload.invoiceDate | date: '%a, %b %d, %y'}}` will format the date as `Thu, Jan 01, 24`


# Custom Action Step (/framework/custom)

Used to execute any custom code as a step in the workflow.

A custom steps allows to execute any custom logic and persist in the durable execution context. The result of this step can be used in subsequent steps.

## Common usecases

* Making an API call to 3rd party service
* Fetch data from a database to be used in subsequent steps
* Execute a custom logic to transform data
* Custom provider implementation

## Custom Step Interface

```tsx
const stepResult = await step.custom(
  'custom-step',
  async () => {
    return {
      item_name: 'A product name',
      item_price: 100,
    };
  },
  {
    outputSchema: {
      type: 'object',
      properties: {
        item_name: { type: 'string' },
        item_price: { type: 'number' },
      },
      required: ['item_name', 'item_price'],
    },
  }
);
```

### Output Schema Definition

This JSON Schema definition is used to validate the output of the custom step. If the output does not match the schema, the workflow will fail. Novu Framework will infer the Typescript interface from the JSON Schema definition.

### Return Value

The Custom Step function should return a valid serializable object. The return value will be persisted in the durable execution context.

## Using the Custom Step Result

The result can only be used in the `resolver` of the step/providers/skip functions of subsequent steps.

```tsx
workflow('hello-world-workflow', async ({ payload }) => {
  const task = await step.custom(
    'fetch-db-data',
    async () => {
      const taskData = db.fetchTask(payload.task_id);
      return {
        task_id: taskData.id,
        task_title: taskData.title,
        complete: taskData.complete,
      };
    },
    {
      outputSchema: {
        type: 'object',
        properties: {
          task_title: { type: 'string' },
          task_id: { type: 'string' },
          complete: { type: 'boolean' },
        },
        required: ['task_id', 'complete'],
      },
    }
  );

  await step.email(
    'send-email',
    () => {
      return {
        subject: `Task reminder for ${task.task_title}`,
        body: 'Task is not yet complete. Please complete the task.',
      };
    },
    {
      // Only send the reminder E-mail if the task is not complete
      skip: () => !task.complete,
    }
  );
});
```

To read more about the full list of parameters, check out the [full SDK reference](/framework/typescript/steps/custom).


# Framework Delay Implementation (/framework/delay)

Learn how to use Delay steps in your notification workflows

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The delay action awaits a specified amount of time before moving on to trigger the following steps of the workflow.

Learn more about the [Delay](/platform/workflow/add-and-configure-steps#delay).

## Common usecases

* Waiting for X amount of time before sending the message
* Wait for a short period of time before sending a push message in case the user seen the notification in the Inbox Component
* Allow the user some time to cancel an action that generated a notification

## Adding a delay step

Delay steps can be inserted at any stage of your workflow execution, they can happen after or before any action. The workflow execution will be halted for the given amount of time and then resumed to the next step in the flow.

The action can also be skipped using the skip parameter conditionally to allow more complex usecases of when to wait and when to send an email immediately.

<Tabs items={['Delay with skip condition', 'Delay and Inbox step']}>
  <Tab value="Delay with skip condition">
    Here, we are delaying the execution of the next step by 1 day and skipping the delay step if the isCriticalMessage function returns true.

    ```tsx
    await step.delay(
      'delay',
      () => {
        return {
          type: 'regular',
          unit: 'days',
          amount: 1,
        };
      },
      {
        skip: () => isCriticalMessage(),
      }
    );
    ```
  </Tab>

  <Tab value="Delay and Inbox step">
    Here, we are delaying the execution of the in-app step by 30 minutes and sending the in-app notification only if the subscriber has `goalReminderInAppAllowed` set to `true` for subscriber. If during 30 minutes delay window, subscriber sets `goalReminderInAppAllowed` to `false`, the in-app step will be skipped.

    ```tsx
    export const goalReminderInAppAfterDelay = workflow(
      'goal-reminder-in-app-after-delay',
      async ({ step, subscriber }) => {
        await step.delay('delay-step', async () => {
          return {
            type: 'regular',
            amount: 30,
            unit: 'minutes',
          };
        });

        await step.inApp(
          'in-app-step',
          async () => {
            return {
              subject: `Don't Forget Your Fitness Goals Today!`,
              body: `Hey ${subscriber.firstName}, it's been a while since you logged your
                    last activity. Keep up the momentum and complete your workout to stay on
                    track with your goals!`,
            };
          },
          {
            skip: () => subscriber.data?.goalReminderInAppAllowed === false,
          }
        );
      }
    );
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Changing the step content after triggering the workflow with delay step will not affect the
  existing pending delayed notification content.
</Callout>

## Frequently Asked Questions

### If delay step fails, will the workflow continue to the next step?

No, workflow execution will stop immediately if the delay step fails due to an error.


# Digest Action Step (/framework/digest)

Learn how to use the Digest Engine to collect multiple events into a single message

You can use the Digest Engine to collect multiple events to a single message. Learn more about the [Digest Engine](/platform/workflow/add-and-configure-steps#digest).

## Defining a digest step

```tsx
const digestResult = await step.digest('digest', async () => {
  return {
    unit: 'days', // 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months'
    amount: 3, // the number of units to digest events for
  };
});
```

## Writing digest content

In many cases, you will need to access all the digested events payload in order to show the user all or parts of the events included in this digest.

**For example:** "John and 5 others liked your photo."

The digest function returns an array of triggers that have been digested.
You can use this array to perform any necessary actions on the digested triggers.
Like Sending and email, or updating a database.

```tsx
const { events } = await step.digest('digest-3-days', async () => {
  return {
    unit: 'days', // 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months'
    amount: 3, // the number of units to digest events for
  };
});

await step.email('send-email', async () => {
  const eventCount = events.length;

  return {
    subject: 'Digest Email',
    body: `You have ${eventCount} new events`,
  };
});
```

## Cron based digest

You can use cron based digest to digest events based on a cron expression.

```tsx
const digestedEvents = await step.digest('cron-digest', async () => {
  return {
    cron: '0 0 * * *', // every day at midnight
  };
});
```

## Custom Digest Key

You can use a custom digest key to digest events based on a custom key. By default, events are digested based on the `subscriberId`. With a custom digest key, events are digested based on the combination of the `subscriberId` and the `digestKey` value.

```tsx
export const customDigestKey = workflow(
  "custom-digest-key",
  async ({ step, payload }) => {
    const { events } = await step.digest("digest-step", async () => {
      return {
        unit: "hours",
        amount: 1,
        digestKey: payload.ticket_id,
      };
    });

    console.log("events ==>", events);

    // use above events to send email / in-app notification
  },
  {
    payloadSchema: z.object({
      ticket_id: z.string(),
    }),
  }
);
```

<Callout type="info">
  Step controls: At the moment, it is not possible to use digest information in step controls. You
  can only use it from the code, by creating a custom component for handling digested data.
</Callout>

The digest step returns an object with events array. Each event in the array has the following properties:

* **id** - The job id of the digested event
* **time** - The time when the event was triggered
* **payload** - The original payload passed to the event

## Two digest steps in a workflow

Currently, Novu does not support two digest steps in a workflow. However, two digest behaviours can be achieved by creating second workflow with digest step, add all other steps after the digest step and trigger the second workflow from the first workflow in [custom step](/framework/custom).

**Use Case: LLM-Powered Feedback Digest**

In this example, customer requests are collected and digested every 15 minutes. An in-app notification alerts the user about the number of new requests. Every 6 hours, those requests are grouped and passed to a second workflow where an LLM (like OpenAI) categorizes the feedback into bugs, feature requests, and praise. A summary email is then sent with the categorized counts. This setup helps reduce noise while still keeping teams informed with meaningful, AI-powered insights.

```typescript
const secondDigestWorkflow = workflow(
  "llm-request-summary-workflow",
  async ({ step, payload }) => {
    const { events } = await step.digest("digest-llm-summary", async () => {
      return {
        unit: "hours",
        amount: 6,
      };
    });

    await step.email("send-llm-summary", async () => {
      const allRequests = events?.map((event) => event.payload.requests);
      // categorized: { bugs: 2, features: 4, praise: 5 }
      const categorized = await categorizeUsingLLM(allRequests);
      const { bugs, features, praise } = categorized;
      return {
        subject: `🧠 LLM Feedback Digest - Last 6 Hours`,
        body: `
          🔧 Bugs reported: ${bugs}\n
          🌟 Feature requests: ${features}\n
          🙌 Praise received: ${praise}\n\n
          View full feedback log in your dashboard.
        `,
      };
    });
  }
);

const firstDigestWorkflow = workflow(
  "customer-requests-digest-workflow",
  async ({ step, subscriber, payload }) => {
    const { events } = await step.digest("digest-recent-requests", async () => {
      return {
        unit: "minutes",
        amount: 15,
      };
    });

    await step.inApp("in-app-summary", async () => {
      return {
        subject: `📝 ${events.length} new requests received`,
        body: `You’ve received ${events.length} customer requests in the last 15 minutes.`,
      };
    });

    await step.custom("trigger-llm-categorize-workflow", async () => {
      return await secondDigestWorkflow.trigger({
        to: subscriber?.subscriberId as string,
        payload: {
          requests: events.map((event) => event.payload),
        },
      });
    });
  }
);
```

<Callout type="info">
  Changing the step content after triggering the workflow with digest step will not affect the
  existing digested events.
</Callout>

## Next Steps

* [Learn more about the Digest Engine](/framework/typescript/steps/digest)

## Frequently Asked Questions

### If digest step fails, will the workflow continue to the next step?

No, workflow execution will stop immediately if the digest step fails due to an error.


# Novu Framework Email Channel (/framework/email-channel)

Learn how to configure the Email channel

The Email Channel is a critical component for delivering notifications reliably. Whether it's a password reset, an onboarding email, or an alert about account activity, email remains a trusted medium for reaching users.
Novu simplifies this process, allowing you to focus on implementation rather than infrastructure.

Learn more about the [Email Channel](/platform/integrations/email).

```tsx
await step.email('email', async () => {
  return {
    subject: 'You received a message',
    body: 'A new post has been created',
  };
});
```


# Bridge Endpoint (/framework/endpoint)

Learn how to configure the Novu Bridge Endpoint, the single HTTP endpoint your application exposes to communicate with the Novu Worker Engine.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Novu Framework requires a **single** `HTTP` endpoint (`/api/novu` or similar) to be exposed by your application. This endpoint is used to receive events from our **Worker Engine**.

You can view the Bridge Endpoint as a webhook endpoint that Novu will call when it needs to retrieve contextual information for a given subscriber and notification.

Using the `npx novu init` command creates a Bridge application for you with a Bridge Endpoint ready to go.

## The `serve` function

We offer framework specific wrappers in form of an exported `serve` function that abstracts away:

* Parsing the incoming request for `GET`, `POST`, `PUT` and `OPTIONS` requests
* HMAC header authentication
* Framework specific response and error handling

Currently, we offer `serve` functions for the following frameworks:

* [Next.js](/framework/quickstart/nextjs)
* [Express.js](/framework/quickstart/express)
* [Nuxt](/framework/quickstart/nuxt)
* [h3](/framework/quickstart/h3)
* [Remix](/framework/quickstart/remix)
* [Sveltekit](/framework/quickstart/svelte)

## Writing a custom `serve` function

If we currently don't support your framework, you can write a custom `serve` function like the following example:

```ts
import { type Request, type Response } from 'express';
import { NovuRequestHandler, ServeHandlerOptions } from '@novu/framework';

export const serve = (options: ServeHandlerOptions) => {
  const requestHandler = new NovuRequestHandler({
    frameworkName: 'express',
    ...options,
    handler: (incomingRequest: Request, response: Response) => ({
      method: () => incomingRequest.method,
      headers: (key) => {
        const header = incomingRequest.headers[key];
        return Array.isArray(header) ? header[0] : header;
      },
      queryString: (key) => {
        const qs = incomingRequest.query[key];
        return Array.isArray(qs) ? qs[0] : qs;
      },
      body: () => incomingRequest.body,
      url: () =>
        new URL(incomingRequest.url, `https://${incomingRequest.headers.get('host') || ''}`),
      transformResponse: ({ body, headers, status }) => {
        Object.entries(headers).forEach(([headerName, headerValue]) => {
          response.setHeader(headerName, headerValue);
        });

        return response.status(status).send(body);
      },
    }),
  });

  return requestHandler.createHandler();
};
```

<Accordions>
  <Accordion title="What is the difference between tunnel url and bridge url?">
    The tunnel url is the url that is generated by the Studio when you run the `npx novu@latest dev` command. It is used to test your notifications by triggering them from the Studio UI. For local development and testing, you can use the tunnel url as bridge url. For production, you should use deployed application url with bridge endpoint as the bridge url.
  </Accordion>

  <Accordion title="Is it necessary to have bridge url publicly accessible?">
    Yes, the bridge url must be publicly accessible. We recommend having https enabled for the bridge url.
  </Accordion>

  <Accordion title="Can endpoint other than /api/novu be used?">
    Yes, you can use any path you want. However, you need to make sure that the endpoint is used in the bridge url. Bridge url is made of the base url and the endpoint path. If your path is /custom-path/novu and deployed application url is [https://my-app.com](https://my-app.com), then the bridge url will be [https://my-app.com/custom-path/novu](https://my-app.com/custom-path/novu).
  </Accordion>
</Accordions>


# Novu Framework In-App Channel (/framework/in-app-channel)

Learn how to configure the In-App channel

Novu extends beyond traditional notification channels like email, SMS, and push by providing a robust framework for in-app notifications. With Novu, you can build reliable, stateful systems that integrate seamlessly into your applications.

Learn more about the [In-App Channel](/platform/inbox).

```tsx
await step.inApp('inbox', async () => {
  return {
    subject: 'Welcome to Acme!',
    body: 'We are excited to have you on board.',
    avatar: 'https://acme.com/avatar.png',
    redirect: {
      url: 'https://acme.com/welcome',
      target: '_blank',
    },
    primaryAction: {
      label: 'Get Started',
      redirect: {
        url: 'https://acme.com/get-started',
        target: '_self',
      },
    },
    secondaryAction: {
      label: 'Learn More',
      redirect: {
        url: 'https://acme.com/learn-more',
        target: '_self',
      },
    },
    data: {
      customData: 'customValue',
      text: payload.text,
    },
  };
});
```


# Novu Framework Overview (/framework)

Learn how to extend Novu's capabilities by building custom notification workflows with code using the Novu Framework.

import { ExpressjsIcon } from '@/components/icons/expressjs';
import { H3Icon } from '@/components/icons/h3';
import { LambdaIcon } from '@/components/icons/lambda';
import { NestjsIcon } from '@/components/icons/nestjs';
import { NextjsIcon } from '@/components/icons/nextjs';
import { NuxtIcon } from '@/components/icons/nuxt';
import { RemixIcon } from '@/components/icons/remix';
import { SvelteIcon } from '@/components/icons/svelte';
import { Card, Cards } from 'fumadocs-ui/components/card';

Novu Framework enables you to run a part of the core Novu workflow engine from within your network boundary. This also opens up a powerful new capability: **you can create Novu workflows entirely in code**. This is important because:

* You can inject custom code that does nearly anything you can imagine as part of a Novu workflow
* Your code-based workflow lives alongside your application code in source control
* You can hydrate notification content using local data-sources, reducing what you need to sync outside of your IT boundary

### What it is and how it works

Novu Framework is an application and SDK that you run locally, and communicates natively with the Novu Cloud Worker Engine via the Novu API.

Novu Framework requires a single HTTP webhook-like endpoint (/api/novu or similar) to be exposed by your application. This endpoint is called a **Bridge Endpoint** and is used to receive events from our Worker Engine through an encrypted client-initiated tunnel.

When enabled, Novu Cloud will call the Bridge Endpoint when it needs to retrieve contextual information for a given subscriber and notification.

Use the `npx novu init` command to create a sample Bridge application with a built-in Bridge Endpoint.

## Quickstart

To get started with Novu Framework, pick your preferred technology from the list below:

<Cards>
  <Card title="Next.js" icon={<NextjsIcon />} href="/framework/quickstart/nextjs" />

  <Card title="Express.js" icon={<ExpressjsIcon />} href="/framework/quickstart/express" />

  <Card title="Remix" icon={<RemixIcon />} href="/framework/quickstart/remix" />

  <Card title="NestJS" icon={<NestjsIcon />} href="/framework/quickstart/nestjs" />

  <Card title="Svelte" icon={<SvelteIcon />} href="/framework/quickstart/svelte" />

  <Card title="Nuxt" icon={<NuxtIcon />} href="/framework/quickstart/nuxt" />

  <Card title="H3" icon={<H3Icon />} href="/framework/quickstart/h3" />

  <Card title="Lambda" icon={<LambdaIcon />} href="/framework/quickstart/lambda" />
</Cards>


# Framework Introduction (/framework/introduction)

Discover how the Novu Framework empowers you to build, customize, and manage advanced notification workflows with a mix of code and no-code capabilities.

The Novu framework allows you to build and manage advanced notification workflows with code, and expose no-code controls for non-technical users to modify.

Workflows are the building blocks of your customer notification experience, they will define the what, when, how and where of your notifications.

## Building blocks

Each Novu workflow is composed of 3 main components:

* **Trigger** - The event that will start the workflow.
* **Channel steps** - The delivery method of the notification with the content.
* **Action steps** - Actions that will happen before and after a given channel step is executed.

Let's take a look at a simple example of a workflow that sends an email after one day:

```tsx
import { workflow } from '@novu/framework';

workflow('sample-workflow', async (step) => {
  await step.delay('delay', async () => {
    return {
      unit: 'days',
      amount: 1,
    };
  });

  await step.email('email-step', async () => {
    return {
      subject: 'Welcome to Novu',
      body: 'Hello, welcome to Novu!',
    };
  });
});
```

### Trigger

The trigger is the event that will start the workflow. In our current example the `sample-workflow` identifier will be used as our trigger id.
Workflow identifiers should be unique to your application and should be descriptive of the workflow's purpose.

### Channel steps

Channel Steps are the delivery methods of the notification. In our example, we have an email Channel Step that will send an email with the subject `Welcome to Novu` and the body `Hello, welcome to Novu!`.
Novu's durable workflow execution engine will select the relevant delivery provider configured for this channel and send the notification with the specified content.

Novu supports a variety of common notification channels out-of-the-box, including **email**, **SMS**, **push**, **inbox**, and **chat**.

To read more about the full list of parameters, check out the [full SDK reference](/framework/typescript/overview).

### Action steps

Action Steps are purpose built functions that help you manage the flow of your workflow. In our example, we have a delay Action Step that will pause the workflow for one day before sending the email.

You can also use Action Steps to perform other tasks such as fetching data from an external API, updating a database, or sending a notification to another channel.

Novu supported the following Action Steps: **delay**, **custom** and **digest**.

## Create a workflow

Here's a bare-bones example of a workflow to send a notification in response to a trigger:

```tsx
import { workflow } from '@novu/framework';

const myWorkflow = workflow(
  'new-signup',
  async ({ step, payload }) => {
    await step.email('send-email', async () => {
      return {
        subject: `Welcome to Acme, ${payload.name}`,
        body: 'We look forward to helping you achieve mission.',
      };
    });
  },
  { payloadSchema: z.object({ name: z.string() }) }
);
```

We'll build on top of this basic code block in the following examples below.

## Just-in-time data fetching

You can add any custom logic needed into your steps. For example, you might want to fetch more information about your new user from a database during the workflow execution. You can achieve this with the following changes:

```tsx
import { workflow } from '@novu/framework';

const myWorkflow = workflow(
  'new-signup',
  async ({ step, payload }) => {
    await step.email('send-email', async () => {
      const user = await db.getUser(payload.userId);
      return {
        subject: `Welcome to Acme ${user.productTier} tier, ${user.name}`,
        body: 'We look forward to helping you achieve mission.',
      };
    });
  },
  { payloadSchema: z.object({ userId: z.string() }) }
);
```

We call this **just-in-time** notification data fetching. It allows you pull in data from the relevant sources during the workflow execution, removing the need to store all of your subscriber data in Novu.

## Multi-step workflow

What if you want to send another update to the same user in one week? But you don't want to send the follow-up if the user opted out. We can add more steps to the workflow to achieve this.

```tsx
import { workflow } from '@novu/framework';

const myWorkflow = workflow(
  'new-signup',
  async ({ step, payload }) => {
    await step.email('send-email', async () => {
      const user = await db.getUser(payload.userId);
      return {
        subject: `Welcome to Acme ${user.productTier} tier, ${user.name}`,
        body: 'We look forward to helping you achieve mission.',
      };
    });

    await step.delay('onboarding-follow-up', async () => ({
      amount: 1,
      unit: 'weeks',
    }));

    await step.inApp(
      'onboarding-follow-up',
      async (controls) => {
        const user = await db.getUser(payload.userId);
        return {
          body: `Hey ${user.name}! How do you like the product? Let us know <a href="${controls.feedbackUrl}">here</a> if you have any questions.`,
        };
      },
      {
        skip: () => !payload.shouldFollowUp,
        controlSchema: {
          type: 'object',
          properties: {
            feedbackUrl: {
              type: 'string',
              format: 'uri',
              default: 'https://acme.com/feedback',
            },
          },
          required: ['feedbackUrl'],
          additionalProperties: false,
        } as const,
      }
    );
  },
  {
    payloadSchema: {
      type: 'object',
      properties: {
        userId: { type: 'string' },
        shouldFollowUp: { type: 'boolean', default: true },
      },
      required: ['userId', 'shouldFollowUp'],
      additionalProperties: false,
    } as const,
  }
);
```

With this simple workflow, we:

* Sent a new signup email
* Waited 1 week
* Sent a follow-up notification in-app

That's the flexibility that Novu Framework offers.

<Callout type="info">
  Read the section on [Controls](/framework/controls) next to learn how to expose Novu's no-code
  editing capabilities to your peers.
</Callout>

## Payload schema

Payload schema defines the payload passed during the `novu.trigger` method. This is useful for ensuring that the payload is correctly formatted and that the data is valid.

```tsx
import { workflow } from '@novu/framework';
import { render } from 'react-email';
import { ReactEmailContent } from './ReactEmailContent';

workflow(
  'comment-on-post',
  async ({ step, payload }) => {
    await step.email('send-email', async () => {
      return {
        subject: `You have a new comment from: ${payload.author_name}`,
        body: render(<ReactEmailContent comment={payload.comment} />),
      };
    });
  },
  {
    payloadSchema: {
      type: 'object',
      properties: {
        post_id: { type: 'number' },
        author_name: { type: 'string' },
        comment: { type: 'string', maxLength: 200 },
      },
      required: ['post_id', 'comment'],
      additionalProperties: false,
    } as const,
  }
);
```

## Tags

Tags are used to categorize the workflows. They also allow you to filter and group notifications for your [Inbox](/platform/inbox/configuration/tabs) tabs.

```tsx
import { workflow } from '@novu/framework';

workflow(
  'acme-login-alert',
  async ({ step, payload }) => {
    await step.inApp('inbox', async () => {
      return {
        subject: 'New Login Detected',
        body: "We noticed a login from a new device or location. If this wasn't you, change your password immediately.",
      };
    });
  },
  {
    tags: ['security'],
  }
);
```


# Workflow Payload (/framework/payload)

Learn how to define and validate workflow payload schemas for data passed during the novu.trigger method.

Workflow payload is the data passed during the `novu.trigger` method. This is useful for ensuring that the payload is correctly formatted and that the data is valid.

## Payload Schema

Payload schema is defining the payload passed during the `novu.trigger` method. This is useful for ensuring that the payload is correctly formatted and that the data is valid.

```tsx
import { render } from '@react-email/components';
import { ReactEmailContent } from './ReactEmailContent';

workflow(
  'comment-on-post',
  async ({ step, payload }) => {
    await step.email('send-email', async () => {
      return {
        subject: `You have a new comment from: ${payload.author_name}.`,
        body: render(<ReactEmailContent comment={payload.comment} />),
      };
    });
  },
  {
    payloadSchema: {
      // Always `object`
      type: 'object',
      // Specify the properties to validate. Supports deep nesting.
      properties: {
        post_id: { type: 'number' },
        author_name: { type: 'string' },
        comment: { type: 'string', maxLength: 200 },
      },
      // Specify the array of which properties are required.
      required: ['post_id', 'comment'],
      // Used to enforce full type strictness, with no rogue properties.
      additionalProperties: false,
      // The `as const` is important to let Typescript know that this
      // type won't change, enabling strong typing on `inputs` via type
      // inference of the provided JSON Schema.
    } as const,
  }
);
```

## Passing Payload

Here is an example of the validated payload during trigger:

```typescript
novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'subscriber_id' },
  payload: {
    post_id: 1234,
    author_name: 'John Doe',
    comment: 'Looks good!',
  },
});
```


# Novu Framework Push Channel (/framework/push-channel)

Learn how to configure the Push channel

Push notifications are a powerful way to deliver real-time updates, reminders, and personalized messages to your users across mobile and web platforms.
Whether it's a promotional alert, a system notification, or a critical update, push notifications are key to enhancing engagement and retention.

Learn more about the [Push Channel](/platform/integrations/push)

```tsx
await step.push('push', async () => {
  return {
    subject: 'You received a message',
    body: 'A new post has been created',
  };
});
```


# Novu Framework Skip Function (/framework/skip)

Skip any step of the workflow based on a condition

The `skip` action is used to skip the next step in the workflow. `skip` function is available for all the steps in the workflow.

## Common usecases

* Skip the step if the user has already seen the notification
* Skip the step if the user has not completed the previous step

## Example

In this example, we will send an in-app notification for task reminder to the user and then send an email reminder 6 hours later if the user has not read the in-app notification.

```tsx
workflow('skip-email-if-in-app-notification-seen', async ({ payload }) => {
  const inAppNotification = await step.inApp(
    'send-in-app-notification',
    async () => {
      return {
        subject: 'Task reminder!',
        body: 'Task is not yet complete. Please complete the task.',
      };
    },
  );

  // delay for 6 hrs
  await step.delay("delay-step-before-email", async () => {
    return {
      unit: 'hours',
      amount: 6,
    };
  });

  // send email notification after 6 hrs if the in-app notification has not been read
  await step.email(
    'send-email',
    () => {
      return {
        subject: `Task reminder!`,
        body: 'Task is not yet complete. Please complete the task.',
      };
    },
    {
      // skip the email step if the in-app notification has been read
      skip: () => inAppNotification.read === true,
    }
  );
});
```


# Framework SMS Channel (/framework/sms-channel)

Learn how to configure the SMS channel

Novu makes SMS notifications simple, scalable, and reliable, enabling seamless integration with your communication stack. Whether you're sending OTPs, updates, or transactional messages, Novu ensures your SMS notifications are delivered efficiently and effectively.

Learn more about the [SMS Channel](/platform/integrations/sms).

```tsx
await step.sms('sms', async () => {
  return {
    body: 'A new post has been created',
  };
});
```


# Local Studio (/framework/studio)

Learn how to use the Local Studio companion app for Novu Framework SDK

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

The Local Studio is a companion app to the Novu Framework SDK. Its goal is to provide a local environment that lives near your code.

To launch the Local Studio locally you can run the following command in your terminal:

<Callout type="warn">
  Local Studio currently works only in the **Chrome** browser
</Callout>

```bash
npx novu@latest dev
```

<Callout type="info">
  Learn how to use the `novu` CLI package and the available [CLI flags](#novu-cli-flags) to use for
  customization
</Callout>

The Dev Studio will be started by default on port 2022, and accessible via: [http://localhost:2022](http://localhost:2022)

After successfully connecting the Studio to your local [Bridge Endpoint](/framework/endpoint), you will be able to preview in real time any workflows and content defined in your code. This is ideal for quick prototyping, debugging, styling, and adjusting your workflows before syncing them to Novu Cloud.

## Control and Payload forms

You can quickly modify the Step Controls and workflow Payload to preview your workflow's different states. This is helpful to quickly debug how the email will behave in case of a missing control, or iterate more complex content structures.

## Syncing State

Syncing state to your Production or Development environment in Novu, is recommended to do via your CI pipeline. However, a sync can be made using the Local Studio for quick experimentation.

Click on the Sync button at the top right corner of the navigation bar. This will open the Sync State modal.

## Tunnel URL

By default the Novu CLI will automatically create a tunnel URL connected to your local computer. This tunnel will proxy any workflow engine requests on our cloud to your local machine.

## Connect Studio to your local server

By default, the Studio will connect to the Novu [Bridge Endpoint](/framework/endpoint) running on your local machine at `http://localhost:4000/api/novu` if your server is running on a different port or the workflows are served from a different endpoint path you can use the following optional parameters to connect:

```bash
npx novu@latest dev --port <YOUR_SERVER_PORT> --route <YOUR_NOVU_ROUTE_PATH>
```

* **YOUR\_SERVER\_PORT** - This accepts the port number where your server is running. Defaults to 4000.
* **YOUR\_NOVU\_ROUTE\_PATH** - This is the mounted path of the framework `serve` function. Defaults to `/api/novu`.

## Novu CLI flags

The Novu CLI command `npx novu@latest dev` supports a number of flags:

| Flag | Long form usage example | Description                 | Default value                                          |
| ---- | ----------------------- | --------------------------- | ------------------------------------------------------ |
| -p   | --port `<port>`         | Bridge application port     | 4000                                                   |
| -r   | --route `<route>`       | Bridge application route    | /api/novu                                              |
| -o   | --origin `<origin>`     | Bridge application origin   | [http://localhost](http://localhost)                   |
| -d   | --dashboard-url `<url>` | Novu Cloud dashboard URL    | [https://dashboard.novu.co](https://dashboard.novu.co) |
| -sp  | --studio-port `<port>`  | Local Studio server port    | 2022                                                   |
| -t   | --tunnel `<url>`        | Self hosted tunnel url      | null                                                   |
| -H   | --headless              | Run bridge in headless mode | false                                                  |

Example: If bridge application is running on port `3002` and Novu account is in `EU` region.

```bash
npx novu@latest dev --port 3002 --dashboard-url https://eu.dashboard.novu.co
```

## FAQ

<Accordions>
  <Accordion title="Running Studio without a tunnel">
    It is possible to run the Studio without generating the default tunnel by passing the `--tunnel` flag with the URL of your application.

    ```bash
    npx novu@latest dev -t http://custom-tunnel-url.ngrok.app
    ```

    <Callout type="warn">
      While the preview will work, you won't be able to test your notifications by the triggering them from the Studio UI.
    </Callout>
  </Accordion>
</Accordions>


# Workflow Tags (/framework/tags)

Learn how to implement and manage notification tags programmatically using the Novu Framework SDK.

**Tags** act like labels or categories that help you organize and manage notifications in your app. By grouping notifications under specific tags, you can better control how they're filtered, displayed, or managed by both your app and your users.

[Learn more about why and how to use tags](/platform/workflow/configure-workflow#tags)

## How to Add Tags to Notifications

Adding tags to a notification is simple and can be done directly in the workflow configuration.
Here's an example:

```tsx
import { workflow } from '@novu/framework';

workflow(
  'acme-login-alert',
  async ({ step, payload }) => {
    await step.inApp('inbox', async () => {
      return {
        subject: 'New Login Detected',
        body: "We noticed a login from a new device or location. If this wasn't you, change your password immediately.",
      };
    });
  },
  {
    tags: ['security'],
  }
);

workflow(
  'acme-password-change',
  async ({ step, payload }) => {
    await step.inApp('inbox', async () => {
      return {
        subject: 'Password Changed',
        body: "Your password was successfully updated. If you didn't request this, contact support right away.",
      };
    });
  },
  {
    tags: ['security'],
  }
);
```

Let's break it down:
In the above workflows, whenever someone logs in from a new device, or changes their password, the notification is tagged as security.

**Benefits:**

* **Filtered Views**: Users can quickly locate security-related notifications in their inbox.
* **Custom Preferences**: Users who only want security alerts can opt in or out of that tag category.


# How Novu Works (/platform/how-novu-works)

A high-level overview of Novu’s architecture: workflows, triggers, subscribers, and environments, and how they connect to support in-app and external channels.

import { Step, Steps } from '@/components/steps';

Novu is a notification infrastructure built around the concept of workflows, environments, and subscriber-based delivery. It centralizes multi-channel messaging and supports real-time in-app experiences through a customizable <Method href="/platform/inbox">{`<Inbox />`}</Method> component.

At its core, Novu uses workflows to orchestrate how notifications are sent, step by step, to different channels like email, SMS, in-app, push, and chat. Each workflow is triggered by your application and executed in the context of a specific environment.

## The Inbox component in the notification lifecycle

The <Method href="/platform/inbox">{`<Inbox />`}</Method> component is Novu’s in-app delivery endpoint. This component makes it possible for users to receive and manage notifications directly within your application interface.

Unlike external channels that rely on third-party providers, the Inbox is internal to your app. It uses the environment’s `application identifier` to establish a secure connection, scoped to your subscribers.

When a workflow includes an in-app step, messages are routed to the subscriber’s inbox in real time. The Inbox component handles rendering, notification management, users' preferences, and message actions without requiring additional backend logic.

## Core concepts overview

At a high level, Novu’s architecture is built around modular but connected concepts. Each concept serves a specific role in the delivery pipeline and is scoped to an environment.

![How Novu works](/images/how-novu-works.png)

### Organization and environments

Everything starts with your organization, the top-level entity in Novu. Each organization can have multiple environments, such as:

* Development for testing
* Production for live apps
* Any custom environments you need (for example, Staging)

Each environment contains:

* Independent workflows
* Environment-specific subscribers
* Topics
* Separate integrations and credentials
* API keys for secure access (application identifier, secret keys)

This isolation allows teams to test workflows and notifications on one environment without affecting the other environments.

### Workflows and Triggers

A workflow defines the steps Novu takes to deliver a notification. Steps are either channel steps (email, in-app, push, chat, and SMS) or action steps (Delay and Digest).

Workflows are environment-specific and versioned. You trigger them using the REST API by sending an event along with the relevant secret key from the current environment, `subscriberId`, `workflowId`, and `payload`.

Each trigger becomes an event that flows through the workflow. Steps in the workflow generate messages, which are delivered via their corresponding channels or routed to the inbox.

To learn more about workflows, refer to the [Workflows documentation](/platform/concepts/workflows).

### Subscribers and topics

A subscriber represents a user in a given environment. Each subscriber has:

* **Channel identifiers**: Such as email address or phone number.
* **A unique `subscriberId`**: Used when triggering workflows and resolving the recipient.
* **Personal details**: You can pass `firstName` and `lastName` when creating the subscriber.
* **Custom metadata**: Stored under a `data` field, which is a flexible JSON object where you can store any additional user-specific information (for example, plan level, preferences, timestamps).
* **Environment-specific preferences**: Like preferred channels and opt-in settings.

To send notifications to multiple users, you can group subscribers into a topic. A workflow can be triggered for an individual subscriber or for all subscribers within a topic.

Subscriber resolution is part of workflow execution. Novu uses the subscriber's metadata to determine how messages are personalized, delivered, and stored.

To learn more about subscribers, refer to the [Subscribers documentation](/platform/concepts/subscribers).

### Channels and the Inbox component

Each channel represents a delivery medium (email, SMS, push, chat, or in-app). Channels are linked to provider configurations known as integrations, which are defined per environment.

In-app messages are delivered to the <Method href="/platform/inbox">{`<Inbox />`}</Method> component, which is located in your frontend and listens for messages scoped to the current environment and subscriber.

To learn more about channels and the Inbox component, refer to the [Channels documentation](/platform/integrations)

### Integrations

Integrations connect Novu to external delivery providers (for example, SendGrid, Twilio, Firebase Cloud Messaging, Slack). They are configured per environment and mapped to specific channels.

During workflow execution, Novu uses these integrations to send messages for steps that require external delivery. The presence of an integration for a given channel is required for a workflow step to succeed.

To learn more about Integrations, refer to the [Integrations documentation](/platform/concepts/integrations).

## How it all connects

See how the concepts work together:

<Steps>
  <Step title="An event triggers the workflow">
    Your application calls Novu’s API and passes in:

    * The secret API key for your environment.
    * The `workflowIdentifier` of the workflow that you want to run.
    * The `subscriberId` of the user that you want to notify (or a topic key for bulk notifications).
    * An optional `payload` to customize message content for example, `{{firstName}}`, `{{orderId}}`
  </Step>

  <Step title="Novu resolves the subscriber">
    Novu looks up the subscriber using the ID you provided. This includes:

    * Channel-specific identifiers (email and phone number).
    * Subscriber preferences, which might affect delivery behavior.
    * Any metadata tied to that subscriber in the current environment
  </Step>

  <Step title="The workflow steps execute sequentially">
    Each step is evaluated in order. These steps include:

    * **Channel steps**: Deliver a message via email, SMS, push, in-app, or chat.
    * **Action steps**: Introduce logic such as delays or digest aggregation.
  </Step>

  <Step>
    If a step fails (for example, due to a provider error), then Novu retries it without re-executing previous steps. This ensures fault tolerance and message-level traceability.
  </Step>

  <Step title="Messages are delivered">
    Once a step completes, Novu uses the environment’s configured integrations to deliver the message. For example:

    * An Email step uses a provider like SendGrid.
    * An In-App step sends the message to the <Method href="/platform/inbox">{`<Inbox />`}</Method> component in your frontend.
    * An SMS step uses a provider like Twilio.
  </Step>

  <Step title="Logs and metadata are recorded">
    Each triggered workflow becomes an event with a unique `transactionId`. Novu records:

    * Which steps ran.
    * Whether each step succeeded or failed.
    * How long each step took.
    * What messages were generated and sent.
  </Step>
</Steps>

The Novu pipeline is designed to be consistent, observable, and scalable across channels and environments.


# Novu Platform Overview (/platform)

Explore the Novu notification infrastructure platform. Learn about workflows, subscribers, integrations, and the Inbox component.

import { OverviewPage } from '@/components/pages/overview-page';

<OverviewPage />


# What is Novu? (/platform/what-is-novu)

The open-source notification infrastructure that simplifies in-app, email, chat, and push notifications.

import { Rocket } from 'lucide-react';
import { ReactIcon } from '@/components/icons/react';
import { NextjsIcon } from '@/components/icons/nextjs';
import { RemixIcon } from '@/components/icons/remix';

Novu is an open-source notification infrastructure built for anyone who needs an easy way to implement, manage, and deliver notifications across multi-channels, including in-app, email, chat, push, and SMS.

Novu is designed to fit and scale with your existing system by providing a unified API, customizable Inbox component that can be integrated with six lines of code, a drag-and-drop workflow builder, and an intuitive dashboard for sending and managing notifications.

Trusted by startups and enterprises alike for its ease of use, developer-first design, and cost-effective scalability, Novu ensures that notifications are delivered reliably to users without complexity.

<Cards>
  <Card icon={<Rocket />} href="/quickstart/nextjs" title="Quickstart">Get started in minutes and focus on building, not maintaining notifications. </Card>
</Cards>

## Why Novu?

Novu is designed to provide a powerful, flexible, and easy-to-use notification solution that helps teams save time, reduce complexity, and improve user engagement across multiple platforms. Here’s what sets it apart from other notification infrastructure solutions:

### The only fully open-source notification infrastructure

* **Backed by a growing open-source community**. Novu is 100% open-source, with a rich community of creative minds constantly contributing to improve its capabilities.
* **Built with an API-first approach**. Developers can deeply customize workflows and automate notifications through Novu APIs.
* **Easily integrates with existing tools**. Novu works with modern development stacks, enabling smooth adoption without disrupting workflows.

### Best-in-class in-app notification inbox

* **Simplifies in-app notifications**. Developers can integrate real-time notifications in any web or mobile app with six lines of code.
* **Offers full customization**. Developers can use hooks and headless libraries to modify the look and feel of the inbox UI.
* **Empowers users with preferences**. The <Method href="/platform/inbox">{`<Inbox />`}</Method> built-in preference management lets your users control how they receive notifications.

### True omnichannel notification management

* **Unifies all notification channels**. Developers can manage email, in-app, push, SMS, and chat notifications from a single API.
* **Optimizes delivery strategies**. Novu enables multi-step workflows, ensuring users receive messages in the most effective channel.
* **Reduces notification overload**. The digest feature consolidates updates (for example, “10 new likes on your post”), improving user experience.

### Flexible workflow automation: no-code or code-first

* **No-code workflow automation**. The drag-and-drop workflow builder makes notification automation accessible to your non-technical teams via the Novu’s dashboard.
* **Provides ultimate control with code-first workflows**. [The Novu Framework SDK](/platform/sdks) lets developers define workflows in code, integrate with CI/CD, and add custom automation logic.
* **Consistent notification experience across teams**. Standardizes notification patterns, preventing each team from implementing separate, inconsistent solutions.

### Advanced features for power users

* **Extends functionality with the Novu Framework SDK**. Developers can integrate custom workflows beyond Novu’s default capabilities.
* **Enhances real-time engagement**. Subscriber presence tracking detects if a user is online before sending notifications.
* **Supports multi-tenancy**. Ideal for SaaS businesses managing multiple customer accounts.

### Cost-effective with clear, transparent pricing

* **Eliminates unpredictable costs**. Fixed pricing ensures startups and enterprises can scale without hidden fees.
* **Offers a free tier for easy adoption**. Independent developers and small businesses can get started at no cost.

## Common Use Cases

Here is how developers, startups and enterprises are currently using Novu in real-world projects:

### Transactional notifications

* Order confirmations and shipping updates for e-commerce.
* Password reset emails and authentication alerts for SaaS platforms.
* Payment failure or subscription renewal reminders.

### In-app notification feeds

* Show unread notifications directly in the app using Novu’s Inbox component.
* Customize the notification UI with hooks and headless components.
* Deliver updates, such as mentions, comments, or system alerts.

### Digest and summary notifications

* “10 people liked your post” (similar to Facebook).
* A weekly report summarizing account activity.
* A daily task reminder for productivity apps.

### Multi-step notification workflows

* Step 1: Send an in-app notification → Step 2: If unread in 24 hours, send an email → Step 3: If still unread, send an SMS reminder.
* Delay and schedule notifications using Novu’s workflow automation.

### Multi-channel notification delivery

* Notify VIP customers via SMS while sending regular users an email.
* Route system alerts to Slack or Microsoft Teams for internal teams.
* Let users opt-in to specific channels (e.g., receive marketing updates via email but urgent alerts via push notifications).

### Customizable notification management

* Let users enable/disable notification channels (email, SMS, push).
* Offer per-event notification settings (e.g., only notify me when tagged in a comment).
* Manage user preferences with Novu’s built-in preference center.

## Next steps

Get started with Novu in minutes! Choose a quickstart guide to integrate notifications into your application:

<Cards>
  <Card icon={<NextjsIcon />} title="Next.js" href="/platform/quickstart/nextjs" description="Get started with our pre-built UI component in Next.js" />

  <Card icon={<ReactIcon />} title="React" href="/platform/quickstart/react" description="Get started with our pre-built UI component in React" />

  <Card icon={<RemixIcon />} title="Remix" href="/platform/quickstart/remix" description="Get started with our pre-built UI component in Remix" />
</Cards>


# Data Migrations (/community/self-hosting-novu/data-migrations)

Learn how to update your database data through migrations.

On occasion, Novu may introduce features that require changes to the database schema or data. This usually happens when
a feature has a hard dependency on some data being available on a database entity. You can use migrations to make these
changes to your database.

## How to Run Novu Migrations (Manual Process)

Novu does **not automatically run database migrations** when deploying new versions. If you're self-hosting or managing
deployments outside a CI/CD pipeline, follow these steps to safely run migrations against your MongoDB database.

For Novu Cloud, the Novu team have a custom deployment service that runs migrations on AWS and is triggered by our team.
By policy any changes are backward compatible and non schema migrations is needed for any deployment. So any migration
can be run after the service was already deployed unless specified otherwise. Those migrations are usually for cleanup
purposes, and schema alignment.

For Novu Self-Hosting, each migration can be run locally against your Mongodb using known connection strings that have
credentials. Your connection may require further access via a tunnel. A script has been added at the bottom that help
manages the complexity of versions across connections strings. Manually add and run `run-migrations.sh` script from
`apps/api` folder.

## Overview

* **Migrations are manual.**
* They must be run from an environment that has **access to the migration scripts**.
* There is no practical way to run those from within the docker container at the moment becuase the migrations scripts
  are not shipped with the images
* Requires **valid MongoDB credentials** and **network access**.
* Typically run **during deployment** of new application versions.
* **Novu does not use a versioning or idempotent migration strategy.**
  See [Versioning Note](#migration-versioning-and-idempotency) below.
* Migrations once added to source code do not change (by policy)
* Refer to the table of releases to know which to run when
* There is a shell script at the end that you can use to ease the burden (
  see [run-migrations.sh](#run-migrations-script))
* Success of this process requires cloning the git repository and setting up the projects from source before starting
  migrations
* Success may also require the Redis instance to be running during execution for some migrations (here's the kicker,
  these are running locally otherwise you would need (potentially) another tunnel through to the remote
  version \[TODO: confirm side effects (April, 2025)])
* **Warning:** some migrations do not exit fully when run in the bash script ( eg \< 0.19.0 ) and require Ctrl-C to finish and continue
* **Warning:** not all migrations are fully documented in the release notes for each release
* **Warning:** migrations are dependent on the underlying code (eg repositories) and matches the version of the code against the migration at the right point in time is crucial and each version also requires the correct version of `node` and `pnpm`

## Migration Release Map

This table maps each migration script to the likely Novu release version, based on the date the script was added and the
closest following release tag.

| **Release Version**                                              | **Release Date** | **Migrations Introduced**                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`v0.17.2`](https://github.com/novuhq/novu/releases/tag/v0.17.2) | 2023-08-13       | `novu-integrations` *(Integration Store)*                                                                                                                                                                                                                                                                                                                                                      |
| [`v0.18.0`](https://github.com/novuhq/novu/releases/tag/v0.18.0) | 2023-08-14       | `changes-migration` *(Change Promotion)* <br /> `encrypt-credentials` *(Secure Credentials)* <br /> `expire-at` *(Database TTL)* <br /> `fcm-credentials` *(Secure Credentials)* <br /> `in-app-integration` *(In-App Integration)* <br /> `normalize-users-email` *(Organization Invite Fix)* <br /> `secure-to-boolean` *(Secure Flag Fix)* <br /> `seen-read-support` *(Seen/Read Support)* |
| [`v0.21.0`](https://github.com/novuhq/novu/releases/tag/v0.19.0) | 2023-09-01       | `integration-scheme-update` *(Multi-Provider)* <br /> `layout-identifier-update` *(Add layout identifier)*                                                                                                                                                                                                                                                                                     |
| [`v0.23.0`](https://github.com/novuhq/novu/releases/tag/v0.23.0) | 2024-02-02       | `encrypt-api-keys` *(API keys encryption)*                                                                                                                                                                                                                                                                                                                                                     |
| [`v0.24.0`](https://github.com/novuhq/novu/releases/tag/v0.24.0) | 2024-03-06       | `normalize-message-template-cta-action` *(Normalize CTA action)* <br /> `topic-subscriber-normalize` *(Normalize topic-subscriber links)*                                                                                                                                                                                                                                                      |
| [`v2.0.0`](https://github.com/novuhq/novu/releases/tag/v2.0.0)   | 2024-10-07       | `subscribers` *(Subscriber record adjustments)*                                                                                                                                                                                                                                                                                                                                                |
| [`v2.0.1`](https://github.com/novuhq/novu/releases/tag/v2.0.1)   | 2024-11-11       | `preference-centralization` *(Preference model centralization)* — **ensure this is done before v2.1 as repository access has been removed**                                                                                                                                                                                                                                                    |
| *(future release)*                                               | *sometime 2025*  | `deleteLogs` *(Cleanup deleted logs)*                                                                                                                                                                                                                                                                                                                                                          |

### Historical releases

| Version                                                      | Feature                 | Migration Path(s)                                                                                                                          |
| ------------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [v0.23](https://github.com/novuhq/novu/releases/tag/v0.23.0) | API keys encryption     | `./encrypt-api-keys/encrypt-api-keys-migration.ts`                                                                                         |
| [v0.18](https://github.com/novuhq/novu/releases/tag/v0.18.0) | Multi-Provider          | `./integration-scheme-update/add-primary-priority-migration.ts`<br />`./integration-scheme-update/add-integration-identifier-migration.ts` |
|                                                              | Integration Store       | `./novu-integrations/novu-integrations.migration.ts`                                                                                       |
| [v0.16](https://github.com/novuhq/novu/releases/tag/v0.16.0) | In-App Integration      | `./in-app-integration/in-app-integration.migration.ts`                                                                                     |
|                                                              | Secure Flag Fix         | `./secure-to-boolean/secure-to-boolean-migration.ts`                                                                                       |
| [v0.15](https://github.com/novuhq/novu/releases/tag/v0.15.0) | Database TTL            | `./expire-at/expire-at.migration.ts`                                                                                                       |
| [v0.12](https://github.com/novuhq/novu/releases/tag/v0.12.0) | Organization Invite Fix | `./normalize-users-email/normalize-users-email.migration.ts`                                                                               |
| [v0.9](https://github.com/novuhq/novu/releases/tag/v0.9.0)   | Seen/Read Support       | `./seen-read-support/seen-read-support.migration.ts`                                                                                       |
| [v0.8](https://github.com/novuhq/novu/releases/tag/v0.8.0)   | Secure Credentials      | `./fcm-credentials/fcm-credentials-migration.ts`<br />`./encrypt-credentials/encrypt-credentials-migration.ts`                             |
| [v0.4](https://github.com/novuhq/novu/releases/tag/v0.4.0)   | Change Promotion        | `./changes-migration.ts`                                                                                                                   |

## Step-by-Step Instructions

### Runtime prerequisites

* `node`
* `npm`
* `pnpm`
* `npx`
* MacOS (or linux)
* tunnel (optional `ssh`)

Some migration scripts (like `in-app-integration`) require access to Redis during execution. If Redis is not running,
you will encounter `ECONNREFUSED 127.0.0.1:6379`. The problem here is that remote environments have their own Redis and
currently the assumption is that migrations should only affect the MongoDB collection. To fix this start Redis locally (
or launch a Docker container: `docker run -p 6379:6379 redis`)

### 1. Clone the Novu Repository

Ensure you’re using the same version as the one you’re deploying:

```bash
git clone https://github.com/novuhq/novu.git
cd novu

git checkout <your-version-tag>  # e.g. v0.24.0
npm run clean
npm run setup:project # really important to run if you change tag
cd apps/api
```

**Warning:** migrations are dependent on the underlying code (eg repositories)

* match the version of the code against the migration at the right point in time
* each version often requires the correct version of `node` and `pnpm` as per the `package.json`

**Notes:**

* Getting the code the run at a checked out version can be tricky
* If you want to know which tags are available: `git tag`
* Some migrations may fail because they rely on the underlying code rather than direct mongo queries
* Migrations are located in: `apps/api/migrations/`
* Checkout by tag stops accidentally running too many migrations that would normally be managed by migrations runner (
  see [migration versioning](#migration-versioning-and-idempotency) )

### 2. Connect to Your MongoDB Database

If your database is not directly accessible, you may need to tunnel:

```bash
# Example: Tunnel MongoDB via SSH
ssh -L 27017:localhost:27017 your-user@your-db-host
```

Have your:

* MongoDB **connection string**
* **Username and password** (if required)

### 3. Run the Migration Script

> use the [script `run-migrations.sh` below](#run-migrations-script) for all the following steps

Configure access to the correct database:

```bash
npx cross-env \
MONGO_URL="mongodb://127.0.0.1:27017/novu-db" \
NEW_RELIC_ENABLED=false \
npm run migration -- ./migrations/normalize-users-email/normalize-users-email.migration.ts
```

Some notes:

* under the hood of the migration script `npx ts-node --transpile-only ./apps/api/migrations/<script-name>.ts`
* some migrations require REDIS (ensure already running)
* some migrations require NEW\_RELIC (so turn off)
* Run each script only once. Monitor logs or database changes for success.

### 5. Repeat for Each Relevant Migration

Use a [migration release map](#migration-release-map) to determine which scripts are required for your upgrade.

## Post-Migration Validation

After completing migrations:

* Verify new fields/collections are present
* Check logs for errors
* Confirm application starts and behaves as expected

## Migration Versioning and Idempotency

Novu **does not implement a versioning system** or record migration history in the database. This means:

* Migrations **must be manually tracked**.
* There is **no built-in idempotency** for running the migration, so running a script twice may cause duplicate data or
  errors (but by policy the underlying code does its best)
* It is your responsibility to **ensure each script runs only once** and in the correct order.

### What Is an Idempotent Migration?

An *idempotent* migration can be safely run multiple times without changing the outcome after the first execution. This
is typically achieved through:

* Tracking applied migrations in a collection (e.g., `migrations`).
* Guard clauses in code to check if a change has already been made.

Note:

* there are libraries that support idempotent Mongo migrations in TypeScript
* if you want to introduce versioned/idempotent migrations in your own deployment process, consider [
  `migrate-mongo`](https://github.com/seppevs/migrate-mongo) or [
  `mongodb-migrations`](https://github.com/emirotin/mongodb-migrations)

## Tips

* Always **back up your database** before running migrations.
* Consider scripting or CI/CD automation for repeatability.
* **Dockerized deployments do not auto-run migrations**—there is no explicit configuration to turn this on either.
* You could implement your own migrations versioning on top

#### Run Migrations Script

Use this shell to ease the burden, ensure that it is executable. Instructions are in the script comments.

```bash
chmod +x run-migrations.sh
```

```bash run-migrations.sh
#!/bin/sh

###############################################################################
# 📦 NOVU MIGRATION RUNNER - POSIX SH EDITION (macOS Compatible)
#
# This script runs one or more database migration scripts for the Novu project.
# It supports:
#   - Selecting a version interactively or via argument
#   - Providing a custom MongoDB connection string
#   - Executing version-specific migration files in order
#   - Compatible with macOS default /bin/sh
#
# ⚠️ WARNING: some migrations do not exit properly ( eg < 0.19.0 ) and require Ctrl-C to finish and continue
#
# 🛠 REQUIREMENTS:
#   - Node.js (with npm and npx)
#   - ts-node and dependencies installed via your project
#
# ▶️ USAGE:
#   ./run-migrations.sh                       # Interactive version selection
#   ./run-migrations.sh v0.24.0               # Run migrations for version
#   ./run-migrations.sh mongodb://...         # Use custom Mongo URL (interactive version)
#   ./run-migrations.sh v0.18.0 mongodb://... # Version + custom Mongo URL
#   ./run-migrations.sh v0.24.0 --dry-run     # Dry run file check only
#
#  Atlas connection strings
#   - remove all & from query params
#      eg mongodb+srv://<USER>:<PASSWORD>@<INSTANCE>.mongodb.net/novu-db
#
# ⚠️ REDIS WARNING:
#   Some migrations require Redis (on 127.0.0.1:6379) to be running.
#   If Redis is not available, you may see ECONNREFUSED errors during execution.
#
#   To fix this:
#     • Start Redis
###############################################################################

set -e

DEFAULT_MONGO_URL="mongodb://127.0.0.1:27017/novu-db"
NEW_RELIC_ENABLED=false

VERSION=""
MONGO_URL=""
DRY_RUN=false

# Argument parsing
for arg in "$@"; do
  case "$arg" in
    v*) VERSION="$arg" ;;
    mongo*) MONGO_URL="$arg" ;;
    --dry-run) DRY_RUN=true ;;
  esac
done

[ -z "$MONGO_URL" ] && MONGO_URL="$DEFAULT_MONGO_URL"

# Define versions and associated keys
# versions must match suffix
VERSIONS="v0.17.2 v0.18.0 v0.21.0 v0.23.0 v0.24.0 v2.0.0 v2.0.1 Future"
MIGRATION_MAP_v0_17_2="novu-integrations"
MIGRATION_MAP_v0_18_0="changes-migration encrypt-credentials expire-at fcm-credentials in-app-integration normalize-users-email secure-to-boolean seen-read-support"
MIGRATION_MAP_v0_21_0="integration-scheme-update layout-identifier-update"
MIGRATION_MAP_v0_23_0="encrypt-api-keys"
MIGRATION_MAP_v0_24_0="normalize-message-template-cta-action topic-subscriber-normalize"
MIGRATION_MAP_v2_0_0="subscribers"
MIGRATION_MAP_v2_0_1="preference-centralization"
MIGRATION_MAP_Future="deleteLogs"

# Migration file paths
get_migration_path() {
  case "$1" in
    fcm-credentials) echo "fcm-credentials/fcm-credentials-migration.ts" ;;
    layout-identifier-update) echo "layout-identifier-update/add-layout-identifier-migration.ts" ;;
    normalize-message-template-cta-action) echo "normalize-message-template-cta-action/normalize-message-cta-action-migration.ts" ;;
    changes-migration) echo "changes-migration.ts" ;;
    seen-read-support) echo "seen-read-support/seen-read-support.migration.ts" ;;
    in-app-integration) echo "in-app-integration/in-app-integration.migration.ts" ;;
    novu-integrations) echo "novu-integrations/novu-integrations.migration.ts" ;;
    expire-at) echo "expire-at/expire-at.migration.ts" ;;
    secure-to-boolean) echo "secure-to-boolean/secure-to-boolean-migration.ts" ;;
    encrypt-api-keys) echo "encrypt-api-keys/encrypt-api-keys-migration.ts" ;;
    encrypt-credentials) echo "encrypt-credentials/encrypt-credentials-migration.ts" ;;
    topic-subscriber-normalize) echo "topic-subscriber-normalize/topic-subscriber-normalize.migration.ts" ;;
    subscriber-preferences-level) echo "subscriber-preferences-level/subscriber-preferences-level.migration.ts" ;;
    integration-scheme-update) echo "integration-scheme-update/add-primary-priority-migration.ts integration-scheme-update/update-primary-for-disabled-novu-integrations.ts integration-scheme-update/add-integration-identifier-migration.ts" ;;
    normalize-users-email) echo "normalize-users-email/normalize-users-email.migration.ts" ;;
    subscribers) echo "subscribers/remove-duplicated-subscribers/remove-duplicated-subscribers.migration.ts" ;;
    preference-centralization) echo "preference-centralization/preference-centralization-migration.ts" ;;
    deleteLogs) echo "deleteLogs/deleteLogsCollection.ts" ;;
    *) echo "" ;;
  esac
}

# Interactive version selector
if [ -z "$VERSION" ]; then
  echo "📦 No version provided. Please choose one:"
  i=1
  for v in $VERSIONS; do
    echo "  $i) $v"
    eval "VERSION_INDEX_$i=$v"
    i=$((i + 1))
  done

  echo
  printf "Enter the number of the version to run migrations for: "
  read choice

  eval "VERSION=\$VERSION_INDEX_$choice"

  if [ -z "$VERSION" ]; then
    echo "❌ Invalid selection."
    exit 1
  fi

  echo "✅ Selected version: $VERSION"
fi

# Normalize version string to match variable names
VERSION_VAR=$(echo "$VERSION" | tr '.' '_' | tr '-' '_')

eval "MIGRATION_KEYS=\$MIGRATION_MAP_$VERSION_VAR"

echo
echo "🌐 Using MongoDB: $MONGO_URL"
echo "🚀 Running migrations for version: $VERSION"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

for key in $MIGRATION_KEYS; do
  paths=$(get_migration_path "$key")
  for path in $paths; do
    fullPath="./migrations/$path"
    if [ "$DRY_RUN" = true ]; then
      if [ -f "$fullPath" ]; then
        echo "✅ File exists: $fullPath"
      else
        echo "❌ File missing: $fullPath"
      fi
    else
      echo "🔁 Running migration: $fullPath"
      npx cross-env MONGO_URL="$MONGO_URL" NEW_RELIC_ENABLED="$NEW_RELIC_ENABLED" npm run migration -- "$fullPath"
    fi
  done
done

if [ "$DRY_RUN" = true ]; then
  echo "✅ Dry-run completed."
else
  echo "✅ All applicable migrations completed."
fi
```

### Reference for Generating Table

The migration-to-release mapping is done by comparing the migration creation date to the next release tag
chronologically.

If multiple migrations appear before a release, they’re grouped under that version.

#### Generating Migrations List

```bash
for file in *; do
  echo "$(git log --diff-filter=A --follow --format=%ad --date=short -- $file | head -1) $file"
done | sort

2023-07-31 novu-integrations
2023-08-01 changes-migration.ts
2023-08-01 encrypt-credentials
...
2024-03-24 subscribers
2024-11-19 preference-centralization
2024-11-29 deleteLogs
```

#### Generating Releases List

```bash
git for-each-ref --sort=creatordate --format '%(creatordate:short) %(refname:short)' refs/tags

2023-08-13 v0.17.2
2023-08-14 v0.18.0
...
2024-02-07 v0.23.1
2024-03-06 v0.24.0
2024-04-05 v0.24.1
2024-10-07 v2.0.0
2024-11-11 v2.0.1
```

#### Listing all migrations

```bash
find . -type f -name "*.ts" ! -name "*.spec.ts"

./fcm-credentials/fcm-credentials-migration.ts
./layout-identifier-update/add-layout-identifier-migration.ts
./normalize-message-template-cta-action/normalize-message-cta-action-migration.ts
./normalize-message-template-cta-action/normalize-message-template-cta-action-migration.ts
./changes-migration.ts
./seen-read-support/seen-read-support.migration.ts
./in-app-integration/in-app-integration.migration.ts
./novu-integrations/novu-integrations.migration.ts
./expire-at/expire-at.migration.ts
./secure-to-boolean/secure-to-boolean-migration.ts
./encrypt-api-keys/encrypt-api-keys-migration.ts
./encrypt-credentials/encrypt-credentials-migration.ts
./topic-subscriber-normalize/topic-subscriber-normalize.migration.ts
./subscriber-preferences-level/subscriber-preferences-level.migration.ts
./integration-scheme-update/add-primary-priority-migration.ts
./integration-scheme-update/update-primary-for-disabled-novu-integrations.ts
./integration-scheme-update/add-integration-identifier-migration.ts
./normalize-users-email/normalize-users-email.migration.ts
```


# Deploy with Docker (/community/self-hosting-novu/deploy-with-docker)

Learn how to deploy Novu with Docker

Docker compose is the easiest way to get started with self-hosted Novu. This guide will walk you through the steps to run all services in single virtual machine using docker compose. This guide uses latest docker images. If you are looking to self host 0.24.x version, checkout [0.24.x docs](https://v0.x-docs.novu.co/self-hosting-novu/deploy-with-docker)

## Prerequisites

You need the following installed in your system:

* [Docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/)
* `curl` and `openssl` (pre-installed on most systems)

## Quick Start

Run the setup script to download the required files, generate secure secrets, and start Novu:

```bash
curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | bash
```

To install into a specific directory, set `NOVU_DIR`:

```bash
curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | NOVU_DIR=~/novu bash
```

The script will:

1. Download `docker-compose.yml` and `.env.example` into the target directory (defaults to `./novu`)
2. Generate cryptographically random values for `JWT_SECRET`, `STORE_ENCRYPTION_KEY`, and `NOVU_SECRET_KEY`
3. Create a `.env` file with the generated secrets
4. Start all Novu services via `docker compose up -d`

Once complete, visit [http://localhost:4000](http://localhost:4000/) to start using Novu.

<Callout type="info">
  If you already have a `.env` file in the target directory, the script will only fill in any missing secret values without overwriting existing configuration.
</Callout>

### Configure Environment

#### VPS Deployment

When deploying to a VPS, update your `.env` file with your server's information:

```bash
# Replace <vps-ip-address> with your VPS IP address
HOST_NAME=http://<vps-ip-address>
```

Start Novu on your VPS:

```bash
docker compose up -d
```

Access your dashboard at [http://vps-ip-address:4000](http://vps-ip-address:4000/).

## Securing Your Setup

If you used the setup script, secure random secrets were generated automatically for `JWT_SECRET`, `STORE_ENCRYPTION_KEY`, and `NOVU_SECRET_KEY`. If you cloned the repository manually, update the `.env` file with your own secrets before going to production.

### Required Variables:

* `JWT_SECRET`: Used by the API to generate JWT keys.
* `STORE_ENCRYPTION_KEY`: Used to encrypt/decrypt the provider credentials. It must be 32 characters long.
* `HOST_NAME`: Host name of your installation:
  * To run in local machine: `http://localhost`
  * To run in VPS: Your server's IP address (e.g., `http://<vps-ip-address>`) or domain name
* `REDIS_CACHE_SERVICE_HOST` and `REDIS_HOST` can have same value for small deployments. For larger deployments, it is recommended to use separate Redis instances for caching and queue management.

## Configuration

To keep the setup simple, we made some choices that may not be optimal for production:

* the database is in the same machine as the servers
* the storage uses localstack instead of S3

We strongly recommend that you decouple your database before deploying.

## Setting Up the Inbox Component

This section explains how to integrate the Novu Inbox component into your application when using a self-hosted Novu deployment.

### Install the required packages

```bash
npm install @novu/react react-router-dom
```

### Create the Inbox component

Create a component file (e.g., `notification-center.tsx`) in your project:

```tsx
import React from 'react';
import { Inbox } from '@novu/react';
import { useNavigate } from 'react-router';
 
export function NotificationCenter() {
  const navigate = useNavigate();
 
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      backendUrl="http://<your-docker-host>:3000" // Docker host address where Novu API is running
      socketUrl="http://<your-docker-host>:3002" // Docker host address where Novu socket is running
      routerPush={(path: string) => navigate(path)}
    />
  );
}
```

### Configure the environment URLs

Adjust the `backendUrl` and `socketUrl` based on your deployment:

### Testing the connection

Once your application is running, you should see the bell icon in your navbar. Clicking it will open the notification inbox UI.

To test notifications, create and trigger a workflow from your self-hosted Novu dashboard, selecting In-App as the channel.

For more information on customizing the Inbox component, refer to the [Inbox documentation](/inbox/overview).

## Initializing the Node SDK

When using a self-hosted Novu deployment with your backend services, you need to configure the Node SDK to connect to your Docker-hosted Novu instance.

### Install the package

```bash
npm install @novu/api
```

### Initialize the SDK

Configure the SDK with your self-hosted backend URL:

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<YOUR_SECRET_KEY_HERE>", // Your Novu API key from the dashboard
  serverURL: "http://<your-docker-host>:3000", // URL of your self-hosted Novu API instance
});
```

### Configure for different environments

Adjust the `backendUrl` based on your deployment:

### Triggering events

Once initialized, you can trigger notification events:

```typescript
await novu.trigger({ 
  workflowId: 'workflowId', 
  to: {
    subscriberId: 'subscriberId',
  },
  payload: {
    // Your custom payload data
    name: 'John Doe',
    orderId: 'ORDER_ID_123',
  },
});
```

For more information on using the Node SDK, refer to the [Server-Side SDKs documentation](/sdks/overview).

### Setting Up local studio and bridge application

#### Setting Up the bridge application

The bridge application is application where workflow definition are written using `@novu/framework`. Here's how to set it up:

```bash
# Initialize the bridge application
npx novu@latest init \
  --secret-key=<secret_key> \
  --api-url=http://localhost:3000

# Install dependencies
npm install

# Start the bridge application
npm run dev
```

Nextjs based bridge application having one test workflow written using `@novu/framework` will be running on `http://localhost:4000`, Go to [http://localhost:4000/api/novu](http://localhost:4000/api/novu) to see status.

#### Setting Up Novu Studio

[Novu Local Studio](/framework/studio) is a development environment that allows you to test and manage your workflows. The setup varies based on your deployment:

1. Running in local machine

if novu is run using above docker compose command in local machine, use below commmand

```bash
npx novu@latest dev -d http://localhost:4000 -p <bridge_application_port>
```

Following actions will occur:

* Novu local studio will be started on default port 2002,
* Novu will generate a tunnel url that will forward the request to bridge application running on `<bridge_application_port>`
* Studio will use `http://localhost:4000` as dashboard url

**Using bridge application url as bridge url**

To use bridge application url as bridge url, use below command:

```bash
npx novu@latest dev -d http://localhost:4000 -p <bridge_application_port> -t http://host.docker.internal:<bridge_application_port>

# example:
npx novu@latest dev -d http://localhost:4000 -p 4000 -t http://host.docker.internal:4000
```

<Callout type="info">
  In Windows OS, there are some additional steps:

  * stop the running docker compose process using `ctrl + c`
  * update the `docker-compose.yml` file and add below config with each service (api, dashboard, worker and ws)

  ```bash
  extra_hosts:
      - "host.docker.internal:host-gateway"
  ```

  * start the docker compose process again using `docker compose up`
  * now you can use `host.docker.internal` as bridge url hostname inplace of `localhost`
</Callout>

2. Running in VPS

```bash
# update the bridge .env file with below variables
NOVU_API_URL=http://<vps-ip-address>:3000

# Start Novu Studio with your VPS dashboard URL and bridge application URL
npx novu@latest dev -d http://<vps-ip-address>:4000
```

Check all [available flags](/framework/studio#novu-cli-flags) with `npx novu dev` command

### Synchronizing Workflows

1. For local deployment:

```bash
npx novu@latest sync \
  --bridge-url <tunnel-url>/api/novu \
  --api-url http://localhost:3000 \
  --secret-key <secret_key>
```

2. For VPS deployment:

```bash
npx novu@latest sync \
  --bridge-url <tunnel_url>/api/novu \
  --api-url http://<vps-ip-address>:3000 \
  --secret-key <secret_key>
```

### VPS Security Considerations

When deploying to a VPS, consider these additional security measures:

1. Use a firewall to restrict access to only necessary ports
2. Set up SSL/TLS certificates for HTTPS access
3. Regularly update your Docker images and host system
4. Use strong, unique secrets in your `.env` file
5. Consider using a reverse proxy like Nginx for additional security layers

### Triggering events with custom installation

When self-hosting Novu, in order to trigger an event you must first create a new `Novu` object and configure it with the proper `backendUrl`.

```tsx
import { Novu } from '@novu/api';  

const novu = new Novu({
  secretKey: '<YOUR_SECRET_KEY_HERE>',
  serverURL: '<REPLACE_WITH_SELF_HOSTED_BACKEND_URL>',
});

await novu.trigger({
  workflowId: 'workflowId',
  to: {
    subscriberId: 'subscriberId',
  },
  payload: {},
});
```

### Caching

We are introducing the first stage of caching in our system to improve performance and efficiency. Caching is turned off by default, but can easily be activated by setting the following environment variables:

* REDIS\_CACHE\_SERVICE\_HOST
* REDIS\_CACHE\_SERVICE\_PORT

Currently, we are caching data in the most heavily loaded areas of the system: the widget requests such as feed and unseen count, as well as common DAL requests during the execution of trigger event flow. These are the most heavily used areas of our system, and we hope that by implementing caching in these areas, we can improve performance in the near future.

### Reverse-Proxy / Load Balancers

To implement a reverse-proxy or load balancer in front of Novu, you need to set the GLOBAL\_CONTEXT\_PATH for the base path of the application. This is the path that the application will be served from after the domain. For example: - company.com/novu This is used to set the base path for the application, and is used to set the base path for the API, Dashboard, and WebSocket connections.

The following environment variables are used to set the context path for each public service that Novu provides: API\_CONTEXT\_PATH WIDGET\_CONTEXT\_PATH WS\_CONTEXT\_PATH DASHBOARD\_CONTEXT\_PATH

These allow you to set the context path for each service independently or dependently of the GLOBAL\_CONTEXT\_PATH.

For example, if I was using a reverse proxy to serve Novu from company.com/novu, I would set the GLOBAL\_CONTEXT\_PATH to novu, and then set the API\_CONTEXT\_PATH to api, the WIDGET\_CONTEXT\_PATH to widget, the WS\_CONTEXT\_PATH to ws, and the DASHBOARD\_CONTEXT\_PATH to Dashboard.

This would produce the following urls: - API: company.com/novu/api - WIDGET: company.com/novu/widget - WS: company.com/novu/ws - DASHBOARD: company.com/novu/dashboard

However the Service context path can be used entirely independently of the GLOBAL\_CONTEXT\_PATH.

For example, if I wanted to expose the api as novu-api, I would set the API\_CONTEXT\_PATH to novu-api without setting the GLOBAL\_CONTEXT\_PATH. This would producte the following url: - API: company.com/novu-api

<Callout type="info">
  These env variables should be present on all services novu provides due to tight coupling.
</Callout>

## FAQs

### Local Tunnel and Self-Hosted Deployments

Novu uses a local tunnel as bridge url. It can be used as bridge url with local studio and for testing purpose in development environment. It should not be used in production environment. It is recommended to use deployed application url as bridge url

#### When is Local Tunnel Not Required?

If the customer's application and the self-hosted Novu deployment are within the same network, there is no need for a local tunnel. In this case, the application can communicate directly with Novu through the internal network. Checkout `Using bridge application url as bridge url` section to learn more.

#### When is Local Tunnel Required?

If the application and Novu deployment reside on different networks, you can still interact with your self-hosted Novu instance using the Novu CLI. The CLI allows you to specify the Dashboard URL and Bridge Endpoint Origin to enable communication across networks via the Novu Cloud Local Tunnel.

For example, you can use the following command:

```bash
npx novu@latest dev -d http://my-self-hosted-novu-domain.com:my-port
```


# Self-Hosting Novu Overview (/community/self-hosting-novu/overview)

Self-host Novu for full control over your notification infrastructure. Covers system requirements, VMs, Redis, MongoDB, and storage.

When self-hosting Novu, you take full control over your communication infrastructure by deploying it on your own servers. While this setup allows for customization and greater flexibility, it is important to note that some features exclusive to Novu's cloud-managed solution will not be available in a self-hosted environment.

<Callout type="warn">
  Self-hosting Novu does not support social login (GitHub, Google, etc.). To access your account,
  please use the email and password associated with your Novu account.
</Callout>

## System requirements overview

### Multi-VM deployment (recommended)

For optimal performance, host Novu's core services across multiple virtual machines.

| Component                       | Instances                                    | Specs                         |
| ------------------------------- | -------------------------------------------- | ----------------------------- |
| Novu services (API, Worker, WS) | 3 VMs per service                            | 2 vCPUs, 4 GB RAM each        |
| Dashboard                       | 1 VM                                         | 2 vCPUs, 4 GB RAM             |
| Redis                           | 2 clusters (one for queues with AOF enabled) | 8 GB RAM per cluster          |
| MongoDB                         | 1 cluster                                    | M20 or higher (MongoDB Atlas) |
| S3 storage                      | —                                            | 10 GB minimum                 |

### Single-VM deployment

If resources are limited or simplicity is a priority, all services can run on a single VM.

| Component                                      | Specs                 |
| ---------------------------------------------- | --------------------- |
| All Novu services (API, Worker, WS, Dashboard) | 4 vCPUs, 8 GB RAM     |
| MongoDB                                        | 2 GB RAM, 20 GB disk  |
| Redis                                          | 2 GB RAM, AOF enabled |
| S3 storage                                     | 10 GB minimum         |

### Infrastructure details

#### Redis

| Setting     | Value                                                                                  |
| ----------- | -------------------------------------------------------------------------------------- |
| Clusters    | 2 (one dedicated to queues)                                                            |
| Memory      | 8 GB RAM per cluster                                                                   |
| Persistence | Append Only File (AOF) enabled on the queue cluster to prevent job loss during outages |

#### MongoDB

| Setting      | Value                          |
| ------------ | ------------------------------ |
| Cluster tier | M20 or higher on MongoDB Atlas |

#### Storage

| Setting    | Value         |
| ---------- | ------------- |
| S3 storage | 10 GB minimum |

<Callout type="info">
  The above specifications are general recommendations. Adjust them based on your system load, usage
  patterns, and scale of operations.
</Callout>


# Self-Hosting Telemetry (/community/self-hosting-novu/telemetry)

Learn about Novu's telemetry data collection and how to configure it

Telemetry in Novu encompasses the collection of data regarding user interactions with the platform. This data enables the Novu team to identify usage patterns, troubleshoot issues, and make informed decisions about new features and improvements.

## Data collected by Novu

Novu does not capture any data from your APIs, databases, or third-party tools. All information collected from self-hosted instances is completely anonymized to protect user privacy.

### Keep Alive Beacon

The Novu server sends a keep-alive ping every hour to confirm its operational status without errors. This data is collected regardless of whether telemetry is enabled or disabled.

```json
{
  "freeMemory": 115703808,
  "hostname": "somemachine",
  "instanceId": "ba54fb29-6422-4a83-a0e4-951d767efa73",
  "ipAddress": "192.168.1.4",
  "platform": "darwin",
  "release": "23.6.0",
  "timestamp": "2024-10-04T11:54:14",
  "totalMemory": 8589934592
}
```

### Usage Statistics

When telemetry is enabled, the server collects anonymous information regarding users, organizations, events, notifications, and more. This data provides insights into platform usage and helps us improve the Novu Project for all users.

```json
{
  "eventCount": 1,
  "integrationCount": [
    {
      "count": 1,
      "providerId": "example"
    },
    {
      "count": 1,
      "providerId": "novu"
    }
  ],
  "orgCount": 1,
  "subscriberCount": 1,
  "timestamp": "2024-10-04T11:54:30",
  "topicCount": 3,
  "totalSteps": 10,
  "userCount": 3,
  "workflowCount": 6
}
```

## Disable telemetry

Sharing telemetry data is optional. You can disable telemetry via the Admin Settings or by modifying the relevant environment variable.

### Environment variable

To disable telemetry using the `NOVU_TELEMETRY` environment variable, follow these steps:

1. Go to the directory where the .env file is located.
2. Open the file in an editor and search for `NOVU_TELEMETRY`.
3. Change the value of `NOVU_TELEMETRY` to `false`.
4. Restart the Docker container.

Once the container restarts, Novu will be running with telemetry disabled.


# Migrate from v0 Web UI to v2 Dashboard (/community/self-hosting-novu/v0-to-v2-migration)

A guide to help you migrate from Novu self-hosted v0 to v2

## Migrating from Novu Self-Hosted v0 to v2

This guide will help you migrate your existing Novu self-hosted v0 instance to v2. Due to significant architectural changes between versions, some manual steps are required, particularly for workflow migration.

## Terminology

* Web UI: The old Novu UI, that you are currently using.
* Dashboard: The new Novu UI, that is powered by the v2 APIs and architecture.

## Prerequisites

* Access to your existing v0 instance
* New v2 instance ready for deployment
* Temporary ability to run both instances simultaneously for migration purposes

## Main Changes in v2 Dashboard

The new Dashboard brings a cleaner, and more intuitive UI. We have reconsidered some core principles, let's review the most important ones:

### Subscribers

The Subscribers page has been redesigned to provide a more comprehensive view of your subscribers, including preferences management and credentials.

### Topics

Brand new topics page, to view and manage your topics in Novu.

### Workflows

This area of the product was completely redesigned, and old v0 workflows will not be visible in the new UI.
The new Editor includes a block based editor for E-mail, with the ability to provide custom HTML blocks if needed.

### Layouts

Layout management is available on the new Dashboard. Checkout the [layouts](/platform/workflow/add-notification-content/channels-template-editors#email-layouts) documentation for more details.

### Variants (Deprecated)

Workflow Variants will not be available in the v2 UI, if you rely on them, you can continue to use the old UI for those workflows.

### Changes (Deprecated)

The changes mechanism was removed, in favor of a more simple "Sync" mechanism, that enables you to sync workflow state between environments, Production environment can also be modified directly from the UI, however we still recommend using the Dev environment and syncing the changes to Production.

### User management (Not available)

You can still login to your old Novu Users and their passwords with the new Dashboard,
However we are not allowing team management flows with the new version.

In v2 we have moved our internal cloud implementation to use Clerk as our authentication and authorization provider, and we are not able to maintain 2 separate user management systems.
We recommend creating a reusable user credentials and share them between your team.

## API Changes in v2

The v2 API introduces several new endpoints and improvements. Here are the key changes:

### New v2 Routes

1. **Subscribers** (`/v2/subscribers`)
   * Enhanced subscriber management with new endpoints:
     * `GET /` - Search subscribers with advanced filtering
     * `GET /:subscriberId` - Retrieve specific subscriber
     * `POST /` - Create new subscriber
     * `PATCH /:subscriberId` - Update subscriber details
     * `DELETE /:subscriberId` - Remove subscriber
   * New preferences management:
     * `GET /:subscriberId/preferences` - Get subscriber preferences
     * `PATCH /:subscriberId/preferences` - Update preferences
2. **Topics** (`/v2/topics`)
3. **Workflows** (`/v2/workflows`)

## Migrating Workflows

Unfortunately, we do not have an automated way to migrate v0 workflows created in the v0 UI.
To migrate workflows, you will need to manually recreate them in the new Dashboard UI.

The old Web UI dashboard is compatible with the new v2 API, so you don't have to worry about updating your API instance, as it will continue to work as expected.

While running the old "Web UI", deploy the new "Dashboard" docker image under another host (we use dashboard.novu.co and dashboard-v0.novu.co for this example).
During the transition period, you will have the two dashboards running in the same time, so you can copy the workflows from the old UI to the new one.

Workflows created in the new UI will not be visible under the old Web UI, but old workflows create will appear in the new UI however, will not be editable from there.

1. **Access both dashboards**: Open the admin dashboards for both versions
2. **Copy workflow configurations**: For each workflow in v0:
   * Note all steps, templates, and trigger configurations
   * Manually recreate them in v2 with the same structure
   * Verify variables, conditions, and integrations are properly configured

## FAQs

### If I currently use the v2 docker images, what should I do?

If you already have the v2 docker images running, you will just need to run the new dashboard image in parallel to the existing "web" image, and migrate your workflows.

### What breaking changes are in the new v2 images (API)

The new v2 images are backward compatible with the old v0 API, so you don't have to worry about updating your instances.
However, to enjoy the new Workflow editor experience, you will need to migrate your workflows to the new v2 engine.

### What is the difference between Novu Cloud, Enterprise and Self-hosted?

You can learn more about the differences between the different editions [here](https://docs.novu.co/community/self-hosted-and-novu-cloud).

## Need Help?

If you encounter challenges during migration, our community is here to help:

* Join our [Discord community](https://discord.gg/novu)
* Open issues on [GitHub](https://github.com/novuhq/novu)
* Check the [documentation](https://docs.novu.co) for the latest updates


# Using Translations with @novu/framework (/guides/framework/using-translations)

Learn how to use translations with @novu/framework based workflows

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Novu Framework workflows are code-first: workflow definitions and content are expressed in code rather than in the dashboard. Internationalization (i18n) is implemented in the application layer—translations are defined there and resolved at runtime—so that workflow step content (e.g. subject and body fields) can be locale-aware.

This guide implements a locale-aware email notification workflow using **i18next** for translation resolution and **React Email** for the message template, with a Twitch welcome email as the reference implementation.

<Steps>
  <Step title="Create translation keys in the code">
    Import the `createInstance` and `InitOptions` from the `i18next` library and add translation keys for all supported locales.

    ```ts title="translations.ts"
    import { createInstance, InitOptions } from "i18next";

    const i18nOptions: InitOptions = {
      resources: {
        en_US: {
          translation: {
            welcomeEmailSubject: "Welcome to Twitch, {{username}}!",
            welcomeEmailIntroduction:
              "We’re glad you could join us. Twitch has a huge, passionate community ready to watch and celebrate all the things you’re into, and we’ve saved a seat just for you.",
            linkText: "WATCH NOW",
            welcomeEmailConclusion:
              "If you want to watch it, someone on Twitch streams it: games, anime, fitness, cosplay, esports, cooking, music, meditation. Take a look around, find a few channels to call home, and cozy up in chat.",
          },
        },
        de_DE: {
          translation: {
            welcomeEmailSubject: "Willkommen bei Twitch, {{username}}!",
            welcomeEmailIntroduction:
              "Wir freuen uns, dass Sie sich uns anschließen konnten. Twitch hat eine riesige, leidenschaftliche Community, die bereit ist, alles zu sehen und zu feiern, was Sie interessiert, und wir haben einen Platz nur für Sie reserviert.",
            linkText: "JETZT ANSEHEN",
            welcomeEmailConclusion:
              "If you want to watch it, someone on Twitch streams it: games, anime, fitness, cosplay, esports, cooking, music, meditation. Take a look around, find a few channels to call home, and cozy up in chat.",
          },
        },
      },
    };

    const i18n = createInstance(i18nOptions);
    i18n.init(i18nOptions);

    export default i18n;
    ```
  </Step>

  <Step title="Create email template">
    * Create a new file called `react-email-template.tsx` and add the following code using components from the `@react-email/components` library.
    * Add the `renderEmail` function to render the email template.

    <Callout type="info">
      Here, we are using [@react-email/components](https://react.email/components) to build the email template. You can use any other library or bare HTML to build the email template.
    </Callout>

    <Accordions>
      <Accordion title="Email template">
        ```tsx title="react-email-template.tsx"
        import {
          Body,
          Container,
          Head,
          Html,
          Preview,
          Section,
          Text,
          Link,
          Img,
          Row,
          Column,
          render,
        } from '@react-email/components';
        import * as React from 'react';

        const baseUrl = process.env.IMAGE_BASE_URL;

        export const TwitchWelcomeEmail = ({
          subject,
          body,
          linkText,
          body2,
        }: {
          subject: string;
          body: string;
          linkText: string;
          body2: string;
        }) => {
          return (
            <Html>
              <Head />
              <Preview>{subject}</Preview>
              <Body style={main}>
                <Container style={container}>
                  <Section style={logo}>
                    <Img width={114} src={`${baseUrl}/twitch-logo.png`} />
                  </Section>
                  <Section style={sectionsBorders}>
                    <Row>
                      <Column style={sectionBorder} />
                      <Column style={sectionCenter} />
                      <Column style={sectionBorder} />
                    </Row>
                  </Section>
                  <Section style={content}>
                    <Text style={paragraph}>{body}</Text>
                    <Section style={center}>
                      <Link href='https://www.twitch.tv' style={link}>
                        {linkText}
                      </Link>
                    </Section>
                    <Text style={paragraph}>{body2}</Text>
                  </Section>
                </Container>
                <Section style={footer}>
                  <Row>
                    <Column align='right' style={{ width: '50%', paddingRight: '8px' }}>
                      <Img src={`${baseUrl}/twitch-icon-twitter.png`} />
                    </Column>
                    <Column align='left' style={{ width: '50%', paddingLeft: '8px' }}>
                      <Img src={`${baseUrl}/twitch-icon-facebook.png`} />
                    </Column>
                  </Row>
                  <Row>
                    <Text style={{ textAlign: 'center', color: '#706a7b' }}>
                      © {new Date().getFullYear()} Twitch, All Rights Reserved <br />
                      350 Bush Street, 2nd Floor, San Francisco, CA, 94104 - USA
                    </Text>
                  </Row>
                </Section>
              </Body>
            </Html>
          );
        };

        const fontFamily = 'HelveticaNeue,Helvetica,Arial,sans-serif';

        const main = {
          backgroundColor: '#efeef1',
          fontFamily,
        };

        const paragraph = {
          lineHeight: 1.5,
          fontSize: 14,
        };

        const container = {
          maxWidth: '580px',
          margin: '30px auto',
          backgroundColor: '#ffffff',
        };

        const footer = {
          maxWidth: '580px',
          margin: '0 auto',
        };

        const content = {
          padding: '5px 20px 10px 20px',
        };

        const logo = {
          display: 'flex',
          justifyContent: 'center',
          alingItems: 'center',
          padding: 30,
        };

        const sectionsBorders = {
          width: '100%',
          display: 'flex',
        };

        const sectionBorder = {
          borderBottom: '1px solid rgb(238,238,238)',
          width: '249px',
        };

        const sectionCenter = {
          borderBottom: '1px solid rgb(145,71,255)',
          width: '102px',
        };

        const center = {
          display: 'flex',
          justifyContent: 'center',
          alingItems: 'center',
        };

        const link: React.CSSProperties = {
          margin: 0,
          border: '0 solid #9147ff',
          borderRadius: '3px',
          color: '#fff',
          background: '#9147ff',
          display: 'inline-block',
          fontFamily: 'Helvetica,Arial,sans-serif',
          fontSize: '18px',
          fontWeight: 'regular',
          lineHeight: 1.3,
          padding: '10px 30px 10px 30px',
          textAlign: 'left',
          textDecoration: 'none',
        };

        export function renderEmail(
          subject: string,
          body: string,
          linkText: string,
          body2: string
        ) {
          return render(
            <TwitchWelcomeEmail
              subject={subject}
              body={body}
              linkText={linkText}
              body2={body2}
            />
          );
        }
        ```
      </Accordion>
    </Accordions>
  </Step>

  <Step title="Create the workflow and use translations">
    * Create the workflow definition by importing the `workflow` function from the `@novu/framework` library.
    * Import the `renderEmail` function from the `react-email-template.tsx` file. This is the email template that will be used to send the notification.
    * Import the `i18n` from the `translations.ts` file.
    * Import the `zod` library to validate the workflow payload.

    ```ts title="workflow-with-translations.ts"
    import { workflow } from "@novu/framework";
    import { renderEmail } from "./react-email-template";
    import i18n from "./translations";
    import { z } from "zod";

    export const workflowWithTranslations = workflow(
      "workflow-with-translations",
      async ({ step, subscriber }) => {
        await step.email(
          "email-step",
          async (controls) => {
            const translate = i18n.getFixedT([
              subscriber?.locale || (controls.defaultLocale as string),
            ]);

            const subject = translate("welcomeEmailSubject", {
              username: subscriber?.firstName || "Novu",
            });
            const welcomeEmailIntroduction = translate("welcomeEmailIntroduction");
            const linkText = translate("linkText");
            const welcomeEmailConclusion = translate("welcomeEmailConclusion");
            return {
              subject,
              body: (await renderEmail(
                subject,
                welcomeEmailIntroduction,
                linkText,
                welcomeEmailConclusion
              )) as string,
            };
          },
          {
            controlSchema: z.object({
              defaultLocale: z.string().default("en").optional(),
            }),
          }
        );
      }
    );
    ```
  </Step>

  <Step title="Add workflow to serve function">
    ```ts title="api/novu/route.ts"
    import { serve } from '@novu/framework/next';
    import { workflowWithTranslations } from '../../workflow-with-translations';

    export const { GET, POST, OPTIONS } = serve({
      workflows: [workflowWithTranslations],
    });
    ```
  </Step>

  <Step title="Sync and test the workflow">
    * [Sync the workflow](/framework/deployment/syncing) to the Novu cloud.
    * Test the workflow by triggering it to subscribers with different locales.
  </Step>
</Steps>


# Novu and Clerk integration guide (/guides/webhooks/clerk)

This guide walks you through integrating Clerk webhooks with Novu notifications in a Next.js application.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { NextjsIcon } from '@/components/icons/nextjs';
import { ExpressjsIcon } from '@/components/icons/expressjs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { File, Folder, Files } from 'fumadocs-ui/components/files';

You'll learn how to automatically trigger notification workflows when **any Clerk event** occurs, such as **user creation, email events, or password changes**.

## Overview

When specific events happen in Clerk (e.g., user signup, password changes, email verification), this integration will:

1. Receive the webhook event from Clerk.
2. Verify the webhook signature.
3. Process the event data.
4. Trigger the corresponding **Novu notification workflow**.

<Callout>
  You can also clone this repository: [https://github.com/novuhq/clerk-to-novu-webhooks](https://github.com/novuhq/clerk-to-novu-webhooks)
</Callout>

## Prerequisites

Before proceeding, ensure you have:

* A **Clerk + Next.js app** ([Set up Clerk](https://clerk.com/docs/quickstarts/nextjs)).
* A **Novu account** ([Sign up here](https://novu.com/signup)).

<Steps>
  <Step>
    ## Install Dependencies

    Run the following command to install the required packages:

    ```
    npm install svix @novu/api @clerk/nextjs
    ```
  </Step>

  <Step>
    ## Configure Environment Variables

    Add the following variables to your `.env.local` file:

    ```
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
    CLERK_SECRET_KEY=sk_test_...
    CLERK_SIGNING_SECRET=whsec_...
    NOVU_SECRET_KEY=novu_secret_...
    ```
  </Step>

  <Step>
    ## Expose Your Local Server

    To test webhooks locally, you need to expose your **local server** to the internet.

    There are two common options:

    <Tabs items={['localtunnel', 'ngrok']}>
      <Tab value="localtunnel">
        ### localtunnel

        **localtunnel** is a simple and free way to expose your local server without requiring an account.

        1. Start a localtunnel listener

           ```bash
           npx localtunnel 3000
           ```

        2. Copy and save the generated **public URL** (e.g., `https://your-localtunnel-url.loca.lt`).

        Learn more about **localtunnel** [here](https://www.npmjs.com/package/localtunnel).

        <Callout>
          **localtunnel** links may expire quickly and sometimes face reliability issues.
        </Callout>
      </Tab>

      <Tab value="ngrok">
        ### ngrok

        For a more stable and configurable tunnel, use **ngrok**:

        1. Create an account at [ngrok dashboard](https://dashboard.ngrok.com/).

        2. Follow the [setup guide](https://dashboard.ngrok.com/get-started/setup).

        3. Run the command:

           ```bash
           ngrok http 3000
           ```

        4. Copy and save the **Forwarding URL** (e.g., `https://your-ngrok-url.ngrok.io`).

        Learn more about **ngrok** [here](https://dashboard.ngrok.com/get-started/setup).
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Set Up Clerk Webhook Endpoint

    1. Go to the **Clerk Webhooks** page ([link](https://dashboard.clerk.com/last-active?path=webhooks)).

    2. Click **Add Endpoint**.

    3. Set the **Endpoint URL** as:

       ```
          https://your-forwarding-URL/api/webhooks/clerk
       ```

    4. Subscribe to the **relevant Clerk events** (e.g., `user.created`, `email.created` etc.).

    <Callout>
      You can find the list of all supported Clerk events [here](https://clerk.com/docs/reference/webhooks/events), or proceed to the section which going over [Identify the Triggering Event(s).](#identify-the-triggering-events)
    </Callout>

    5. Click **Create** and keep the settings page open.
  </Step>

  <Step>
    ## Add Signing Secret to Environment Variables

    1. Copy the **Signing Secret** from Clerk's **Webhook Endpoint Settings**.
    2. Add it to your `.env.local` file:

    ```
    CLERK_SIGNING_SECRET=your_signing_secret_here
    ```
  </Step>

  <Step>
    ## Make Webhook Route Public

    Ensure the webhook route is public by updating `middleware.ts` :

    ```jsx
    import { clerkMiddleware } from '@clerk/nextjs/server';

    export default clerkMiddleware({
      publicRoutes: ['/api/webhooks'],
    });
    ```
  </Step>

  <Step>
    ## Create Webhook Endpoint for Clerk in Next.js

    Create `app/api/webhooks/clerk/route.ts`:

    <Files>
      <Folder name="app" defaultOpen>
        <Folder name="api" defaultOpen>
          <Folder name="webhooks" defaultOpen>
            <Folder name="clerk" defaultOpen>
              <File name="route.ts" />
            </Folder>
          </Folder>
        </Folder>
      </Folder>
    </Files>

    The following snippet is the complete code of how to create a webhook endpoint for Clerk in Next.js:

    ```jsx
    import { Webhook } from 'svix'
    import { headers } from 'next/headers'
    import { WebhookEvent, UserJSON } from '@clerk/nextjs/server'
    import { triggerWorkflow } from '@/app/utils/novu'

    // Single source of truth for all supported Clerk events and their corresponding Novu workflows
    const EVENT_TO_WORKFLOW_MAPPINGS = {
        // Session events
        'session.created': 'recent-login-v2',
        
        // User events
        'user.created': 'user-created',
        
        // Email events
        'email.created': {
            'magic_link_sign_in': 'auth-magic-link-login',
            'magic_link_sign_up': 'auth-magic-link-registration',
            'magic_link_user_profile': 'profile-magic-link-update',
            'organization_invitation': 'organization-invitation-v2',
            'organization_invitation_accepted': 'org-member-joined',
            'passkey_added': 'security-passkey-created',
            'passkey_removed': 'security-passkey-deleted',
            'password_changed': 'security-password-updated',
            'password_removed': 'security-password-deleted',
            'primary_email_address_changed': 'profile-email-updated',
            'reset_password_code': 'reset-password-code-v2',
            'verification_code': 'verification-code-v2',
            'waitlist_confirmation': 'waitlist-signup-confirmed',
            'waitlist_invitation': 'waitlist-access-granted',
            'invitation': 'user-invitation'
        }
    } as const;

    export async function POST(request: Request) {
        try {
            const SIGNING_SECRET = process.env.SIGNING_SECRET
            if (!SIGNING_SECRET) {
                throw new Error('Please add SIGNING_SECRET from Clerk Dashboard to .env')
            }

            const webhook = new Webhook(SIGNING_SECRET)
            const headerPayload = await headers()
            const validatedHeaders = validateHeaders(headerPayload)

            const payload = await request.json()
            const body = JSON.stringify(payload)

            const event = await verifyWebhook(webhook, body, {
                'svix-id': validatedHeaders.svix_id,
                'svix-timestamp': validatedHeaders.svix_timestamp,
                'svix-signature': validatedHeaders.svix_signature,
            })

            await handleWebhookEvent(event)

            return new Response('Webhook received', { status: 200 })
        } catch (error) {
            console.error('Webhook processing error:', error)
            return new Response(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`, { status: 400 })
        }
    }

    const handleWebhookEvent = async (event: WebhookEvent) => {
        const workflow = await workflowBuilder(event)
        if (!workflow) {
            console.log(`Unsupported event type: ${event.type}`)
            return
        }

        const subscriber = await subscriberBuilder(event)
        const payload = await payloadBuilder(event)

        await triggerWorkflow(workflow, subscriber, payload)
    }

    async function workflowBuilder(event: WebhookEvent): Promise<string | undefined> {
        if (!EVENT_TO_WORKFLOW_MAPPINGS[event.type as keyof typeof EVENT_TO_WORKFLOW_MAPPINGS]) {
            return undefined;
        }

        if (event.type === 'email.created' && event.data.slug) {
            const emailMappings = EVENT_TO_WORKFLOW_MAPPINGS['email.created'];
            const emailSlug = event.data.slug as keyof typeof emailMappings;
            return emailMappings[emailSlug] || `email-${String(emailSlug).replace(/_/g, '-')}`;
        }

        return EVENT_TO_WORKFLOW_MAPPINGS[event.type as keyof typeof EVENT_TO_WORKFLOW_MAPPINGS] as string;
    }

    async function subscriberBuilder(response: WebhookEvent) {
        const userData = response.data as UserJSON;
        
        if (!userData.id) {
            throw new Error('Missing subscriber ID from webhook data');
        }

        return {
            subscriberId: (userData as any).user_id ?? userData.id,
            firstName: userData.first_name ?? undefined,
            lastName: userData.last_name ?? undefined,
            email: (userData.email_addresses?.[0]?.email_address ?? (userData as any).to_email_address) ?? undefined,
            phone: userData.phone_numbers?.[0]?.phone_number ?? undefined,
            locale: 'en_US',
            avatar: userData.image_url ?? undefined,
            data: {
                clerkUserId: (userData as any).user_id ?? userData.id,
                username: userData.username ?? '',
            },
        }
    }

    async function payloadBuilder(response: WebhookEvent) {
        return response.data;
    }

    const validateHeaders = (headerPayload: Headers) => {
        const svix_id = headerPayload.get('svix-id')
        const svix_timestamp = headerPayload.get('svix-timestamp')
        const svix_signature = headerPayload.get('svix-signature')

        if (!svix_id || !svix_timestamp || !svix_signature) {
            throw new Error('Missing Svix headers')
        }

        return { svix_id, svix_timestamp, svix_signature }
    }

    const verifyWebhook = async (webhook: Webhook, body: string, headers: any): Promise<WebhookEvent> => {
        try {
            return webhook.verify(body, headers) as WebhookEvent
        } catch (err) {
            console.error('Error: Could not verify webhook:', err)
            throw new Error('Verification error')
        }
    }
    ```

    <Accordions>
      <Accordion title="Breakdown of the code">
        ***

        **Imports and Dependencies**

        ```jsx
        import { Webhook } from 'svix'
        import { headers } from 'next/headers'
        import { WebhookEvent, UserJSON } from '@clerk/nextjs/server'
        import { triggerWorkflow } from '@/app/utils/novu'
        ```

        * `Webhook` from `svix`: This is a library used to verify the authenticity of incoming webhooks by checking their signatures. Webhooks often use signatures to ensure the payload hasn’t been tampered with.

        * `headers` from `next/headers`: A Next.js utility to access HTTP headers from the incoming request in the App Router.

        * `WebhookEvent` from `@clerk/nextjs/server`: A type definition for webhook events, likely provided by Clerk (a user authentication and management service). This ensures type safety when handling events.

        * `triggerWorkflow`: A custom function (imported from another file) that triggers a workflow. This is likely where notifications or other business logic is executed.

        ***

        **Event Mapping**

        ```jsx
        const EVENT_TO_WORKFLOW_MAPPINGS = {
           
            // Clerk webhook event type -> Novu workflowId

            // Session events
            'session.created': 'session-created',
            
            // User events
            'user.created': 'user-created',
            
            // Email events
            'email.created': {
                'magic_link_sign_in': 'auth-magic-link-login',
                'magic_link_sign_up': 'auth-magic-link-registration',
                'magic_link_user_profile': 'profile-magic-link-update',
                'organization_invitation': 'organization-invitation',
                'organization_invitation_accepted': 'org-member-joined',
                'passkey_added': 'security-passkey-created',
                'passkey_removed': 'security-passkey-deleted',
                'password_changed': 'security-password-updated',
                'password_removed': 'security-password-deleted',
                'primary_email_address_changed': 'profile-email-updated',
                'reset_password_code': 'reset-password-code',
                'verification_code': 'verification-code',
                'waitlist_confirmation': 'waitlist-signup-confirmed',
                'waitlist_invitation': 'waitlist-access-granted',
                'invitation': 'user-invitation'
            }
        } as const;
        ```

        This mapping defines how Clerk webhook events are associated with Novu workflows.

        ***

        **Main Entry Point: `POST` Handler**

        ```jsx
        export async function POST(request: Request) {
            try {
                const SIGNING_SECRET = process.env.SIGNING_SECRET
                if (!SIGNING_SECRET) {
                    throw new Error('Please add SIGNING_SECRET from Clerk Dashboard to .env')
                }

                const webhook = new Webhook(SIGNING_SECRET)
                const headerPayload = await headers()
                const validatedHeaders = validateHeaders(headerPayload)

                const payload = await request.json()
                const body = JSON.stringify(payload)

                const event = await verifyWebhook(webhook, body, {
                    'svix-id': validatedHeaders.svix_id,
                    'svix-timestamp': validatedHeaders.svix_timestamp,
                    'svix-signature': validatedHeaders.svix_signature,
                })

                await handleWebhookEvent(event)

                return new Response('Webhook received', { status: 200 })
            } catch (error) {
                console.error('Webhook processing error:', error)
                return new Response(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`, { status: 400 })
            }
        }
        ```

        This is the main function that handles incoming HTTP POST requests (webhook events).

        ***

        **Handling the Webhook Event: `handleWebhookEvent`**

        ```jsx
        const handleWebhookEvent = async (event: WebhookEvent) => {
            const workflow = await workflowBuilder(event)
            if (!workflow) {
                console.log(`Unsupported event type: ${event.type}`)
                return
            }

            const subscriber = await subscriberBuilder(event)
            const payload = await payloadBuilder(event)

            await triggerWorkflow(workflow, subscriber, payload)
        }
        ```

        This function processes the verified webhook event.

        ***

        **Identify the WorkflowID based on the event type: `workflowBuilder`**

        ```jsx
        async function workflowBuilder(event: WebhookEvent): Promise<string | undefined> {
            if (!EVENT_TO_WORKFLOW_MAPPINGS[event.type as keyof typeof EVENT_TO_WORKFLOW_MAPPINGS]) {
                return undefined;
            }

            if (event.type === 'email.created' && event.data.slug) {
                const emailMappings = EVENT_TO_WORKFLOW_MAPPINGS['email.created'];
                const emailSlug = event.data.slug as keyof typeof emailMappings;
                return emailMappings[emailSlug] || `email-${String(emailSlug).replace(/_/g, '-')}`;
            }

            return EVENT_TO_WORKFLOW_MAPPINGS[event.type as keyof typeof EVENT_TO_WORKFLOW_MAPPINGS] as string;
        }
        ```

        This function determines the workflow ID by mapping the Clerk webhook event type to the Novu workflow ID.

        ***

        **Building the Subscriber: `subscriberBuilder`**

        ```jsx
        async function subscriberBuilder(response: WebhookEvent) {
            const userData = response.data as UserJSON;
            
            if (!userData.id) {
                throw new Error('Missing subscriber ID from webhook data');
            }

            return {
                subscriberId: (userData as any).user_id ?? userData.id,
                firstName: userData.first_name ?? undefined,
                lastName: userData.last_name ?? undefined,
                email: (userData.email_addresses?.[0]?.email_address ?? (userData as any).to_email_address) ?? undefined,
                phone: userData.phone_numbers?.[0]?.phone_number ?? undefined,
                locale: 'en_US',
                avatar: userData.image_url ?? undefined,
                data: {
                    clerkUserId: (userData as any).user_id ?? userData.id,
                    username: userData.username ?? '',
                },
            }
        }
        ```

        This function builds the subscriber data based on the webhook event data.

        ***

        **Building the Payload: `payloadBuilder`**

        ```jsx
        async function payloadBuilder(response: WebhookEvent) {
            return response.data;
        }
        ```

        This function constructs (extracts from the webhook event) the payload object data that will be used within workflow trigger call.

        ***

        **Validating the Headers: `validateHeaders`**

        ```jsx
        const validateHeaders = (headerPayload: Headers) => {
            const svix_id = headerPayload.get('svix-id')
            const svix_timestamp = headerPayload.get('svix-timestamp')
            const svix_signature = headerPayload.get('svix-signature')

            if (!svix_id || !svix_timestamp || !svix_signature) {
                throw new Error('Missing Svix headers')
            }

            return { svix_id, svix_timestamp, svix_signature }
        }
        ```

        This function extracts and validates the Svix headers from the request.

        ***

        **Verifying the Webhook: `verifyWebhook`**

        ```jsx

        const verifyWebhook = async (webhook: Webhook, body: string, headers: any): Promise<WebhookEvent> => {
            try {
                return webhook.verify(body, headers) as WebhookEvent
            } catch (err) {
                console.error('Error: Could not verify webhook:', err)
                throw new Error('Verification error')
            }
        }
        ```

        This function verifies the authenticity of the webhook using the `svix` library.

        ***

        **How It All Fits Together**

        Here’s a high-level flow of how the code works:

        1. **Receive a Webhook:**
           The `POST` handler receives an `HTTP POST` request with a webhook payload.

        2. **Validate and Verify:**
           The `validateHeaders` function ensures the required Svix headers are present. The `verifyWebhook` function uses the `svix` library to verify the webhook’s authenticity.

        3. **Process the Event:**
           The `handleWebhookEvent` function filters events and processes only `user.created` or `email.created` events.

           It calls helper functions (`workflowBuilder`, `subscriberBuilder`, `payloadBuilder`) to construct the necessary data.

        4. **Trigger a Workflow:**
           The `triggerWorkflow` function is called with the constructed data, executing the desired business logic (e.g., sending notifications).

        ***
      </Accordion>
    </Accordions>
  </Step>

  <Step>
    ## Add Novu Workflow Notification Trigger Function

    Create `app/utils/novu.ts` :

    <Files>
      <Folder name="app" defaultOpen>
        <Folder name="utils" defaultOpen>
          <File name="novu.ts" />
        </Folder>

        <Folder name="api" defaultOpen>
          <Folder name="webhooks" defaultOpen>
            <Folder name="clerk" defaultOpen>
              <File name="route.ts" />
            </Folder>
          </Folder>
        </Folder>
      </Folder>
    </Files>

    ```jsx
    import { Novu } from '@novu/api';
    import { SubscriberPayloadDto } from '@novu/api/models/components/subscriberpayloaddto';

    const novu = new Novu({
        secretKey: process.env['NOVU_SECRET_KEY']
    });

    export async function triggerWorkflow(workflowId: string, subscriber: SubscriberPayloadDto, payload: object) {
        try {
            console.log("Payload:", payload ,"Triggering workflow:", workflowId, "Subscriber:", subscriber)
            await novu.trigger({
                workflowId,
                to: subscriber,
                payload
            });
            return new Response('Notification triggered', { status: 200 });
        } catch (error) {
            return new Response('Error triggering notification', { status: 500 });
        }
    }
    ```
  </Step>

  <Step>
    ## Add or create Novu workflows in your Novu dashboard

    In Novu, a webhook event—such as a user being created or updated—can trigger one or more workflows, depending on how you want to handle these events in your application.

    A workflow defines a sequence of actions (e.g., sending notifications, updating records) that execute when triggered by a webhook.

    The Novu dashboard allows you to either create a custom workflow from scratch or choose from pre-built templates to streamline the process.

    **Steps to Create a Workflow**

    Follow these steps to set up your workflow(s) in the Novu dashboard:

    ### Identify the Triggering Event(s)

    Determine which webhook events will activate your workflow (e.g., "user created," "user updated").

    Check your webhook configuration to understand the event data being sent.

    <Accordions>
      <Accordion title="Supported webhook events">
        To find a list of all the events Clerk supports:

        1. In the Clerk Dashboard, navigate to the Webhooks page.
        2. Select the Event Catalog tab.
      </Accordion>

      <Accordion title="Payload structure">
        The payload of a webhook is a JSON object that contains the following properties:

        * `data`: contains the actual payload sent by Clerk.
          The payload can be a different object depending on the event type.

          For example, for `user.*` events, the payload will always be the [User object](https://clerk.com/docs/references/javascript/user).

        * `object`: always set to `event`.

        * `type`: the type of event that triggered the webhook.

        * `timestamp`: timestamp in milliseconds of when the event occurred.

        * `instance_id`: the identifier of your Clerk instance.

        The following example shows the payload of a `user.created` event:

        ```json
        {
        "data": {
          "birthday": "",
          "created_at": 1654012591514,
          "email_addresses": [
            {
              "email_address": "exaple@example.org",
              "id": "idn_29w83yL7CwVlJXylYLxcslromF1",
              "linked_to": [],
              "object": "email_address",
              "verification": {
                "status": "verified",
                "strategy": "ticket"
              }
            }
          ],
          "external_accounts": [],
          "external_id": "567772",
          "first_name": "Example",
          "gender": "",
          "id": "user_29w83sxmDNGwOuEthce5gg56FcC",
          "image_url": "https://img.clerk.com/xxxxxx",
          "last_name": "Example",
          "last_sign_in_at": 1654012591514,
          "object": "user",
          "password_enabled": true,
          "phone_numbers": [],
          "primary_email_address_id": "idn_29w83yL7CwVlJXylYLxcslromF1",
          "primary_phone_number_id": null,
          "primary_web3_wallet_id": null,
          "private_metadata": {},
          "profile_image_url": "https://www.gravatar.com/avatar?d=mp",
          "public_metadata": {},
          "two_factor_enabled": false,
          "unsafe_metadata": {},
          "updated_at": 1654012591835,
          "username": null,
          "web3_wallets": []
        },
        "instance_id": "ins_123",
        "object": "event",
        "timestamp": 1654012591835,
        "type": "user.created"
        }
        ```
      </Accordion>
    </Accordions>

    ### Choose Your Starting Point

    <Tabs items={['Use a Workflow Template', 'Create a Blank Workflow', 'Code-First Workflow (Novu Framework)']}>
      <Tab value="Use a Workflow Template">
        Browse the workflow template store in the Novu dashboard. If a template matches your use case (e.g., "User Onboarding"), select it and proceed to customize it.

        ![Dashboard Template Store](./media-assets/clerk/workflow-fromTemplate.gif)
      </Tab>

      <Tab value="Create a Blank Workflow">
        If no template fits or you need full control, start with a blank workflow and define every step yourself.

        ![Dashboard Blank Workflow](./media-assets/clerk/blankWorkflow.gif)
      </Tab>

      <Tab value="Code-First Workflow (Novu Framework)">
        If you prefer a more code-based approach, you can create a workflow using the Novu Framework.

        <Card title="Novu Framework" icon={<NextjsIcon />} href="/framework">
          <p>
            The Novu framework allows you to build and manage advanced notification workflows with code, and expose no-code controls for non-technical users to modify.
          </p>
        </Card>
      </Tab>
    </Tabs>

    ### Configure the Workflow

    * For a template, tweak the existing steps to align with your requirements.

    * For a blank workflow, add actions like sending emails, sending in-app notifications, Push notifications, or other actions.

    * For a code-first workflow, you can use the Novu Framework to build your workflow right within your code base.

    ### Set Trigger Conditions

    * Link the workflow to the correct webhook event(s).

    * Ensure the trigger matches the event data (e.g., event type or payload) sent by your application.

    <Callout type="info" title="Tips for Success" color="yellow">
      - **Start Simple:** Use templates for common tasks and switch to blank workflows for unique needs.

      - **Test Thoroughly:** Simulate webhook events to ensure your workflows behave as expected.

      - **Plan for Growth:** Organize workflows logically (separate or combined) to make future updates easier.
    </Callout>
  </Step>

  <Step>
    ## Disable Email **Delivered by Clerk**

    By default, Clerk sends email notifications whenever necessary, such as Magic Links for email verification, Invitations, Password Resets, and more.

    To prevent users from receiving duplicate emails, we need to disable email delivery by Clerk for the notifications handled by Novu.

    1. Navigate to the **Emails** section in the Clerk Dashboard.

       ![Clerk's Dashboard 1](/images/guides/clerk/clerk-email-dashboard.png)

    2. Select any **email.created** event that you want Novu to handle.

    3. Toggle **off** email delivery for the selected event.

       ![Clerk's Dashboard 2](/images/guides/clerk/clerk-email-dashboard2.png)

    This ensures that Clerk does not send duplicate emails, allowing Novu to manage the notifications seamlessly.
  </Step>

  <Step>
    ## Test the Webhook

    1. Start your Next.js server.
    2. Go to **Clerk Webhooks → Testing**.
    3. Select an event (e.g., `user.created`, `email.created`).
    4. Click **Send Example**.
    5. Verify logs in **your terminal**.
  </Step>
</Steps>


# How to integrate Segment with Novu (/guides/webhooks/segment)

Learn how to set up Segment as a data source for Novu using Destination Functions. Send user events from Segment to trigger notifications in Novu.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { NextjsIcon } from '@/components/icons/nextjs';
import { ExpressjsIcon } from '@/components/icons/expressjs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { File, Folder, Files } from 'fumadocs-ui/components/files';

This guide demonstrates how to use Segment's Destination Functions to send user events and traits to Novu. You'll learn how to:

* Create a custom Segment destination for Novu
* Map Segment identify calls to Novu subscribers
* Trigger notification workflows from Segment track events
* Handle errors and retry logic for reliable delivery

By the end, you'll have a working integration that creates subscribers and triggers notification workflows in Novu based on Segment events.

<Callout type="info">
  **Prerequisites**

  Before you start, ensure you have:

  * A **Segment account** with access to **Functions** (check your workspace permissions)
  * A **Novu account** with an **API key** (find this in your Novu dashboard under Settings > API Keys)
</Callout>

<Steps>
  <Step>
    ## Create a Destination Function in Segment

    1. Log in to your Segment account
    2. Navigate to **Connections** > **Functions** in the left sidebar
    3. Click **New Function** and select **Destination**
    4. Name your function (e.g., Novu Destination) and click **Create Function**
  </Step>

  <Step>
    ## Configure the Destination Function

    The Destination Function will handle two key Segment event types:

    * **identify**: Creates or updates a subscriber in Novu
    * **track**: Triggers a notification workflow in Novu

    Paste the following complete code into the Segment Function editor:

    ```jsx
    /**
     * Handles identify events: Creates or updates a subscriber in Novu
     * @param {SegmentIdentifyEvent} event - The Segment identify event
     * @param {FunctionSettings} settings - Function settings including API key
     */
    async function onIdentify(event, settings) {
      const endpoint = 'https://api.novu.co/v2/subscribers';
      const apiKey = settings.apiKey;

      if (!apiKey) throw new Error('Novu API key is missing in settings');
      if (!event.userId) throw new Error('userId is required in identify event');

      const subscriberData = {
        subscriberId: event.userId,
        firstName: event.traits?.firstName || null,
        lastName: event.traits?.lastName || null,
        email: event.traits?.email || null,
        phone: event.traits?.phone || null,
        avatar: event.traits?.avatar || null,
      };

      try {
        const response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            'Authorization': `ApiKey ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(subscriberData)
        });

        const responseBody = await response.json();
        if (!response.ok) {
          if (response.status >= 500 || response.status === 429) {
            throw new RetryError(`Server error: ${response.status}`);
          }
          throw new Error(`API error: ${response.status} - ${responseBody.message || 'Unknown error'}`);
        }
      } catch (error) {
        throw error instanceof RetryError ? error : new RetryError(error.message);
      }
    }

    // Mapping of Segment track events to Novu workflows
    const EVENT_TO_WORKFLOW_MAPPINGS = {
      'User Registered': 'welcome'
      // Add more mappings: 'Event Name': 'novu-workflow-name'
    };

    /**
     * Handles track events: Triggers a notification workflow in Novu
     * @param {SegmentTrackEvent} event - The Segment track event
     * @param {FunctionSettings} settings - Function settings including API key
     */
    async function onTrack(event, settings) {
      const endpoint = 'https://api.novu.co/v1/events/trigger';
      const apiKey = settings.apiKey;

      if (!apiKey) throw new Error('Novu API key is missing in settings');
      if (!event.userId) throw new Error('userId is required in track event');

      const workflow = EVENT_TO_WORKFLOW_MAPPINGS[event.event];
      if (!workflow) throw new Error(`No workflow mapped for event: ${event.event}`);

      const triggerEvent = {
        name: workflow,
        to: { subscriberId: event.userId },
        payload: event.properties || {}
      };

      try {
        const response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            'Authorization': `ApiKey ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(triggerEvent)
        });

        const responseBody = await response.json();
        if (!response.ok) {
          if (response.status >= 500 || response.status === 429) {
            throw new RetryError(`Server error: ${response.status}`);
          }
          throw new Error(`API error: ${response.status} - ${responseBody.message || 'Unknown error'}`);
        }
      } catch (error) {
        throw error instanceof RetryError ? error : new RetryError(error.message);
      }
    }
    ```

    <Accordions>
      <Accordion title="Code Explanation">
        * **`onIdentify`**:
          * Maps Segment traits (e.g., firstName, lastName, email) to Novu subscriber fields
          * Uses Novu's `/v2/subscribers` endpoint
          * Creates or updates subscribers (Novu's API is idempotent for existing `subscriberIds`)
        * **`onTrack`**:
          * Maps Segment `track` events to Novu workflows using `EVENT_TO_WORKFLOW_MAPPINGS`
          * Sends the event properties as the payload to trigger a workflow via `/v1/events/trigger`
        * **Error Handling**: Retries on server errors (5xx) or rate limits (429), fails fast on other errors
      </Accordion>
    </Accordions>

    <Callout type="info">
      **Customize the Mapping**: Update `EVENT_TO_WORKFLOW_MAPPINGS` with your Segment event names and corresponding Novu workflow names.
    </Callout>
  </Step>

  <Step>
    ## Deploy the Function

    1. Click **Save** in the Function editor
    2. Enable the function by toggling it to **Active**
  </Step>

  <Step>
    ## Connect the Function to a Source

    1. Go to **Connections** > Select your **Source** (e.g., website, app)
    2. In the **Destinations** tab, click **Add Destination**
    3. Choose your **Novu Destination Function** from the list
    4. Click **Connect**. When prompted, enter your **Novu API key** in the apiKey field
    5. Save the configuration
  </Step>

  <Step>
    ## Testing the Integration

    Verify everything works:

    <Accordions>
      <Accordion title="1. Send an identify event">
        Example:

        ```json
        {
          "type": "identify",
          "traits": {
            "name": "Peter Gibbons",
            "email": "peter@example.com",
            "plan": "premium",
            "logins": 5
          },
          "userId": "97980cfea0067"
        }
        ```

        Check Novu's **Subscribers** list to confirm the subscriber appears.
      </Accordion>

      <Accordion title="2. Send a track event">
        Example:

        ```json
        {
          "type": "track",
          "event": "User Registered",
          "properties": {
            "plan": "Pro Annual",
            "accountType" : "Facebook"
          }
        }
        ```

        Verify the `welcome` workflow triggers in Novu's activity feed.
      </Accordion>
    </Accordions>

    Use Segment's **Debugger** to monitor function calls and catch any errors.
  </Step>
</Steps>

<Accordions>
  <Accordion title="Troubleshooting">
    * **401 Unauthorized**: Double-check your Novu API key in the function settings
    * **Subscriber Not Created**: Ensure userId is included in the identify event
    * **Workflow Not Triggering**: Confirm the event name matches a key in EVENT\_TO\_WORKFLOW\_MAPPINGS and the workflow exists in Novu
    * **API Errors**: Check Segment's logs for detailed error messages
  </Accordion>

  <Accordion title="Additional Notes">
    * **Subscriber Updates**: Novu's /v1/subscribers endpoint updates existing subscribers if the subscriberId matches, keeping data current with each identify event
    * **Expanding Functionality**: Add more event types (e.g., group, page) by defining additional handlers like onGroup in the code
  </Accordion>
</Accordions>

With this setup, your Segment events will seamlessly flow into Novu, enabling powerful notification workflows tailored to your users' actions.


# Novu and Stripe integration guide (/guides/webhooks/stripe)

This guide walks you through integrating Stripe webhooks with Novu notifications in a Next.js application.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { NextjsIcon } from '@/components/icons/nextjs';
import { ExpressjsIcon } from '@/components/icons/expressjs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { File, Folder, Files } from 'fumadocs-ui/components/files';

You'll learn how to automatically trigger notification workflows when **any Stripe event** occurs, such as **payment, subscription, or customer events**.

## Overview

When specific events happen in Stripe (e.g., payment, subscription, or customer events), this integration will:

1. Receive the webhook event from Stripe.
2. Verify the webhook signature.
3. Process the event data.
4. Trigger the corresponding **Novu notification workflow**.

<Callout>
  You can also clone this repository: [https://github.com/novuhq/stripe-to-novu-webhooks](https://github.com/novuhq/stripe-to-novu-webhooks)
</Callout>

## Prerequisites

Before proceeding, ensure you have:

* A **Stripe account** ([Sign up here](https://dashboard.stripe.com/signup)).
* A **Novu account** ([Sign up here](https://novu.com/signup)).

<Steps>
  <Step>
    ## Install Dependencies

    Run the following command to install the required packages:

    ```
    npm install @novu/api @clerk/nextjs @stripe
    ```
  </Step>

  <Step>
    ## Configure Environment Variables

    Add the following variables to your `.env.local` file:

    ```
    NOVU_SECRET_KEY=novu_secret_...
    STRIPE_SECRET_KEY=sk_test_...
    STRIPE_WEBHOOK_SECRET=whsec_...
    ```
  </Step>

  <Step>
    ## Expose Your Local Server

    To test webhooks locally, you need to expose your **local server** to the internet.

    There are two common options:

    <Tabs items={['localtunnel', 'ngrok']}>
      <Tab value="localtunnel">
        ### localtunnel

        **localtunnel** is a simple and free way to expose your local server without requiring an account.

        1. Start a localtunnel listener

           ```bash
           npx localtunnel 3000
           ```

        2. Copy and save the generated **public URL** (e.g., `https://your-localtunnel-url.loca.lt`).

        Learn more about **localtunnel** [here](https://www.npmjs.com/package/localtunnel).

        <Callout>
          **localtunnel** links may expire quickly and sometimes face reliability issues.
        </Callout>
      </Tab>

      <Tab value="ngrok">
        ### ngrok

        For a more stable and configurable tunnel, use **ngrok**:

        1. Create an account at [ngrok dashboard](https://dashboard.ngrok.com/).

        2. Follow the [setup guide](https://dashboard.ngrok.com/get-started/setup).

        3. Run the command:

           ```bash
           ngrok http 3000
           ```

        4. Copy and save the **Forwarding URL** (e.g., `https://your-ngrok-url.ngrok.io`).

        Learn more about **ngrok** [here](https://dashboard.ngrok.com/get-started/setup).
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Set Up Stripe Webhook Endpoint

    Stripe supports two endpoint types: Account and Connect. Create an endpoint for Account unless you’ve created a Connect application. You can register up to 16 webhook endpoints on each Stripe account.

    <Callout type="info" title="Note">
      When you create an endpoint in the Dashboard, you can choose between your Account’s API version or the latest API version. You can test other API versions in Workbench using stripe webhook\_endpoints create, but you must create a webhook endpoint using the API to use other API versions in production.
    </Callout>

    Use the following steps to register a webhook endpoint in the Developers Dashboard.

    1. Navigate to the [**Webhooks page**](https://dashboard.stripe.com/webhooks).

    2. Click **Add Endpoint**.

    3. Add your webhook endpoint’s HTTPS URL in **Endpoint URL**.

       ```
          https://your-forwarding-URL/api/webhooks/stripe
       ```

    4. If you have a **Stripe Connect account**, enter a description, then click **Listen to events** on **Connected accounts**.

    5. Select the [event types](https://docs.stripe.com/api#event_types) you’re currently receiving in your local webhook endpoint in **Select events**.

    6. Click **Add endpoint**.
  </Step>

  <Step>
    ## Add Signing Secret to Environment Variables

    1. Copy the **Signing Secret** from Stripe's **Webhook Endpoint Settings**.
    2. Add it to your `.env.local` file:

    ```
    STRIPE_WEBHOOK_SECRET=your_signing_secret_here
    ```
  </Step>

  <Step>
    ## Make Webhook Route Public

    Ensure the webhook route is public by updating `middleware.ts` :

    ```jsx
    import { clerkMiddleware } from '@clerk/nextjs/server';

    export default clerkMiddleware({
      publicRoutes: ['/api/webhooks'],
    });
    ```
  </Step>

  <Step>
    ## Create Webhook Endpoint for Clerk in Next.js

    Create `app/api/webhooks/stripe/route.ts`:

    <Files>
      <Folder name="app" defaultOpen>
        <Folder name="api" defaultOpen>
          <Folder name="webhooks" defaultOpen>
            <Folder name="stripe" defaultOpen>
              <File name="route.ts" />
            </Folder>
          </Folder>
        </Folder>
      </Folder>
    </Files>

    The following snippet is the complete code of how to create a webhook endpoint for Clerk in Next.js:

    ```jsx
    import Stripe from "stripe";
    import { NextResponse, NextRequest } from "next/server";
    import { triggerWorkflow } from "@/app/utils/novu";


    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

    const supportedEvents = [
      "customer.subscription.created",
      "customer.subscription.updated",
    ];

    export async function POST(request: NextRequest) {
      const webhookPayload = await request.text();
      const response = JSON.parse(webhookPayload);

      const signature = request.headers.get("Stripe-Signature");

      try {
        let event = stripe.webhooks.constructEvent(
          webhookPayload,
          signature!,
          process.env.STRIPE_WEBHOOK_SECRET!
        );

        if (supportedEvents.includes(event.type)) {
          const workflow = event.type.replaceAll(".", "-");
          const subscriber = await buildSubscriberData(response);
          const payload = await payloadBuilder(response);
          console.log(
            "Triggering workflow:", workflow,
            "Subscriber:", subscriber,
            "Payload:", payload
          );
          return await triggerWorkflow(workflow, subscriber, payload);
        }

        return NextResponse.json({ status: "success", event: event.type, response: response });
      } catch (error) {
        return NextResponse.json({ status: "Failed", error });
      }
    }



    async function buildSubscriberData(response: any) {
      const customer = await stripe.customers.retrieve(response.data.object.customer);
      console.log("Customer", customer);
      
      if ('deleted' in customer) {
        throw new Error('Customer has been deleted');
      }
      
      // Split the full name into first and last name
      const [firstName = '', lastName = ''] = (customer.name || '').split(' ');
      
      return {
        subscriberId: customer.id,
        email: customer.email || 'test2@test.com',
        firstName: firstName || '',
        lastName: lastName || '',
        phone: customer?.phone || '',
        locale: customer?.preferred_locales?.[0] || 'en', // Use first preferred locale or default to 'en'
        avatar: '', // Stripe customer doesn't have avatar
        data: {
          stripeCustomerId: customer.id,
        },
      };
    }

    async function payloadBuilder(response: any) {
      const webhookData = JSON.parse(response);
      return webhookData;
    }
    ```
  </Step>

  <Step>
    ## Add Novu Workflow Notification Trigger Function

    Create `app/utils/novu.ts` :

    <Files>
      <Folder name="app" defaultOpen>
        <Folder name="utils" defaultOpen>
          <File name="novu.ts" />
        </Folder>

        <Folder name="api" defaultOpen>
          <Folder name="webhooks" defaultOpen>
            <Folder name="stripe" defaultOpen>
              <File name="route.ts" />
            </Folder>
          </Folder>
        </Folder>
      </Folder>
    </Files>

    ```jsx
    import { Novu } from '@novu/api';
    import { SubscriberPayloadDto } from '@novu/api/models/components/subscriberpayloaddto';

    const novu = new Novu({
        secretKey: process.env['NOVU_SECRET_KEY']
    });

    export async function triggerWorkflow(workflowId: string, subscriber: SubscriberPayloadDto, payload: object) {
        try {
            console.log("Payload:", payload ,"Triggering workflow:", workflowId, "Subscriber:", subscriber)
            await novu.trigger({
                workflowId,
                to: subscriber,
                payload
            });
            return new Response('Notification triggered', { status: 200 });
        } catch (error) {
            return new Response('Error triggering notification', { status: 500 });
        }
    }
    ```
  </Step>

  <Step>
    ## Add or create Novu workflows in your Novu dashboard

    In Novu, a webhook event—such as a user being created or updated—can trigger one or more workflows, depending on how you want to handle these events in your application.

    A workflow defines a sequence of actions (e.g., sending notifications, updating records) that execute when triggered by a webhook.

    The Novu dashboard allows you to either create a custom workflow from scratch or choose from pre-built templates to streamline the process.

    ***

    Follow these steps to set up your workflow(s) in the Novu dashboard:

    ### Identify the Triggering Event(s)

    Determine which webhook events will activate your workflow (e.g., "user created," "user updated").

    Check your webhook configuration to understand the event data being sent.

    <Accordions>
      <Accordion title="Supported webhook events">
        To find a list of all the events Stripe supports and learn more about them, visit the [Stripe documentation](https://docs.stripe.com/event-destinations).
      </Accordion>

      <Accordion title="Payload structure">
        The following example shows the payload of a `customer.subscription.created` event:

        ```json
        {
        "object": {
          "id": "sub_1Qy9WoR7RyRE3Uxrj6iaIAHV",
          "object": "subscription",
          "application": null,
          "application_fee_percent": null,
          "automatic_tax": {
            "disabled_reason": null,
            "enabled": false,
            "liability": null
          },
          "billing_cycle_anchor": 1740910426,
          "billing_cycle_anchor_config": null,
          "billing_thresholds": null,
          "cancel_at": null,
          "cancel_at_period_end": false,
          "canceled_at": null,
          "cancellation_details": {
            "comment": null,
            "feedback": null,
            "reason": null
          },
          "collection_method": "charge_automatically",
          "created": 1740910426,
          "currency": "usd",
          "current_period_end": 1743588826,
          "current_period_start": 1740910426,
          "customer": "cus_RrtJuJIveFMpmq",
          "days_until_due": null,
          "default_payment_method": null,
          "default_source": null,
          "default_tax_rates": [],
          "description": null,
          "discount": null,
          "discounts": [],
          "ended_at": null,
          "invoice_settings": {
            "account_tax_ids": null,
            "issuer": {
              "type": "self"
            }
          },
          "items": {
            "object": "list",
            "data": [
              {
                "id": "si_sdfsFwsthbHIUHJY",
                "object": "subscription_item",
                "billing_thresholds": null,
                "created": 1740910426,
                "discounts": [],
                "metadata": {},
                "plan": {
                  "id": "price_1Qy9WnR7RyRE3UxrRi33EJNc",
                  "object": "plan",
                  "active": true,
                  "aggregate_usage": null,
                  "amount": 1500,
                  "amount_decimal": "1500",
                  "billing_scheme": "per_unit",
                  "created": 1740910425,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {},
                  "meter": null,
                  "nickname": null,
                  "product": "prod_RrtJKUBhMKqoHb",
                  "tiers_mode": null,
                  "transform_usage": null,
                  "trial_period_days": null,
                  "usage_type": "licensed"
                },
                "price": {
                  "id": "price_1Qy9WnR7RyRE3UxrRi33EJNc",
                  "object": "price",
                  "active": true,
                  "billing_scheme": "per_unit",
                  "created": 1740910425,
                  "currency": "usd",
                  "custom_unit_amount": null,
                  "livemode": false,
                  "lookup_key": null,
                  "metadata": {},
                  "nickname": null,
                  "product": "prod_RrtJKUBhMKqoHb",
                  "recurring": {
                    "aggregate_usage": null,
                    "interval": "month",
                    "interval_count": 1,
                    "meter": null,
                    "trial_period_days": null,
                    "usage_type": "licensed"
                  },
                  "tax_behavior": "unspecified",
                  "tiers_mode": null,
                  "transform_quantity": null,
                  "type": "recurring",
                  "unit_amount": 1500,
                  "unit_amount_decimal": "1500"
                },
                "quantity": 1,
                "subscription": "sub_1Qy9WoR7RyRE3Uxrj6iaIAHV",
                "tax_rates": []
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/subscription_items?subscription=sub_1Qy9WoR7RyRE3Uxrj6iaIAHV"
          },
          "latest_invoice": "in_1Qy9WoR7RyRE3UxrNBjqvFxM",
          "livemode": false,
          "metadata": {},
          "next_pending_invoice_item_invoice": null,
          "on_behalf_of": null,
          "pause_collection": null,
          "payment_settings": {
            "payment_method_options": null,
            "payment_method_types": null,
            "save_default_payment_method": "off"
          },
          "pending_invoice_item_interval": null,
          "pending_setup_intent": null,
          "pending_update": null,
          "plan": {
            "id": "price_1Qy9WnR7RyRE3UxrRi33EJNc",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 1500,
            "amount_decimal": "1500",
            "billing_scheme": "per_unit",
            "created": 1740910425,
            "currency": "usd",
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {},
            "meter": null,
            "nickname": null,
            "product": "prod_RrtJKUBhMKqoHb",
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "quantity": 1,
          "schedule": null,
          "start_date": 1740910426,
          "status": "active",
          "test_clock": null,
          "transfer_data": null,
          "trial_end": null,
          "trial_settings": {
            "end_behavior": {
              "missing_payment_method": "create_invoice"
            }
          },
          "trial_start": null
        },
        "previous_attributes": null
        }
        ```
      </Accordion>
    </Accordions>

    ### Choose Your Starting Point

    <Tabs items={['Use a Workflow Template', 'Create a Blank Workflow', 'Code-First Workflow (Novu Framework)']}>
      <Tab value="Use a Workflow Template">
        Browse the workflow template store in the Novu dashboard. If a template matches your use case (e.g., "User Onboarding"), select it and proceed to customize it.

        ![Dashboard Template Store](./media-assets/clerk/workflow-fromTemplate.gif)
      </Tab>

      <Tab value="Create a Blank Workflow">
        If no template fits or you need full control, start with a blank workflow and define every step yourself.

        ![Dashboard Blank Workflow](./media-assets/clerk/blankWorkflow.gif)
      </Tab>

      <Tab value="Code-First Workflow (Novu Framework)">
        If you prefer a more code-based approach, you can create a workflow using the Novu Framework.

        <Card title="Novu Framework" icon={<NextjsIcon />} href="/framework">
          <p>
            The Novu framework allows you to build and manage advanced notification workflows with code, and expose no-code controls for non-technical users to modify.
          </p>
        </Card>
      </Tab>
    </Tabs>

    ### Configure the Workflow

    * For a template, tweak the existing steps to align with your requirements.

    * For a blank workflow, add actions like sending emails, sending in-app notifications, Push notifications, or other actions.

    * For a code-first workflow, you can use the Novu Framework to build your workflow right within your code base.

    ### Set Trigger Conditions

    * Link the workflow to the correct webhook event(s).

    * Ensure the trigger matches the event data (e.g., event type or payload) sent by your application.

    <Callout type="info" title="Tips for Success" color="yellow">
      - **Start Simple:** Use templates for common tasks and switch to blank workflows for unique needs.

      - **Test Thoroughly:** Simulate webhook events to ensure your workflows behave as expected.

      - **Plan for Growth:** Organize workflows logically (separate or combined) to make future updates easier.
    </Callout>
  </Step>

  <Step>
    ## Disable Email Delivery by Stripe

    By default, Stripe sends email notifications whenever necessary, such as subscription created, updated, and more.

    To prevent users from receiving duplicate emails, we need to disable email delivery by Stripe for the notifications handled by Novu.

    1. In your Stripe Dashboard, navigate to the **Settings**.

    2. Under the **Product Settings** section, navigate to the **Billing** tab.

    3. Toggle **off** delivery of the events you want to handle with Novu.

    This ensures that Stripe does not send duplicate emails, allowing Novu to manage the notifications seamlessly.
  </Step>

  <Step>
    ## Test the Webhook

    <Cards>
      <Card title="Stripe CLI" href="https://docs.stripe.com/stripe-cli/triggers">
        Learn how you can test the webhook events using the Stripe CLI.
      </Card>
    </Cards>
  </Step>
</Steps>


# Track provider activity and engagement events (/api-reference/activity/track-provider-activity-and-engagement-events)

Track activity and engagement events for a specific delivery provider

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/inbound-webhooks/delivery-providers/{environmentId}/{integrationId}","method":"post"}]} webhooks={[]} hasHead={false} />


# Create a channel connection (/api-reference/channel-connections/create-a-channel-connection)

Create a new channel connection for a resource for given integration. Only one channel connection is allowed per resource and integration.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-connections","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a channel connection (/api-reference/channel-connections/delete-a-channel-connection)

Delete a specific channel connection by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-connections/{identifier}","method":"delete"}]} webhooks={[]} hasHead={false} />


# List all channel connections (/api-reference/channel-connections/list-all-channel-connections)

List all channel connections for a resource.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-connections","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a channel connection (/api-reference/channel-connections/retrieve-a-channel-connection)

Retrieve a specific channel connection by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-connections/{identifier}","method":"get"}]} webhooks={[]} hasHead={false} />


# Update a channel connection (/api-reference/channel-connections/update-a-channel-connection)

Update an existing channel connection by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-connections/{identifier}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Create a channel endpoint (/api-reference/channel-endpoints/create-a-channel-endpoint)

Create a new channel endpoint for a resource.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-endpoints","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a channel endpoint (/api-reference/channel-endpoints/delete-a-channel-endpoint)

Delete a specific channel endpoint by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-endpoints/{identifier}","method":"delete"}]} webhooks={[]} hasHead={false} />


# List all channel endpoints (/api-reference/channel-endpoints/list-all-channel-endpoints)

List all channel endpoints for a resource based on query filters.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-endpoints","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a channel endpoint (/api-reference/channel-endpoints/retrieve-a-channel-endpoint)

Retrieve a specific channel endpoint by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-endpoints/{identifier}","method":"get"}]} webhooks={[]} hasHead={false} />


# Update a channel endpoint (/api-reference/channel-endpoints/update-a-channel-endpoint)

Update an existing channel endpoint by its unique identifier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/channel-endpoints/{identifier}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Context schema Model API Reference (Contexts) (/api-reference/contexts/context-schema)

Reference the Novu context schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Context

**Context** is a reusable, user-defined data object that stores metadata (like tenant, region, or app details) to organize and personalize notifications. Unlike payloads that exist only for a single workflow execution, contexts are persistent and can be shared across multiple workflows and API calls.
This makes them particularly useful for multi-tenant applications, dynamic branding, and scenarios where notifications need to reference common, reusable data.

Read more about how to use contexts in workflows in the [contexts](/platform/workflow/advanced-features/contexts) section.


# Create a context (/api-reference/contexts/create-a-context)

Create a new context with the specified type, id, and data. Returns 409 if context already exists.
      **type** and **id** are required fields, **data** is optional, if the context already exists, it returns the 409 response

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/contexts","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a context (/api-reference/contexts/delete-a-context)

Delete a context by its type and id.
      **type** and **id** are required fields, if the context does not exist, it returns the 404 response

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/contexts/{type}/{id}","method":"delete"}]} webhooks={[]} hasHead={false} />


# List all contexts (/api-reference/contexts/list-all-contexts)

Retrieve a paginated list of all contexts, optionally filtered by type and key pattern.
      **type** and **id** are optional fields, if provided, only contexts with the matching type and id will be returned.
      **search** is an optional field, if provided, only contexts with the matching key pattern will be returned.
      Checkout all possible parameters in the query section below for more details

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/contexts","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a context (/api-reference/contexts/retrieve-a-context)

Retrieve a specific context by its type and id.
      **type** and **id** are required fields, if the context does not exist, it returns the 404 response

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/contexts/{type}/{id}","method":"get"}]} webhooks={[]} hasHead={false} />


# Update a context (/api-reference/contexts/update-a-context)

Update the data of an existing context.
      **type** and **id** are required fields, **data** is required. Only the data field is updated, the rest of the context is not affected.
      If the context does not exist, it returns the 404 response

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/contexts/{type}/{id}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Create a variable (/api-reference/environment-variables/create-a-variable)

Creates a new environment variable. Keys must be uppercase with underscores only (e.g. BASE_URL). Secret variables are encrypted at rest and masked in API responses.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete environment variable (/api-reference/environment-variables/delete-environment-variable)

Deletes an environment variable by key.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables/{variableKey}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Environment variable schema Model API Reference (Environment Variables) (/api-reference/environment-variables/environment-variable-schema)

Reference the Novu environment variable schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Environment Variable

Environment variable is a named value you define once in the dashboard and reuse across workflows. Each [Novu environment](/platform/developer/environments) can hold its own value for the same variable, so Development and Production (and any custom environments) stay isolated without duplicating workflow logic. Read more about environment variables on [environment variables documentation page](/platform/developer/environment-variables).

<TypeTable
  name="EnvironmentVariable"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"organizationId": {
  "description": "",
  "type": "string"
},
"key": {
  "description": "",
  "type": "string"
},
"type": {
  "description": "",
  "type": "\"string\""
},
"isSecret": {
  "description": "",
  "type": "boolean"
},
"values": {
  "description": "",
  "type": "EnvironmentVariableValueResponseDto[]"
},
"createdAt": {
  "description": "",
  "type": "string"
},
"updatedAt": {
  "description": "",
  "type": "string"
}
}}
/>


# Get environment variable (/api-reference/environment-variables/get-environment-variable)

Returns a single environment variable by key. Secret values are masked.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables/{variableKey}","method":"get"}]} webhooks={[]} hasHead={false} />


# List all variables (/api-reference/environment-variables/list-all-variables)

Returns all environment variables for the current organization. Secret values are masked.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a variable usage (/api-reference/environment-variables/retrieve-a-variable-usage)

Returns the workflows that reference this environment variable via `{{env.KEY}}` in their step controls. **variableId** is required.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables/{variableKey}/usage","method":"get"}]} webhooks={[]} hasHead={false} />


# Update a variable (/api-reference/environment-variables/update-a-variable)

Updates an existing environment variable. Providing values replaces all existing per-environment values.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environment-variables/{variableKey}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Compare resources between environments (/api-reference/environments/compare-resources-between-environments)

Compares workflows and other resources between the source and target environments, returning detailed diff information including additions, modifications, and deletions.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/environments/{targetEnvironmentId}/diff","method":"post"}]} webhooks={[]} hasHead={false} />


# Create an environment (/api-reference/environments/create-an-environment)

Creates a new environment within the current organization. 
    Environments allow you to manage different stages of your application development lifecycle.
    Each environment has its own set of API keys and configurations.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environments","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete an environment (/api-reference/environments/delete-an-environment)

Delete an environment by its unique identifier **environmentId**. 
    This action is irreversible and will remove the environment and all its associated data.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environments/{environmentId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Environment schema Model API Reference (Environments) (/api-reference/environments/environment-schema)

Reference the Novu environment schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Environment

Environment is a collection of resources that are used to send notifications. For example, an environment can have a set of integrations, workflows, and subscribers. Read more about environments on [environments concept page](/platform/developer/environments).

<TypeTable
  name="Environment"
  type={{
"id": {
  "description": "Unique identifier of the environment",
  "type": "string"
},
"name": {
  "description": "Name of the environment",
  "type": "string"
},
"organizationId": {
  "description": "Organization ID associated with the environment",
  "type": "string"
},
"identifier": {
  "description": "Unique identifier for the environment",
  "type": "string"
},
"type": {
  "description": "Type of the environment",
  "type": "EnvironmentResponseDtoType | null"
},
"apiKeys": {
  "description": "List of API keys associated with the environment",
  "type": "ApiKeyDto[]"
},
"parentId": {
  "description": "Parent environment ID",
  "type": "string"
},
"slug": {
  "description": "URL-friendly slug for the environment",
  "type": "string"
}
}}
/>


# List all environments (/api-reference/environments/list-all-environments)

This API returns a list of environments for the current organization. 
    Each environment contains its configuration, API keys (if user has access), and metadata.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environments","method":"get"}]} webhooks={[]} hasHead={false} />


# List environment tags (/api-reference/environments/list-environment-tags)

Retrieve all unique tags used in workflows within the specified environment. These tags can be used for filtering workflows.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/environments/{environmentId}/tags","method":"get"}]} webhooks={[]} hasHead={false} />


# Publish resources to target environment (/api-reference/environments/publish-resources-to-target-environment)

Publishes all workflows and resources from the source environment to the target environment. Optionally specify specific resources to publish or use dryRun mode to preview changes.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/environments/{targetEnvironmentId}/publish","method":"post"}]} webhooks={[]} hasHead={false} />


# Update an environment (/api-reference/environments/update-an-environment)

Update an environment by its unique identifier **environmentId**. 
    You can modify the environment name, identifier, color, and other configuration settings.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/environments/{environmentId}","method":"put"}]} webhooks={[]} hasHead={false} />


# Broadcast event to all (/api-reference/events/broadcast-event-to-all)

Trigger a broadcast event to all existing subscribers, could be used to send announcements, etc.
      In the future could be used to trigger events to a subset of subscribers based on defined filters.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/events/trigger/broadcast","method":"post"}]} webhooks={[]} hasHead={false} />


# Bulk trigger event (/api-reference/events/bulk-trigger-event)

Using this endpoint you can trigger multiple events at once, to avoid multiple calls to the API.
The bulk API is limited to 100 events per request.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/events/trigger/bulk","method":"post"}]} webhooks={[]} hasHead={false} />


# Cancel triggered event (/api-reference/events/cancel-triggered-event)

Using a previously generated transactionId during the event trigger,
 will cancel any active or pending workflows. This is useful to cancel active digests, delays etc...

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/events/trigger/{transactionId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Trigger event (/api-reference/events/trigger-event)

Trigger event is the main (and only) way to send notifications to subscribers. The trigger identifier is used to match the particular workflow associated with it. Maximum number of recipients can be 100. Additional information can be passed according the body interface below.
To prevent duplicate triggers, you can optionally pass a **transactionId** in the request body. If the same **transactionId** is used again, the trigger will be ignored. The retention period depends on your billing tier.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/events/trigger","method":"post"}]} webhooks={[]} hasHead={false} />


# Auto-configure an integration for inbound webhooks (/api-reference/integrations/auto-configure-an-integration-for-inbound-webhooks)

Auto-configure an integration by its unique key identifier **integrationId** for inbound webhook support. 
    This will automatically generate required webhook signing keys and configure webhook endpoints.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/{integrationId}/auto-configure","method":"post"}]} webhooks={[]} hasHead={false} />


# Create an integration (/api-reference/integrations/create-an-integration)

Create an integration for the current environment the user is based on the API key provided. 
    Each provider supports different credentials, check the provider documentation for more details.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete an integration (/api-reference/integrations/delete-an-integration)

Delete an integration by its unique key identifier **integrationId**. 
    This action is irreversible.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/{integrationId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Generate chat OAuth URL (/api-reference/integrations/generate-chat-oauth-url)

Generate an OAuth URL for chat integrations like Slack and MS Teams. 
    This URL allows subscribers to authorize the integration, enabling the system to send messages 
    through their chat workspace. The generated URL expires after 5 minutes.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/chat/oauth","method":"post"}]} webhooks={[]} hasHead={false} />


# Integration schema Model API Reference (Integrations) (/api-reference/integrations/integration-schema)

Reference the Novu integration schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Integration

Integration is third party service used by Novu to send notification for a specific channel. For example, [sengrid](/platform/integrations/email/sendgrid) is a email integration and [twilio](/platform/integrations/sms/twilio) is a sms integration. Read more about integrations on [integrations concept page](/platform/concepts/integrations).

<TypeTable
  name="Integration"
  type={{
"id": {
  "description": "The unique identifier of the integration record in the database. This is automatically generated.",
  "type": "string"
},
"environmentId": {
  "description": "The unique identifier for the environment associated with this integration. This links to the Environment collection.",
  "type": "string"
},
"organizationId": {
  "description": "The unique identifier for the organization that owns this integration. This links to the Organization collection.",
  "type": "string"
},
"name": {
  "description": "The name of the integration, which is used to identify it in the user interface.",
  "type": "string"
},
"identifier": {
  "description": "A unique string identifier for the integration, often used for API calls or internal references.",
  "type": "string"
},
"providerId": {
  "description": "The identifier for the provider of the integration (e.g., \"mailgun\", \"twilio\").",
  "type": "string"
},
"channel": {
  "description": "The channel type for the integration, which defines how it communicates (e.g., email, SMS).",
  "type": "IntegrationResponseDtoChannel"
},
"credentials": {
  "description": "The credentials required for the integration to function, including API keys and other sensitive information.",
  "type": "CredentialsDto"
},
"configurations": {
  "description": "The configurations required for enabling the additional configurations of the integration.",
  "type": "ConfigurationsDto"
},
"active": {
  "description": "Indicates whether the integration is currently active. An active integration will process events and messages.",
  "type": "boolean"
},
"deleted": {
  "description": "Indicates whether the integration has been marked as deleted (soft delete).",
  "type": "boolean"
},
"deletedAt": {
  "description": "The timestamp indicating when the integration was deleted. This is set when the integration is soft deleted.",
  "type": "string"
},
"deletedBy": {
  "description": "The identifier of the user who performed the deletion of this integration. Useful for audit trails.",
  "type": "string"
},
"primary": {
  "description": "Indicates whether this integration is marked as primary. A primary integration is often the default choice for processing.",
  "type": "boolean"
},
"conditions": {
  "description": "An array of conditions associated with the integration that may influence its behavior or processing logic.",
  "type": "StepFilterDto[]"
}
}}
/>

### Credentials

Each integration has a set of credentials that are used to authenticate with the third party service. Checkout the provider documentation for more details on what credentials are required for each integration.

<TypeTable
  name="Credentials"
  type={{
"apiKey": {
  "description": "",
  "type": "string"
},
"user": {
  "description": "",
  "type": "string"
},
"secretKey": {
  "description": "",
  "type": "string"
},
"domain": {
  "description": "",
  "type": "string"
},
"password": {
  "description": "",
  "type": "string"
},
"host": {
  "description": "",
  "type": "string"
},
"port": {
  "description": "",
  "type": "string"
},
"secure": {
  "description": "",
  "type": "boolean"
},
"region": {
  "description": "",
  "type": "string"
},
"accountSid": {
  "description": "",
  "type": "string"
},
"messageProfileId": {
  "description": "",
  "type": "string"
},
"token": {
  "description": "",
  "type": "string"
},
"from": {
  "description": "",
  "type": "string"
},
"senderName": {
  "description": "",
  "type": "string"
},
"projectName": {
  "description": "",
  "type": "string"
},
"applicationId": {
  "description": "",
  "type": "string"
},
"clientId": {
  "description": "",
  "type": "string"
},
"requireTls": {
  "description": "",
  "type": "boolean"
},
"ignoreTls": {
  "description": "",
  "type": "boolean"
},
"tlsOptions": {
  "description": "",
  "type": "TlsOptions"
},
"baseUrl": {
  "description": "",
  "type": "string"
},
"webhookUrl": {
  "description": "",
  "type": "string"
},
"redirectUrl": {
  "description": "",
  "type": "string"
},
"hmac": {
  "description": "",
  "type": "boolean"
},
"serviceAccount": {
  "description": "",
  "type": "string"
},
"ipPoolName": {
  "description": "",
  "type": "string"
},
"apiKeyRequestHeader": {
  "description": "",
  "type": "string"
},
"secretKeyRequestHeader": {
  "description": "",
  "type": "string"
},
"idPath": {
  "description": "",
  "type": "string"
},
"datePath": {
  "description": "",
  "type": "string"
},
"apiToken": {
  "description": "",
  "type": "string"
},
"authenticateByToken": {
  "description": "",
  "type": "boolean"
},
"authenticationTokenKey": {
  "description": "",
  "type": "string"
},
"instanceId": {
  "description": "",
  "type": "string"
},
"alertUid": {
  "description": "",
  "type": "string"
},
"title": {
  "description": "",
  "type": "string"
},
"imageUrl": {
  "description": "",
  "type": "string"
},
"state": {
  "description": "",
  "type": "string"
},
"externalLink": {
  "description": "",
  "type": "string"
},
"channelId": {
  "description": "",
  "type": "string"
},
"phoneNumberIdentification": {
  "description": "",
  "type": "string"
},
"accessKey": {
  "description": "",
  "type": "string"
},
"appSid": {
  "description": "",
  "type": "string"
},
"senderId": {
  "description": "",
  "type": "string"
},
"tenantId": {
  "description": "",
  "type": "string"
},
"appIOBaseUrl": {
  "description": "",
  "type": "string"
}
}}
/>

### ChannelTypeEnum

ChannelTypeEnum is used to specify the type of channel that the integration is used for. For example, if the integration is used for email, the channel type will be `email`.

```typescript
ChannelTypeEnum {
  IN_APP = "in_app",
  EMAIL = "email",
  SMS = "sms",
  CHAT = "chat",
  PUSH = "push"
}
```


# List active integrations (/api-reference/integrations/list-active-integrations)

List all the active integrations created in the organization

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/active","method":"get"}]} webhooks={[]} hasHead={false} />


# List all integrations (/api-reference/integrations/list-all-integrations)

List all the channels integrations created in the organization

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations","method":"get"}]} webhooks={[]} hasHead={false} />


# Update an integration (/api-reference/integrations/update-an-integration)

Update an integration by its unique key identifier **integrationId**. 
    Each provider supports different credentials, check the provider documentation for more details.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/{integrationId}","method":"put"}]} webhooks={[]} hasHead={false} />


# Update integration as primary (/api-reference/integrations/update-integration-as-primary)

Update an integration as **primary** by its unique key identifier **integrationId**. 
    This API will set the integration as primary for that channel in the current environment. 
    Primary integration is used to deliver notification for sms and email channels in the workflow.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/integrations/{integrationId}/set-primary","method":"post"}]} webhooks={[]} hasHead={false} />


# Create a layout (/api-reference/layouts/create-a-layout)

Creates a new layout in the Novu Cloud environment

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a layout (/api-reference/layouts/delete-a-layout)

Removes a specific layout by its unique identifier **layoutId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Duplicate a layout (/api-reference/layouts/duplicate-a-layout)

Duplicates a layout by its unique identifier **layoutId**. This will create a new layout with the content of the original layout.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}/duplicate","method":"post"}]} webhooks={[]} hasHead={false} />


# Generate layout preview (/api-reference/layouts/generate-layout-preview)

Generates a preview for a layout by its unique identifier **layoutId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}/preview","method":"post"}]} webhooks={[]} hasHead={false} />


# Get layout usage (/api-reference/layouts/get-layout-usage)

Retrieves information about workflows that use the specified layout by its unique identifier **layoutId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}/usage","method":"get"}]} webhooks={[]} hasHead={false} />


# List all layouts (/api-reference/layouts/list-all-layouts)

Retrieves a list of layouts with optional filtering and pagination

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a layout (/api-reference/layouts/retrieve-a-layout)

Fetches details of a specific layout by its unique identifier **layoutId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Update a layout (/api-reference/layouts/update-a-layout)

Updates the details of an existing layout, here **layoutId** is the identifier of the layout

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/layouts/{layoutId}","method":"put"}]} webhooks={[]} hasHead={false} />


# Delete a message (/api-reference/messages/delete-a-message)

Delete a message entity from the Novu platform by **messageId**. 
    This action is irreversible. **messageId** is required and of mongodbId type.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/messages/{messageId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Delete messages by transactionId (/api-reference/messages/delete-messages-by-transactionid)

Delete multiple messages from the Novu platform using **transactionId** of triggered event. 
    This API supports filtering by **channel** and delete all messages associated with the **transactionId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/messages/transaction/{transactionId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# List all messages (/api-reference/messages/list-all-messages)

List all messages for the current environment. 
    This API supports filtering by **channel**, **subscriberId**, and **transactionId**. 
    This API returns a paginated list of messages.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/messages","method":"get"}]} webhooks={[]} hasHead={false} />


# Message schema Model API Reference (Messages) (/api-reference/messages/message-schema)

Reference the Novu message schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Message

Message is a single notification that is sent to a subscriber. Each channel step in the workflow generates a message.

<TypeTable
  name="Message"
  type={{
"id": {
  "description": "Unique identifier for the message",
  "type": "string"
},
"templateId": {
  "description": "Template ID associated with the message",
  "type": "string | null"
},
"environmentId": {
  "description": "Environment ID where the message is sent",
  "type": "string"
},
"messageTemplateId": {
  "description": "Message template ID",
  "type": "string | null"
},
"organizationId": {
  "description": "Organization ID associated with the message",
  "type": "string"
},
"notificationId": {
  "description": "Notification ID associated with the message",
  "type": "string"
},
"subscriberId": {
  "description": "Subscriber ID associated with the message",
  "type": "string"
},
"subscriber": {
  "description": "Subscriber details, if available",
  "type": "SubscriberResponseDto"
},
"template": {
  "description": "Workflow template associated with the message",
  "type": "WorkflowResponse"
},
"templateIdentifier": {
  "description": "Identifier for the message template",
  "type": "string"
},
"createdAt": {
  "description": "Creation date of the message",
  "type": "string"
},
"deliveredAt": {
  "description": "Array of delivery dates for the message, if the message has multiple delivery dates, for example after being snoozed",
  "type": "string[]"
},
"lastSeenDate": {
  "description": "Last seen date of the message, if available",
  "type": "string"
},
"lastReadDate": {
  "description": "Last read date of the message, if available",
  "type": "string"
},
"content": {
  "description": "Content of the message, can be an email block or a string",
  "type": "string | EmailBlock[] | null"
},
"transactionId": {
  "description": "Transaction ID associated with the message",
  "type": "string"
},
"subject": {
  "description": "Subject of the message, if applicable",
  "type": "string"
},
"channel": {
  "description": "Channel type through which the message is sent",
  "type": "ChannelTypeEnum"
},
"read": {
  "description": "Indicates if the message has been read",
  "type": "boolean"
},
"seen": {
  "description": "Indicates if the message has been seen",
  "type": "boolean"
},
"snoozedUntil": {
  "description": "Date when the message will be unsnoozed",
  "type": "string"
},
"email": {
  "description": "Email address associated with the message, if applicable",
  "type": "string"
},
"phone": {
  "description": "Phone number associated with the message, if applicable",
  "type": "string"
},
"directWebhookUrl": {
  "description": "Direct webhook URL for the message, if applicable",
  "type": "string"
},
"providerId": {
  "description": "Provider ID associated with the message, if applicable",
  "type": "string"
},
"deviceTokens": {
  "description": "Device tokens associated with the message, if applicable",
  "type": "string[]"
},
"title": {
  "description": "Title of the message, if applicable",
  "type": "string"
},
"cta": {
  "description": "Call to action associated with the message",
  "type": "MessageCTA"
},
"feedId": {
  "description": "Feed ID associated with the message, if applicable",
  "type": "string | null"
},
"status": {
  "description": "Status of the message",
  "type": "MessageStatusEnum"
},
"errorId": {
  "description": "Error ID if the message has an error",
  "type": "string"
},
"errorText": {
  "description": "Error text if the message has an error",
  "type": "string"
},
"payload": {
  "description": "The payload that was used to send the notification trigger",
  "type": "{ [k: string]: any; }"
},
"overrides": {
  "description": "Provider specific overrides used when triggering the notification",
  "type": "{ [k: string]: any; }"
},
"contextKeys": {
  "description": "Context (single or multi) in which the message was sent",
  "type": "string[]"
}
}}
/>

### ChannelTypeEnum

```typescript
ChannelTypeEnum {
  IN_APP = "in_app",
  EMAIL = "email",
  SMS = "sms",
  CHAT = "chat",
  PUSH = "push"
}
```

### Workflow

Workflow is a collection of steps that are executed in order to send a notification.

<TypeTable
  name="Workflow"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"name": {
  "description": "",
  "type": "string"
},
"description": {
  "description": "",
  "type": "string"
},
"active": {
  "description": "",
  "type": "boolean"
},
"draft": {
  "description": "",
  "type": "boolean"
},
"preferenceSettings": {
  "description": "",
  "type": "SubscriberPreferenceChannels"
},
"critical": {
  "description": "",
  "type": "boolean"
},
"tags": {
  "description": "",
  "type": "string[]"
},
"steps": {
  "description": "",
  "type": "NotificationStepDto[]"
},
"organizationId": {
  "description": "",
  "type": "string"
},
"creatorId": {
  "description": "",
  "type": "string"
},
"environmentId": {
  "description": "",
  "type": "string"
},
"triggers": {
  "description": "",
  "type": "NotificationTrigger[]"
},
"notificationGroupId": {
  "description": "",
  "type": "string"
},
"parentId": {
  "description": "",
  "type": "string"
},
"deleted": {
  "description": "",
  "type": "boolean"
},
"deletedAt": {
  "description": "",
  "type": "string"
},
"deletedBy": {
  "description": "",
  "type": "string"
},
"notificationGroup": {
  "description": "",
  "type": "NotificationGroup"
},
"data": {
  "description": "",
  "type": "WorkflowResponseData"
},
"workflowIntegrationStatus": {
  "description": "",
  "type": "WorkflowIntegrationStatus"
}
}}
/>

### Actor

Actor is the user who is skipped from sending the notification when workflow is triggered to a [topic](/platform/concepts/topics).

<TypeTable
  name="Actor"
  type={{
"toString": {
  "description": "",
  "type": "(() => string) | (() => string)"
},
"valueOf": {
  "description": "",
  "type": "(() => string) | (() => Object)"
}
}}
/>

### MessageCTA

MessageCTA is a call to action that is displayed in the [Inbox](/platform/inbox) message. It can be used to redirect the user to a specific URL when the message is clicked.

<TypeTable
  name="MessageCTA"
  type={{
"type": {
  "description": "Type of call to action",
  "type": "\"redirect\""
},
"data": {
  "description": "Data associated with the call to action",
  "type": "MessageCTAData"
},
"action": {
  "description": "Action associated with the call to action",
  "type": "MessageAction"
}
}}
/>


# List all events (/api-reference/notifications/list-all-events)

List all notification events (triggered events) for the current environment. 
    This API supports filtering by **channels**, **templates**, **emails**, **subscriberIds**, **transactionId**, **topicKey**, **severity**, **contextKeys**. 
    Checkout all available filters in the query section.
    This API returns event triggers, to list each channel notifications, check messages APIs.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/notifications","method":"get"}]} webhooks={[]} hasHead={false} />


# Notification event schema Model API Reference (Notifications) (/api-reference/notifications/notification-event-schema)

Reference the Novu notification event schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Notification event

Notification event is the event that is generated when a workflow is triggered to subscribers. It contains workflow details, subscriber details payload sent during trigger, execution details of each step in the workflow and the result of the execution of each step.

<TypeTable
  name="Notification"
  type={{
"id": {
  "description": "Unique identifier of the notification",
  "type": "string"
},
"environmentId": {
  "description": "Environment ID of the notification",
  "type": "string"
},
"organizationId": {
  "description": "Organization ID of the notification",
  "type": "string"
},
"subscriberId": {
  "description": "Subscriber ID of the notification",
  "type": "string"
},
"transactionId": {
  "description": "Transaction ID of the notification",
  "type": "string"
},
"templateId": {
  "description": "Template ID of the notification",
  "type": "string"
},
"digestedNotificationId": {
  "description": "Digested Notification ID",
  "type": "string"
},
"createdAt": {
  "description": "Creation time of the notification",
  "type": "string"
},
"updatedAt": {
  "description": "Last updated time of the notification",
  "type": "string"
},
"channels": {
  "description": "",
  "type": "string[]"
},
"subscriber": {
  "description": "Subscriber of the notification",
  "type": "ActivityNotificationSubscriberResponseDto"
},
"template": {
  "description": "Template of the notification",
  "type": "ActivityNotificationTemplateResponseDto"
},
"jobs": {
  "description": "Jobs of the notification",
  "type": "ActivityNotificationJobResponseDto[]"
},
"payload": {
  "description": "Payload of the notification",
  "type": "{ [k: string]: any; }"
},
"tags": {
  "description": "Tags associated with the notification",
  "type": "string[]"
},
"controls": {
  "description": "Controls associated with the notification",
  "type": "{ [k: string]: any; }"
},
"to": {
  "description": "To field for subscriber definition",
  "type": "{ [k: string]: any; }"
},
"topics": {
  "description": "Topics of the notification",
  "type": "ActivityTopicDto[]"
},
"severity": {
  "description": "Severity of the workflow",
  "type": "SeverityLevelEnum"
},
"critical": {
  "description": "Criticality of the notification",
  "type": "boolean"
},
"contextKeys": {
  "description": "Context (single or multi) in which the notification was sent",
  "type": "string[]"
}
}}
/>

### Workflow

Workflow contains the details of the workflow that was triggered.

<TypeTable
  name="Workflow"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"name": {
  "description": "",
  "type": "string"
},
"description": {
  "description": "",
  "type": "string"
},
"active": {
  "description": "",
  "type": "boolean"
},
"draft": {
  "description": "",
  "type": "boolean"
},
"preferenceSettings": {
  "description": "",
  "type": "SubscriberPreferenceChannels"
},
"critical": {
  "description": "",
  "type": "boolean"
},
"tags": {
  "description": "",
  "type": "string[]"
},
"steps": {
  "description": "",
  "type": "NotificationStepDto[]"
},
"organizationId": {
  "description": "",
  "type": "string"
},
"creatorId": {
  "description": "",
  "type": "string"
},
"environmentId": {
  "description": "",
  "type": "string"
},
"triggers": {
  "description": "",
  "type": "NotificationTrigger[]"
},
"notificationGroupId": {
  "description": "",
  "type": "string"
},
"parentId": {
  "description": "",
  "type": "string"
},
"deleted": {
  "description": "",
  "type": "boolean"
},
"deletedAt": {
  "description": "",
  "type": "string"
},
"deletedBy": {
  "description": "",
  "type": "string"
},
"notificationGroup": {
  "description": "",
  "type": "NotificationGroup"
},
"data": {
  "description": "",
  "type": "WorkflowResponseData"
},
"workflowIntegrationStatus": {
  "description": "",
  "type": "WorkflowIntegrationStatus"
}
}}
/>

### ChannelTypeEnum

ChannelTypeEnum is the type of the channel that the notification was sent to.

```typescript
ChannelTypeEnum {
  IN_APP = "in_app",
  EMAIL = "email",
  SMS = "sms",
  CHAT = "chat",
  PUSH = "push"
}
```


# Retrieve an event (/api-reference/notifications/retrieve-an-event)

Retrieve an event by its unique key identifier **notificationId**. 
    Here **notificationId** is of mongodbId type. 
    This API returns the event details - execution logs, status, actual notification (message) generated by each workflow step.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/notifications/{notificationId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Archive a notification (/api-reference/subscribers/archive-a-notification)

Archive a specific in-app (inbox) notification by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/archive","method":"patch"}]} webhooks={[]} hasHead={false} />


# Archive all notifications (/api-reference/subscribers/archive-all-notifications)

Archive all in-app (inbox) notifications matching the specified filters. Supports context-based filtering.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/archive","method":"post"}]} webhooks={[]} hasHead={false} />


# Archive all read notifications (/api-reference/subscribers/archive-all-read-notifications)

Archive all read in-app (inbox) notifications matching the specified filters. Supports context-based filtering.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/read-archive","method":"post"}]} webhooks={[]} hasHead={false} />


# Bulk create subscribers (/api-reference/subscribers/bulk-create-subscribers)

Using this endpoint multiple subscribers can be created at once. The bulk API is limited to 500 subscribers per request.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/bulk","method":"post"}]} webhooks={[]} hasHead={false} />


# Bulk update subscriber preferences (/api-reference/subscribers/bulk-update-subscriber-preferences)

Bulk update subscriber preferences by its unique key identifier **subscriberId**. 
    This API allows updating multiple workflow preferences in a single request.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/preferences/bulk","method":"patch"}]} webhooks={[]} hasHead={false} />


# Complete a notification action (/api-reference/subscribers/complete-a-notification-action)

Mark a single in-app (inbox) notification's action (primary or secondary) as completed by its unique identifier **notificationId** and action type **actionType**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/actions/{actionType}/complete","method":"patch"}]} webhooks={[]} hasHead={false} />


# Create a subscriber (/api-reference/subscribers/create-a-subscriber)

Create a subscriber with the subscriber attributes. 
      **subscriberId** is a required field, rest other fields are optional, if the subscriber already exists, it will be updated

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a notification (/api-reference/subscribers/delete-a-notification)

Delete a specific in-app (inbox) notification permanently by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Delete a subscriber (/api-reference/subscribers/delete-a-subscriber)

Deletes a subscriber entity from the Novu platform along with associated messages, preferences, and topic subscriptions. 
      **subscriberId** is a required field.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Delete all notifications (/api-reference/subscribers/delete-all-notifications)

Permanently delete all in-app (inbox) notifications matching the specified filters. Supports context-based filtering.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/delete","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete provider credentials (/api-reference/subscribers/delete-provider-credentials)

Delete subscriber credentials for a provider such as **slack** and **FCM** by **providerId**. 
    This action is irreversible and will remove the credentials for the provider for particular **subscriberId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials/{providerId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Mark a notification as read (/api-reference/subscribers/mark-a-notification-as-read)

Mark a specific in-app (inbox) notification as read by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/read","method":"patch"}]} webhooks={[]} hasHead={false} />


# Mark a notification as unread (/api-reference/subscribers/mark-a-notification-as-unread)

Mark a specific in-app (inbox) notification as unread by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/unread","method":"patch"}]} webhooks={[]} hasHead={false} />


# Mark all notifications as read (/api-reference/subscribers/mark-all-notifications-as-read)

Mark all in-app (inbox) notifications matching the specified filters as read. Supports context-based filtering.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/read","method":"post"}]} webhooks={[]} hasHead={false} />


# Mark notifications as seen (/api-reference/subscribers/mark-notifications-as-seen)

Mark specific and multiple in-app (inbox) notifications as seen. Supports context-based filtering.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/seen","method":"post"}]} webhooks={[]} hasHead={false} />


# Retrieve a subscriber (/api-reference/subscribers/retrieve-a-subscriber)

Retrieve a subscriber by its unique key identifier **subscriberId**. 
    **subscriberId** field is required.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve subscriber notifications count (/api-reference/subscribers/retrieve-subscriber-notifications-count)

Retrieve count of in-app (inbox) notifications for a subscriber by its unique key identifier **subscriberId**. 
    Supports multiple filters to count in-app (inbox) notifications by different criteria, including context keys.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/count","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve subscriber notifications (/api-reference/subscribers/retrieve-subscriber-notifications)

Retrieve subscriber in-app (inbox) notifications by its unique key identifier **subscriberId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/notifications/feed","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve subscriber preferences (/api-reference/subscribers/retrieve-subscriber-preferences)

Retrieve subscriber channel preferences by its unique key identifier **subscriberId**. 
    This API returns all five channels preferences for all workflows and global preferences.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/preferences","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve subscriber subscriptions (/api-reference/subscribers/retrieve-subscriber-subscriptions)

Retrieve subscriber's topic subscriptions by its unique key identifier **subscriberId**. 
    Checkout all available filters in the query section.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/subscriptions","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve unseen notifications count (/api-reference/subscribers/retrieve-unseen-notifications-count)

Retrieve unseen in-app (inbox) notifications count for a subscriber by its unique key identifier **subscriberId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/notifications/unseen","method":"get"}]} webhooks={[]} hasHead={false} />


# Revert a notification action (/api-reference/subscribers/revert-a-notification-action)

Revert a single in-app (inbox) notification's action (primary or secondary) to pending state by its unique identifier **notificationId** and action type **actionType**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/actions/{actionType}/revert","method":"patch"}]} webhooks={[]} hasHead={false} />


# Search subscribers (/api-reference/subscribers/search-subscribers)

Search subscribers by their **email**, **phone**, **subscriberId** and **name**. 
    The search is case sensitive and supports pagination.Checkout all available filters in the query section.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers","method":"get"}]} webhooks={[]} hasHead={false} />


# Snooze a notification (/api-reference/subscribers/snooze-a-notification)

Snooze a specific in-app (inbox) notification by its unique identifier **notificationId** until a specified time.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/snooze","method":"patch"}]} webhooks={[]} hasHead={false} />


# Subscriber schema Model API Reference (Subscribers) (/api-reference/subscribers/subscriber-schema)

Reference the Novu subscriber schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Subscriber

Subscriber is the end user that receives notifications. Subscriber has subscriber attributes like firstName, lastName, email, phone, etc, `data` field to store any custom attributes in key value pairs and channel credentials for push and chat channel provider's integrations. Read more about subscribers on [subscribers concept page](/platform/concepts/subscribers).

<TypeTable
  name="Subscriber"
  type={{
"id": {
  "description": "The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.",
  "type": "string"
},
"firstName": {
  "description": "The first name of the subscriber.",
  "type": "string | null"
},
"lastName": {
  "description": "The last name of the subscriber.",
  "type": "string | null"
},
"email": {
  "description": "The email address of the subscriber.",
  "type": "string | null"
},
"phone": {
  "description": "The phone number of the subscriber.",
  "type": "string | null"
},
"avatar": {
  "description": "The URL of the subscriber's avatar image.",
  "type": "string | null"
},
"locale": {
  "description": "The locale setting of the subscriber, indicating their preferred language or region.",
  "type": "string | null"
},
"channels": {
  "description": "An array of channel settings associated with the subscriber.",
  "type": "ChannelSettingsDto[]"
},
"topics": {
  "description": "An array of topics that the subscriber is subscribed to.",
  "type": "string[]"
},
"isOnline": {
  "description": "Indicates whether the subscriber is currently online.",
  "type": "boolean | null"
},
"lastOnlineAt": {
  "description": "The timestamp indicating when the subscriber was last online, in ISO 8601 format.",
  "type": "string | null"
},
"v": {
  "description": "The version of the subscriber document.",
  "type": "number"
},
"data": {
  "description": "Additional custom data for the subscriber",
  "type": "{ [k: string]: any; } | null"
},
"timezone": {
  "description": "Timezone of the subscriber",
  "type": "string | null"
},
"subscriberId": {
  "description": "The identifier used to create this subscriber, which typically corresponds to the user ID in your system.",
  "type": "string"
},
"organizationId": {
  "description": "The unique identifier of the organization to which the subscriber belongs.",
  "type": "string"
},
"environmentId": {
  "description": "The unique identifier of the environment associated with this subscriber.",
  "type": "string"
},
"deleted": {
  "description": "Indicates whether the subscriber has been deleted.",
  "type": "boolean"
},
"createdAt": {
  "description": "The timestamp indicating when the subscriber was created, in ISO 8601 format.",
  "type": "string"
},
"updatedAt": {
  "description": "The timestamp indicating when the subscriber was last updated, in ISO 8601 format.",
  "type": "string"
}
}}
/>

### ChannelSettingsDto

ChannelSettings are credentials for push and chat channel provider's integrations. One subscriber can have credentials for multiple integrations of same provider of one channel type

<TypeTable
  name="ChannelSettings"
  type={{
"providerId": {
  "description": "The provider identifier for the credentials",
  "type": "ChatOrPushProviderEnum"
},
"integrationIdentifier": {
  "description": "The integration identifier",
  "type": "string"
},
"credentials": {
  "description": "Credentials payload for the specified provider",
  "type": "ChannelCredentials"
},
"integrationId": {
  "description": "The unique identifier of the integration associated with this channel.",
  "type": "string"
}
}}
/>

### Credentials

Credentials like deviceTokens, webhookUrl, etc for a specific integration. `providerId` could be chat channel providerId or push channel providerId.

<TypeTable
  name="Credentials"
  type={{
"apiKey": {
  "description": "",
  "type": "string"
},
"user": {
  "description": "",
  "type": "string"
},
"secretKey": {
  "description": "",
  "type": "string"
},
"domain": {
  "description": "",
  "type": "string"
},
"password": {
  "description": "",
  "type": "string"
},
"host": {
  "description": "",
  "type": "string"
},
"port": {
  "description": "",
  "type": "string"
},
"secure": {
  "description": "",
  "type": "boolean"
},
"region": {
  "description": "",
  "type": "string"
},
"accountSid": {
  "description": "",
  "type": "string"
},
"messageProfileId": {
  "description": "",
  "type": "string"
},
"token": {
  "description": "",
  "type": "string"
},
"from": {
  "description": "",
  "type": "string"
},
"senderName": {
  "description": "",
  "type": "string"
},
"projectName": {
  "description": "",
  "type": "string"
},
"applicationId": {
  "description": "",
  "type": "string"
},
"clientId": {
  "description": "",
  "type": "string"
},
"requireTls": {
  "description": "",
  "type": "boolean"
},
"ignoreTls": {
  "description": "",
  "type": "boolean"
},
"tlsOptions": {
  "description": "",
  "type": "TlsOptions"
},
"baseUrl": {
  "description": "",
  "type": "string"
},
"webhookUrl": {
  "description": "",
  "type": "string"
},
"redirectUrl": {
  "description": "",
  "type": "string"
},
"hmac": {
  "description": "",
  "type": "boolean"
},
"serviceAccount": {
  "description": "",
  "type": "string"
},
"ipPoolName": {
  "description": "",
  "type": "string"
},
"apiKeyRequestHeader": {
  "description": "",
  "type": "string"
},
"secretKeyRequestHeader": {
  "description": "",
  "type": "string"
},
"idPath": {
  "description": "",
  "type": "string"
},
"datePath": {
  "description": "",
  "type": "string"
},
"apiToken": {
  "description": "",
  "type": "string"
},
"authenticateByToken": {
  "description": "",
  "type": "boolean"
},
"authenticationTokenKey": {
  "description": "",
  "type": "string"
},
"instanceId": {
  "description": "",
  "type": "string"
},
"alertUid": {
  "description": "",
  "type": "string"
},
"title": {
  "description": "",
  "type": "string"
},
"imageUrl": {
  "description": "",
  "type": "string"
},
"state": {
  "description": "",
  "type": "string"
},
"externalLink": {
  "description": "",
  "type": "string"
},
"channelId": {
  "description": "",
  "type": "string"
},
"phoneNumberIdentification": {
  "description": "",
  "type": "string"
},
"accessKey": {
  "description": "",
  "type": "string"
},
"appSid": {
  "description": "",
  "type": "string"
},
"senderId": {
  "description": "",
  "type": "string"
},
"tenantId": {
  "description": "",
  "type": "string"
},
"appIOBaseUrl": {
  "description": "",
  "type": "string"
}
}}
/>


# Unarchive a notification (/api-reference/subscribers/unarchive-a-notification)

Unarchive a specific in-app (inbox) notification by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/unarchive","method":"patch"}]} webhooks={[]} hasHead={false} />


# Unsnooze a notification (/api-reference/subscribers/unsnooze-a-notification)

Unsnooze a specific in-app (inbox) notification by its unique identifier **notificationId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/notifications/{notificationId}/unsnooze","method":"patch"}]} webhooks={[]} hasHead={false} />


# Update a subscriber (/api-reference/subscribers/update-a-subscriber)

Update a subscriber by its unique key identifier **subscriberId**. 
    **subscriberId** is a required field, rest other fields are optional

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Update all notifications state (/api-reference/subscribers/update-all-notifications-state)

Update all subscriber in-app (inbox) notifications state such as read, unread, seen or unseen by **subscriberId**.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/mark-all","method":"post"}]} webhooks={[]} hasHead={false} />


# Update notification action status (/api-reference/subscribers/update-notification-action-status)

Update in-app (inbox) notification's action status by its unique key identifier **messageId** and type field **type**. 
      **type** field can be **primary** or **secondary**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/{messageId}/actions/{type}","method":"post"}]} webhooks={[]} hasHead={false} />


# Update notifications state (/api-reference/subscribers/update-notifications-state)

Update subscriber's multiple in-app (inbox) notifications state such as seen, read, unseen or unread by **subscriberId**. 
      **messageId** is of type mongodbId of notifications

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/mark-as","method":"post"}]} webhooks={[]} hasHead={false} />


# Update provider credentials (/api-reference/subscribers/update-provider-credentials)

Update credentials for a provider such as **slack** and **FCM**. 
      **providerId** is required field. This API creates the **deviceTokens** or replaces the existing ones.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials","method":"put"}]} webhooks={[]} hasHead={false} />


# Update subscriber online status (/api-reference/subscribers/update-subscriber-online-status)

Update the subscriber online status by its unique key identifier **subscriberId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/online-status","method":"patch"}]} webhooks={[]} hasHead={false} />


# Update subscriber preferences (/api-reference/subscribers/update-subscriber-preferences)

Update subscriber preferences by its unique key identifier **subscriberId**. 
    **workflowId** is optional field, if provided, this API will update that workflow preference, 
    otherwise it will update global preferences

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/subscribers/{subscriberId}/preferences","method":"patch"}]} webhooks={[]} hasHead={false} />


# Upsert provider credentials (/api-reference/subscribers/upsert-provider-credentials)

Upsert credentials for a provider such as **slack** and **FCM**. 
      **providerId** is required field. This API creates **deviceTokens** or appends to the existing ones.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials","method":"patch"}]} webhooks={[]} hasHead={false} />


# Check topic subscriber (/api-reference/topics/check-topic-subscriber)

Check if a subscriber belongs to a certain topic

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v1/topics/{topicKey}/subscribers/{externalSubscriberId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Create a topic (/api-reference/topics/create-a-topic)

Creates a new topic if it does not exist, or updates an existing topic if it already exists. Use ?failIfExists=true to prevent updates.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics","method":"post"}]} webhooks={[]} hasHead={false} />


# Create topic subscriptions (/api-reference/topics/create-topic-subscriptions)

This api will create subscription for subscriberIds for a topic. 
      Its like subscribing to a common interest group. if topic does not exist, it will be created.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a topic (/api-reference/topics/delete-a-topic)

Delete a topic by its unique key identifier **topicKey**. 
    This action is irreversible and will remove all subscriptions to the topic.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Delete topic subscriptions (/api-reference/topics/delete-topic-subscriptions)

Delete subscriptions for subscriberIds for a topic.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"delete"}]} webhooks={[]} hasHead={false} />


# List all topics (/api-reference/topics/list-all-topics)

This api returns a paginated list of topics.
    Topics can be filtered by **key**, **name**, or **includeCursor** to paginate through the list. 
    Checkout all available filters in the query section.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics","method":"get"}]} webhooks={[]} hasHead={false} />


# List topic subscriptions (/api-reference/topics/list-topic-subscriptions)

List all subscriptions of subscribers for a topic.
    Checkout all available filters in the query section.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a topic subscription (/api-reference/topics/retrieve-a-topic-subscription)

Retrieve a subscription by its unique identifier for a topic.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions/{identifier}","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a topic (/api-reference/topics/retrieve-a-topic)

Retrieve a topic by its unique key identifier **topicKey**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}","method":"get"}]} webhooks={[]} hasHead={false} />


# Topic schema Model API Reference (Topics) (/api-reference/topics/topic-schema)

Reference the Novu topic schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Topic

Topic is a collection of subscribers that share a common interest. Subscriber can subscribe to multiple topics. When a subscriber is subscribed to a topic, they will receive notifications generated by workflows triggered to that topic.

<TypeTable
  name="Topic"
  type={{
"id": {
  "description": "The identifier of the topic",
  "type": "string"
},
"key": {
  "description": "The unique key of the topic",
  "type": "string"
},
"name": {
  "description": "The name of the topic",
  "type": "string"
},
"createdAt": {
  "description": "The date the topic was created",
  "type": "string"
},
"updatedAt": {
  "description": "The date the topic was last updated",
  "type": "string"
}
}}
/>

### TopicSubscription

TopicSubscription is a relationship between a subscriber and a topic. It is used to track which subscribers are subscribed to which topics and when they subscribed. `createdAt` is the date and time the subscription was created.

<TypeTable
  name="TopicSubscription"
  type={{
"id": {
  "description": "The identifier of the subscription",
  "type": "string"
},
"identifier": {
  "description": "The identifier of the subscription",
  "type": "string"
},
"createdAt": {
  "description": "The date and time the subscription was created",
  "type": "string"
},
"topic": {
  "description": "Topic information",
  "type": "TopicResponseDto"
},
"subscriber": {
  "description": "Subscriber information",
  "type": "SubscriberDto"
},
"contextKeys": {
  "description": "Context keys that scope this subscription (e.g., tenant:org-a, project:proj-123)",
  "type": "string[]"
}
}}
/>

### Subscriber

Subscriber is a user who can receive notifications. Read more about subscribers on [subscribers concept page](/platform/concepts/subscribers).

<TypeTable
  name="Subscriber"
  type={{
"id": {
  "description": "The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.",
  "type": "string"
},
"firstName": {
  "description": "The first name of the subscriber.",
  "type": "string | null"
},
"lastName": {
  "description": "The last name of the subscriber.",
  "type": "string | null"
},
"email": {
  "description": "The email address of the subscriber.",
  "type": "string | null"
},
"phone": {
  "description": "The phone number of the subscriber.",
  "type": "string | null"
},
"avatar": {
  "description": "The URL of the subscriber's avatar image.",
  "type": "string | null"
},
"locale": {
  "description": "The locale setting of the subscriber, indicating their preferred language or region.",
  "type": "string | null"
},
"channels": {
  "description": "An array of channel settings associated with the subscriber.",
  "type": "ChannelSettingsDto[]"
},
"topics": {
  "description": "An array of topics that the subscriber is subscribed to.",
  "type": "string[]"
},
"isOnline": {
  "description": "Indicates whether the subscriber is currently online.",
  "type": "boolean | null"
},
"lastOnlineAt": {
  "description": "The timestamp indicating when the subscriber was last online, in ISO 8601 format.",
  "type": "string | null"
},
"v": {
  "description": "The version of the subscriber document.",
  "type": "number"
},
"data": {
  "description": "Additional custom data for the subscriber",
  "type": "{ [k: string]: any; } | null"
},
"timezone": {
  "description": "Timezone of the subscriber",
  "type": "string | null"
},
"subscriberId": {
  "description": "The identifier used to create this subscriber, which typically corresponds to the user ID in your system.",
  "type": "string"
},
"organizationId": {
  "description": "The unique identifier of the organization to which the subscriber belongs.",
  "type": "string"
},
"environmentId": {
  "description": "The unique identifier of the environment associated with this subscriber.",
  "type": "string"
},
"deleted": {
  "description": "Indicates whether the subscriber has been deleted.",
  "type": "boolean"
},
"createdAt": {
  "description": "The timestamp indicating when the subscriber was created, in ISO 8601 format.",
  "type": "string"
},
"updatedAt": {
  "description": "The timestamp indicating when the subscriber was last updated, in ISO 8601 format.",
  "type": "string"
}
}}
/>


# Update a topic subscription (/api-reference/topics/update-a-topic-subscription)

Update a subscription by its unique identifier for a topic. You can update the preferences and name associated with the subscription.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions/{identifier}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Update a topic (/api-reference/topics/update-a-topic)

Update a topic name by its unique key identifier **topicKey**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/topics/{topicKey}","method":"patch"}]} webhooks={[]} hasHead={false} />


# Create a translation (/api-reference/translations/create-a-translation)

Create a translation for a specific workflow and locale, if the translation already exists, it will be updated

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a translation group (/api-reference/translations/delete-a-translation-group)

Delete an entire translation group and all its translations

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/{resourceType}/{resourceId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Delete a translation (/api-reference/translations/delete-a-translation)

Delete a specific translation by resource type, resource ID and locale

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/{resourceType}/{resourceId}/{locale}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Import master translations JSON (/api-reference/translations/import-master-translations-json)

Import translations for multiple workflows from master JSON format for a specific locale

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/master-json","method":"post"}]} webhooks={[]} hasHead={false} />


# Retrieve a translation group (/api-reference/translations/retrieve-a-translation-group)

Retrieves a single translation group by resource type (workflow, layout) and resource ID (workflowId, layoutId)

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/group/{resourceType}/{resourceId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a translation (/api-reference/translations/retrieve-a-translation)

Retrieve a specific translation by resource type, resource ID and locale

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/{resourceType}/{resourceId}/{locale}","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve master translations JSON (/api-reference/translations/retrieve-master-translations-json)

Retrieve all translations for a locale in master JSON format organized by resourceId (workflowId)

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/master-json","method":"get"}]} webhooks={[]} hasHead={false} />


# Upload master translations JSON file (/api-reference/translations/upload-master-translations-json-file)

Upload a master JSON file containing translations for multiple workflows. Locale is automatically detected from filename (e.g., en_US.json)

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/master-json/upload","method":"post"}]} webhooks={[]} hasHead={false} />


# Upload translation files (/api-reference/translations/upload-translation-files)

Upload one or more JSON translation files for a specific workflow. Files name must match the locale, e.g. en_US.json. Supports both "files" and "files[]" field names for backwards compatibility.

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/translations/upload","method":"post"}]} webhooks={[]} hasHead={false} />


# Create a workflow (/api-reference/workflows/create-a-workflow)

Creates a new workflow in the Novu Cloud environment

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows","method":"post"}]} webhooks={[]} hasHead={false} />


# Delete a workflow (/api-reference/workflows/delete-a-workflow)

Removes a specific workflow by its unique identifier **workflowId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}","method":"delete"}]} webhooks={[]} hasHead={false} />


# Generate a step preview (/api-reference/workflows/generate-a-step-preview)

Generates a preview for a specific workflow step by its unique identifier **stepId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}/step/{stepId}/preview","method":"post"}]} webhooks={[]} hasHead={false} />


# List all workflows (/api-reference/workflows/list-all-workflows)

Retrieves a list of workflows with optional filtering and pagination

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve a workflow (/api-reference/workflows/retrieve-a-workflow)

Fetches details of a specific workflow by its unique identifier **workflowId**

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Retrieve workflow step (/api-reference/workflows/retrieve-workflow-step)

Retrieves data for a specific step in a workflow

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}/steps/{stepId}","method":"get"}]} webhooks={[]} hasHead={false} />


# Sync a workflow (/api-reference/workflows/sync-a-workflow)

Synchronizes a workflow to the target environment

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}/sync","method":"put"}]} webhooks={[]} hasHead={false} />


# Update a workflow (/api-reference/workflows/update-a-workflow)

Updates the details of an existing workflow, here **workflowId** is the identifier of the workflow

{/* This file was generated by scripts\/generate-docs.mjs. Do not edit this file directly. Regenerate with pnpm run build:docs. */}

<APIPage document={"content/openapi/novu-spec.json"} operations={[{"path":"/v2/workflows/{workflowId}","method":"put"}]} webhooks={[]} hasHead={false} />


# Workflow schema Model API Reference (Workflows) (/api-reference/workflows/workflow-schema)

Reference the Novu workflow schema used in API requests and responses. Review fields, data types, and object structure for this resource.

### Workflow

In Novu, a workflow defines the logic for delivering notifications based on specific events. It consists of configurable steps that control timing, conditions, and which channels to use, such as email, SMS, or in-app messages. Workflows can be built visually in the dashboard or programmatically using the Novu Framework. Each workflow has a unique identifier, supports environment syncing, and provides real-time visibility through the Activity Feed for monitoring and debugging.. Read more about workflows on [workflows concept page](/platform/concepts/workflows).

<TypeTable
  name="Workflow"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"name": {
  "description": "",
  "type": "string"
},
"description": {
  "description": "",
  "type": "string"
},
"active": {
  "description": "",
  "type": "boolean"
},
"draft": {
  "description": "",
  "type": "boolean"
},
"preferenceSettings": {
  "description": "",
  "type": "SubscriberPreferenceChannels"
},
"critical": {
  "description": "",
  "type": "boolean"
},
"tags": {
  "description": "",
  "type": "string[]"
},
"steps": {
  "description": "",
  "type": "NotificationStepDto[]"
},
"organizationId": {
  "description": "",
  "type": "string"
},
"creatorId": {
  "description": "",
  "type": "string"
},
"environmentId": {
  "description": "",
  "type": "string"
},
"triggers": {
  "description": "",
  "type": "NotificationTrigger[]"
},
"notificationGroupId": {
  "description": "",
  "type": "string"
},
"parentId": {
  "description": "",
  "type": "string"
},
"deleted": {
  "description": "",
  "type": "boolean"
},
"deletedAt": {
  "description": "",
  "type": "string"
},
"deletedBy": {
  "description": "",
  "type": "string"
},
"notificationGroup": {
  "description": "",
  "type": "NotificationGroup"
},
"data": {
  "description": "",
  "type": "WorkflowResponseData"
},
"workflowIntegrationStatus": {
  "description": "",
  "type": "WorkflowIntegrationStatus"
}
}}
/>


# React Email Integration (/framework/content/react-email)

Learn how to use React Email to build beautiful email templates

React Email is a collection of high-quality, unstyled components for creating beautiful emails using React and TypeScript.
It's a great way to build email templates that are consistent with your brand and easy to maintain.

## Getting Started

<Steps>
  <Step title="Install React.Email components">
    ```bash
    npm install @react-email/components react-email
    ```
  </Step>

  <Step title="Write your email">
    ```tsx
    import {
        Body,
        Container,
        Head,
        Html,
        render,
    } from '@react-email/components';
    import * as React from "react";

    interface TestEmailProps {
        name: string
    }

    export const TestEmailTemplate = ({ name }: TestEmailProps) => {
        return (
            <Html>
                <Head />
                <Body>
                    <Container>
                        Hello {name} welcome to your first React E-mail template!
                    </Container>
                </Body>
            </Html>
        );
    };

    export default TestEmailTemplate;

    export function renderEmail(name: string) {
        return render(<TestEmailTemplate name={name} />);
    }
    ```
  </Step>

  <Step title="Write your workflow">
    ```tsx
    import { workflow } from '@novu/framework';
    import { renderEmail } from './emails/test-email';
    import { z } from 'zod';

    export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
        await step.email('send-email', async (controls) => {
            return {
                subject: controls.subject,
                body: renderEmail(payload.userName),
            };
        },
        {
            controlSchema: z.object({
                subject: z.string().default('A Successful Test on Novu from {{userName}}'),
            }),
        });
    }, {
        payloadSchema: z.object({
            userName: z.string().default('John Doe'),
        }),
    });
    ```
  </Step>
</Steps>


# Remix & React Email (/framework/content/remix-react-email)

Learn how to integrate React Email with Novu Framework in a Remix application

Integrating Novu Framework with [React email](https://react.email/) for your Remix application can be done in three steps. If you don't have an app, you can [clone our Remix example](https://github.com/novuhq/novu-framework-remix-example).

<Steps>
  <Step title="Install React email components">
    Install the required React email components.

    ```bash
      npm i @react-email/components react-email
    ```
  </Step>

  <Step title="Create email templates folder">
    Create an `emails` folder in the `app` directory of your Remix app.
  </Step>

  <Step title="Write your email">
    Create a new `sample-email.tsx` file for your email template.

    ```ts
    import { Button, Html } from "@react-email/components";

    function Email(props) {
      return (
        <Html>
          <Button
            href="https://example.com"
            style={{ background: "#000", color: "#fff", padding: "12px 20px" }}
          >
            Click me
          </Button>
        </Html>
      );
    }

    export function renderEmail(inputs) {
      return render(<Email {...inputs} />);
    }
    ```
  </Step>

  <Step title="Write your workflow">
    Define your workflow using the above template

    ```tsx
    import { renderEmail } from './sample-email.tsx';
    import { workflow } from '@novu/framework';

    workflow('new-signup', async ({ step, payload }) => {
      await step.email('send-email', async (inputs) => {
        return {
          subject: `Welcome to Remix and React E-mail`,
          body: renderEmail(inputs),
        }
      });
    });
    ```
  </Step>
</Steps>


# Svelte Email Integration (/framework/content/svelte-email)

Learn how to use Svelte Email to build beautiful email templates

Integrating Novu Framework with [Svelte email](https://react.email/) for your Svelte application can be done in three steps. If you don't have an app, you can [clone our Svelte example](https://github.com/novuhq/novu-svelte-email).

<Steps>
  <Step title="Install Svelte email components">
    Install the required Svelte email components.

    ```bash
      npm install svelte-email
    ```
  </Step>

  <Step title="Create email templates folder">
    Create a new folder called `emails` in your `src` folder.
  </Step>

  <Step title="Write your email">
    Create a new file called `test-email.svelte` in your `emails` folder.

    ```svelte
    <script lang="ts">
        import {
            Body,
            Container,
            Head,
            Html,
            Preview,
        } from 'svelte-email';

        export let name: string;
    </script>

    <Html>
        <Head />
        <Preview>Welcome to Svelte Email</Preview>
        <Body>
            <Container>
                <h1>Welcome, {name}!</h1>
                <p>Thanks for trying Svelte Email. We're thrilled to have you on board.</p>
            </Container>
        </Body>
    </Html>
    ```

    Create a new file called `test-email.ts` in your `emails` folder.

    ```typescript
    import { render } from 'svelte-email';
    import TestEmail from './test-email.svelte';

    export function renderEmail(name: string) {
        return render({
            template: TestEmail,
            props: {
                name,
            },
        });
    }
    ```
  </Step>

  <Step title="Write your workflow">
    Define your workflow using the above template

    ```typescript
    import { workflow } from '@novu/framework';
    import { renderEmail } from './emails/test-email';
    import { z } from 'zod';

    export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
        await step.email('send-email', async (controls) => {
            return {
                subject: controls.subject,
                body: renderEmail(payload.userName),
            };
        },
        {
            controlSchema: z.object({
                subject: z.string().default('A Successful Test on Novu from {{userName}}'),
            }),
        });
    }, {
        payloadSchema: z.object({
            userName: z.string().default('John Doe'),
        }),
    });
    ```
  </Step>
</Steps>


# Vue Email Integration (/framework/content/vue-email)

Learn how to use Vue Email to build beautiful email templates

You can integrate Novu Framework with [Vue Email](https://vuemail.net/) in a few simple steps. This guide will walk you through the process of creating a new email template using Vue Email and Nuxt.

For a Quickstart Boilerplate project using Nuxt.js, and Vue Email, check out the [Vue Email Starter repository](https://github.com/novuhq/novu-framework-nuxt-example/)

## Quickstart

<Steps>
  <Step title="Install Vue.Email components">
    ```bash
    npm install @vue-email/components
    ```
  </Step>

  <Step title="Create templates folder">
    Create a new folder called `emails` in your `src` folder.
  </Step>

  <Step title="Update nuxt.config.ts File">
    ```typescript
    export default defineNuxtConfig({
        build: {
            transpile: ['@vue/email'],
        },
        nitro: {
            esbuild: {
                options: {
                    target: 'esnext',
                },
            },
        },
    });
    ```
  </Step>

  <Step title="Write your email">
    ```vue
    <script setup lang="ts">
    import { VueEmail, Button, Container, Head, Html, Preview } from '@vue-email/components';

    defineProps<{
        name: string;
    }>();
    </script>

    <template>
        <VueEmail>
            <Html>
                <Head />
                <Preview>Welcome to Vue Email</Preview>
                <Container>
                    <h1>Welcome, {{ name }}!</h1>
                    <p>Thanks for trying Vue Email. We're thrilled to have you on board.</p>
                </Container>
            </Html>
        </VueEmail>
    </template>
    ```
  </Step>

  <Step title="Write your workflow">
    ```typescript
    import { workflow } from '@novu/framework';
    import { renderEmail } from './emails/test-email';
    import { z } from 'zod';

    export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
        await step.email('send-email', async (controls) => {
            return {
                subject: controls.subject,
                body: renderEmail(payload.userName),
            };
        },
        {
            controlSchema: z.object({
                subject: z.string().default('A Successful Test on Novu from {{userName}}'),
            }),
        });
    }, {
        payloadSchema: z.object({
            userName: z.string().default('John Doe'),
        }),
    });
    ```
  </Step>
</Steps>

## Learn More

To learn more, refer to [Vue Email documentation](https://vuemail.net/).


# GitHub Actions (/framework/deployment/actions)

Learn how to deploy your Novu workflows using the built-in GitHub Action for CI/CD automation.

Learn how to deploy your Novu workflows with our built-in GitHub Action command:

```yaml
name: Deploy workflow State to Novu

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # https://github.com/novuhq/actions-novu-sync
      - name: Sync State to Novu
        uses: novuhq/actions-novu-sync@v2
        with:
          # The secret key used to authenticate with Novu Cloud
          # To get the secret key, go to https://web.novu.co/api-keys.
          # Required.
          secret-key: ${{ secrets.NOVU_SECRET_KEY }}

          # The publicly available endpoint hosting the bridge application
          # where notification entities (eg. workflows, topics) are defined.
          # Required.
          bridge-url: ${{ secrets.NOVU_BRIDGE_URL }}

          # The Novu Cloud API URL to sync with.
          # Optional.
          # Defaults to https://api.novu.co
          api-url: https://api.novu.co
```


# Novu CLI Deployment (/framework/deployment/cli)

Learn how to use the Novu CLI to synchronize your workflows to Novu Cloud for production deployment.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The Novu CLI provides a mechanism for you to synchronize your workflows into Novu Cloud so that non-technical Novu users can control the workflow and Step-level controls and enable your workflows to be triggered via Novu API.

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```bash
    npx novu@latest sync \
      --bridge-url <YOUR_DEPLOYED_URL_WITH_BRIDGE_ENDPOINT> \
      --secret-key <NOVU_SECRET_KEY> \
      --api-url https://api.novu.co
    ```
  </Tab>

  <Tab value="EU Region">
    ```bash
    npx novu@latest sync \
      --bridge-url <YOUR_DEPLOYED_URL_WITH_BRIDGE_ENDPOINT> \
      --secret-key <NOVU_SECRET_KEY> \
      --api-url https://eu.api.novu.co
    ```
  </Tab>
</Tabs>

* If your application api server is running at URL **[https://api.domain.com](https://api.domain.com)** and **/api/novu** endpoint is serving Novu workflows created using Novu Framework, then `<YOUR_DEPLOYED_URL>`in above command will be `https://api.domain.com/api/novu`

* If your application is running in local machine with a local studio server, the tunnel URL can be used as `<YOUR_DEPLOYED_URL>`. The tunnel URL follows the format of `https://<UUID>.novu.sh/api/novu`, and example is `https://041e553c-0dbf-47e0-8ffa-c4536f390145.novu.sh/api/novu`. In this example `041e553c-0dbf-47e0-8ffa-c4536f390145` is the unique tunnel identifier which is generated for each Novu user when starting a tunnel via `npx novu@latest dev`. The tunnel identifier is persisted to your local machine to guarantee the same tunnel URL each time you invoke `npx novu@latest dev`.

## Using vercel preview url

In free tier, vercel preview urls for non production deployments are not publicly accessible. You will need to enable [Protection Bypass for Automation](https://vercel.com/docs/security/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation#protection-bypass-for-automation) from settings to make the preview url publicly accessible. Use vercel generated secret key in query params with bridge url to make the bridge url accessible to novu.

Example: `https://my-app-preview-url.vercel.app/api/novu?x-vercel-protection-bypass=BYPASS_SECRET_KEY`


# Production Deployment (/framework/deployment/production)

Learn how to deploy your Novu Framework application to production including networking, security, and HMAC verification setup.

## Networking

Novu Cloud workers will need to be able to communicate with your [Bridge Endpoint](/framework/endpoint). You will need to ensure that your firewall rules allow traffic from the internet.
Due to the autoscaling nature of Novu Cloud, we don't have a set of IP Addresses that you can whitelist.

## Security

Novu Cloud workers are GDPR, SOC2 type II and ISO 27001 compliant. We take security very seriously and have implemented a number of security measures to ensure that your data is safe.
Novu Framework has a builtin security mechanism that ensures that the requests are authentic from Novu Cloud using an HMAC signature.

HMAC Verification is turned on by default for all "production" NODE\_ENV environments

<Callout type="info">
  For `NODE_ENV=development` the HMAC validation is turned off, for the Studio to be able to reach
  your endpoint.
</Callout>

The `Novu-Signature` header included in each signed event contains a timestamp and one or more signatures that we verify.
The timestamp is prefixed by `t=`, and each signature is prefixed by a scheme.
Schemes start with `v`, followed by an integer. Currently, the only valid live signature scheme is v1.

{/* todo add an example of the x-novu-signature header here */}

Handling the signature verification is done by the Novu Framework, so you don't need to perform any action.


# Syncing Changes to Cloud (/framework/deployment/syncing)

Learn how to sync your local workflow changes to the Novu Cloud Dashboard across development and production environments.

Novu operates in a multi environment setup, with the currently available environments:

* **Local Studio** - Running against your local machine, this is where you can create, edit, and preview workflows.
* **Development** - Acts as a Staging environment, where your non-technical peers can view and modify controls.
* **Production** - For triggering workflows to your customers.

## Sync changes to Novu Cloud

Novu Framework operates in a GitOps model. This means that the source of truth for your workflows and configurations are located in your Git as Code.

The general workflow for pushing changes to Novu Cloud is as follows:

* Create a feature branch
* Develop workflows locally in your bridge application
* Sync changes to the Development environment to test e2e
* Merge the feature branch to your `dev` branch
  * This will trigger a CI/CD pipeline that will deploy the changes to the Development environment
* Test the changes in the Development environment
* Merge the `dev` branch to the `main` branch
  * This will trigger a CI/CD pipeline that will deploy the changes to the Production environment

## CI/CD Integrations

Novu currently supports the following CI integrations:

* **GitHub Actions** - [Direct Integration](/framework/deployment/actions)
* **GitLab CI** - Using our [CLI command](/framework/deployment/cli)
* **Jenkins** - Using our [CLI command](/framework/deployment/cli)
* **CircleCI** - Using our [CLI command](/framework/deployment/cli)
* **Bitbucket Pipelines** - Using our [CLI command](/framework/deployment/cli)
* **Azure DevOps** - Using our [CLI command](/framework/deployment/cli)
* **Travis CI** - Using our [CLI command](/framework/deployment/cli)
* **Other** - For any other CI/CD tool, you can use our [CLI command](/framework/deployment/cli)

<Callout type="info">
  Direct integration with other CI/CD tools is on our roadmap. If you would like to see a specific
  CI/CD tool integrated, please reach out to us.
</Callout>


# Express.js Framework Quickstart Guide (/framework/quickstart/express)

Get started with Novu Framework in an Express application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a Express.js application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    ```typescript app/server/api/novu.ts
    import { serve } from "@novu/framework/express";
    import { testWorkflow } from "../novu/workflows";

    app.use(express.json()); // Required for Novu POST requests
    app.use( "/api/novu", serve({ workflows: [testWorkflow] }) );
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your app folder as such `novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    Start your Express server with the Novu Endpoint configured.

    If your Express application is running on other than `4000` port, restart the `npx novu dev` command with the port:

    ```tsx
    npx novu@latest dev --port <YOUR_EXPRESS_JS_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="Express.js" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# H3 Framework Quickstart Guide (/framework/quickstart/h3)

Get started with Novu Framework in an H3 application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a H3 application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    ```typescript app/server/api/novu.ts
    import { createApp, eventHandler, toNodeListener } from "h3";
    import { serve } from "@novu/framework/h3";
    import { createServer } from "node:http";
    import { testWorkflow } from "./novu/workflows";

    const app = createApp();

    app.use("/api/novu", eventHandler(serve({ workflows: [testWorkflow] }) ));

    createServer(toNodeListener(app)).listen(4000);
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your app folder as such `novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    Start your H3 server with the Novu Endpoint configured.

    If your H3 application is running on a port other than `4000`, restart `npx novu dev` with that port:

    ```tsx
    npx novu@latest dev --port <YOUR_H3_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="H3" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# AWS Lambda Framework Quickstart Guide (/framework/quickstart/lambda)

Get started with Novu Framework in an AWS Lambda function

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a AWS Lambda application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    ```typescript src/functions/api/novu.ts
    import { serve } from "@novu/framework/lambda";
    import { workflow } from "@novu/framework";
    import { testWorkflow } from "../novu/workflows";

    module.exports.novu = serve({
        workflows: [testWorkflow],
    });
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your app folder as such `novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    Start your AWS Lambda server with the Novu Endpoint configured.

    If your Local Lambda application is running on other than `4000` port, restart the `npx novu dev` command with the port:

    ```tsx
    npx novu@latest dev --port <YOUR_AWS LAMBDA_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="AWS Lambda" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# NestJS Framework Quickstart Guide (/framework/quickstart/nestjs)

Get started with Novu Framework in a NestJS application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a NestJS application and send our first test workflow.

<Steps>
  <Step>
    ### Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ### Install packages

    <PackagesStep />
  </Step>

  <Step title="Add the NovuModule to your application">
    The `NovuModule` is a NestJS module that registers the Novu Endpoint in your application.

    The following example does not support NestJS dependency injection. If you need to `@Injectable` dependencies in your workflow definition, see [Advanced Usage](#advanced-usage-dependency-injection).

    ```typescript src/app.module.ts
    import { Module } from '@nestjs/common';
    import { NovuModule } from '@novu/framework/nest';
    import { testWorkflow } from './novu/workflows';

    @Module({
        imports: [
            NovuModule.register({
                apiPath: '/api/novu',
                workflows: [testWorkflow],
            }),
        ],
    })
    export class AppModule {}
    ```
  </Step>

  <Step>
    ### Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ### Create your workflow definition

    Add a `novu` folder in your `src` folder as such `src/novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ### Start your application

    Start your NestJS application with the Novu Endpoint configured.

    If your NestJS application is running on other than `4000` port, restart the `npx novu dev` command with the port:

    ```tsx
    npx novu@latest dev --port <YOUR_NESTJS_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ### Test your endpoint

    <TestStep framework="NestJS" />
  </Step>

  <Step>
    ### Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />

## Advanced Usage (Dependency Injection)

If you need to inject dependencies into your workflow definition, you can use the `registerAsync` method.

Add the `NovuModule` using the `registerAsync` method to your `AppModule`.

```typescript src/app.module.ts
import { Module } from '@nestjs/common';
import { NovuModule } from '@novu/framework/nest';
import { NotificationService } from './notification.service';
import { UserService } from './user.service';

@Module({
  imports: [
    NovuModule.registerAsync({
      imports: [AppModule],
      useFactory: (notificationService: NotificationService) => ({
        apiPath: '/api/novu',
        workflows: [notificationService.welcomeWorkflow()],
      }),
      inject: [NotificationService],
    }),
  ],
  providers: [NotificationService, UserService],
  exports: [NotificationService],
})
export class AppModule {}
```

For example, you might need to inject a service that fetches the user's name from a database. This is useful when you need to fetch data in realtime during the execution of your workflow.

An example `UserService` is available below with hardcoded values, but in a real-world application you might use a database or an external API to fetch the user's name.

```typescript src/user.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class UserService {
  getUser(id: string) {
    return {
      name: 'John Doe',
      email: `john.doe.${id}@example.com`,
    };
  }
}
```

Finally, configure your `NotificationService` to use the injected `UserService`.

```typescript src/notification.service.ts
import { Injectable } from '@nestjs/common';
import { workflow } from '@novu/framework';
import { z } from 'zod';
import { UserService } from './user.service';

@Injectable()
export class NotificationService {
  constructor(private readonly userService: UserService) {}

  public welcomeWorkflow() {
    return workflow(
      'welcome-email',
      async ({ step, payload }) => {
        await step.email('send-email', async () => {
          const user = this.userService.getUser(payload.userId);

          return {
            subject: `Hello, ${user.name}`,
            body: `We are glad you are here!`,
          };
        });
      },
      {
        payloadSchema: z.object({
          userId: z.string(),
        }),
      }
    );
  }
}
```

A full example NestJS application demonstrating dependency injection is available [here](https://github.com/novuhq/novu/tree/next/playground/nestjs).


# Next.js Framework Quickstart Guide (/framework/quickstart/nextjs)

Get started with Novu Framework in a Next.js application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a Next.js application and send our first test workflow.

<Steps>
  <Step title="Create a Next.js application">
    This link can be copied right from the onboarding guide on the Novu Studio or can always be copied from the [API Keys](https://dashboard.novu.co/api-keys) page on the Novu Dashboard.

    ```bash
    npx novu init --secret-key=<YOUR_NOVU_SECRET_KEY>
    ```

    The sample application will create an `.env` file containing the `NOVU_SECRET_KEY` environment variable required
    for securing your endpoint. And a sample workflow demonstrating the flexibility of Novu using Step Controls.

    <Accordions>
      <Accordion title="Manually add to an existing application (5 minutes)">
        **Install required packages**

        ```bash
        npm install @novu/framework @react-email/components react-email zod zod-to-json-schema
        ```

        This will install

        * **`@novu/framework`** SDK Package
        * **React Email** (Recommended) - For writing your email templates with React
        * **Zod** (Recommended) - For end-to-end type safety for your Payload and Step Controls

        **Add a Novu API Endpointt**

        ```typescript App Router (app/api/novu/route.ts)
        import { serve } from "@novu/framework/next";
        import { myWorkflow } from "../../novu/workflows";

        export const { GET, POST, OPTIONS } = serve({ workflows: [myWorkflow] });
        ```

        ```typescript Pages Router (pages/api/novu.ts)
        import { serve } from '@novu/framework/next';
        import { testWorkflow } from '../../novu/workflows';

        export default serve({ workflows: [testWorkflow] });
        ```

        **Add a Novu Secret Key Environment Variable**

        Add `NOVU_SECRET_KEY` environment variable to your `.env`

        ```bash
        NOVU_SECRET_KEY=<NOVU_SECRET_KEY>
        ```

        **Create your workflow definition**

        Add a `novu` folder that will contain your workflow definitions

        ```tsx app/novu/workflows.ts
        import { workflow } from '@novu/framework';
        import { renderEmail } from './emails/test-email';
        import { z } from 'zod';

        export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
            await step.email('send-email', async (controls) => {
                return {
                    subject: controls.subject,
                    body: renderEmail(payload.userName),
                };
            },
            {
                controlSchema: z.object({
                    subject: z.string().default('A Successful Test on Novu from {{userName}}'),
                }),
            });
        }, {
            payloadSchema: z.object({
                userName: z.string().default('John Doe'),
            }),
        });
        ```

        **Create your React Email Template (Optional)**

        Add a new email template

        ```typescript app/novu/emails/test-email.tsx
        import {
            Body,
            Container,
            Head,
            Html,
            render,
        } from '@react-email/components';
        import * as React from "react";

        interface TestEmailProps {
            name: string
        }

        export const TestEmailTemplate = ({ name }: TestEmailProps) => {
            return (
                <Html>
                    <Head />
                    <Body>
                        <Container>
                            Hello {name} welcome to your first React E-mail template!
                        </Container>
                    </Body>
                </Html>
            );
        };

        export default TestEmailTemplate;

        export function renderEmail(name: string) {
            return render(<TestEmailTemplate name={name} />);
        }
        ```
      </Accordion>
    </Accordions>
  </Step>

  <Step>
    ## Start your application

    To start your boilerplate Next.js server with the Novu Endpoint configured, run the following command:

    ```tsx
    cd my-novu-app && npm run dev
    ```

    The sample application will start on [`https://localhost:4000`](https://localhost:4000) and your novu endpoint will be exposed at `/api/novu` served by the Next.js API.

    If your Next.js application is running on other than `4000` port, restart the `novu dev` command with the port:

    ```tsx
    npx novu@latest dev --port <YOUR_NEXTJS_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="Next.js" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# Nuxt Framework Quickstart Guide (/framework/quickstart/nuxt)

Get started with Novu Framework in a Nuxt application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a Nuxt application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    ```typescript app/server/api/novu.ts
    import { serve } from '@novu/framework/nuxt';
    import { testWorkflow } from "../novu/workflows";

    export default defineEventHandler(serve({ workflows: [myWorkflow] }));
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your app folder as such `app/server/api/novu.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    Start your Nuxt application with the Novu Endpoint configured.

    ```bash
    cd my-novu-app && npm run dev
    ```

    If your Nuxt application is running on other than `4000` port, restart the `npx novu dev` command with the port:

    ```bash
    npx novu@latest dev --port <YOUR_NUXT_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="Nuxt" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# Remix Framework Quickstart Guide (/framework/quickstart/remix)

Get started with Novu Framework in a Remix application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a Remix application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    This guide is based on Remix Offical [Quick Start](https://remix.run/docs/en/main/start/quickstart).

    ```typescript app/routes/api.novu.ts
    import { serve } from "@novu/framework/remix";
    import { testWorkflow } from "../novu/workflows";

    const handler = serve({
        workflows: [testWorkflow]
    });

    export { handler as action, handler as loader };
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your app folder as such `app/novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    To start your Remix server with the Novu Endpoint configured, run the following command:

    ```bash
    cd my-novu-app && npm run dev
    ```

    Remix application default port is 5173. For that to work, restart Novu Studio and point it to the right port:

    ```bash
    npx novu@latest dev --port <YOUR_REMIX_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="Remix" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# SvelteKit Framework Quickstart Guide (/framework/quickstart/svelte)

Get started with Novu Framework in a SvelteKit application

import DeployApp from '@/snippets/quickstart/deploy.mdx';
import NextStepsStep from '@/snippets/quickstart/next-steps.mdx';
import { PackagesStep } from '@/snippets/quickstart/packages.tsx';
import { SecretStep } from '@/snippets/quickstart/secret.tsx';
import { StudioStep } from '@/snippets/quickstart/studio.tsx';
import { TestStep } from '@/snippets/quickstart/test.tsx';
import { WorkflowStep } from '@/snippets/quickstart/workflow.tsx';

In this guide, we will add a Novu [Bridge Endpoint](/framework/endpoint) to a Svelte application and send our first test workflow.

<Steps>
  <Step>
    ## Set up your local environment

    <StudioStep />
  </Step>

  <Step>
    ## Install packages

    <PackagesStep />
  </Step>

  <Step>
    ## Add a Novu API Endpoint

    ```typescript src/routes/api/novu/+server.ts
    import { testWorkflow } from '$lib/novu/workflows';
    import { serve } from '@novu/framework/sveltekit';

    export const { GET, POST, OPTIONS } = serve({ workflows: [testWorkflow] });
    ```
  </Step>

  <Step>
    ## Configure your secret key

    <SecretStep />
  </Step>

  <Step>
    ## Create your workflow definition

    Add a `novu` folder in your lib folder as such `src/lib/novu/workflows.ts` that will contain your workflow definitions.

    <WorkflowStep />
  </Step>

  <Step>
    ## Start your application

    To start your Svelte server with the Novu Endpoint configured, run the following command:

    ```tsx
    cd my-novu-app && npm run dev
    ```

    Svelte application default port is 5173. For that to work, restart Novu Studio and point it to the right port:

    ```tsx
    npx novu@latest dev --port <YOUR_SVELTE_APPLICATION_PORT>
    ```
  </Step>

  <Step>
    ## Test your endpoint

    <TestStep framework="Svelte" />
  </Step>

  <Step>
    ## Deploy your application

    <DeployApp />
  </Step>
</Steps>

<NextStepsStep />


# Class Validator Schema (/framework/schema/class-validator)

Integrate Class Validator with your notification workflows

Novu Framework allows you to use [Class Validator](https://www.npmjs.com/package/class-validator) to define the [Control](/framework/controls) and [Payload](/framework/payload) schemas for your workflows.

## Add class validator to your project

<Steps>
  <Step title="Install Class Validator Packages">
    ```bash
    npm install class-validator class-validator-jsonschema reflect-metadata
    ```

    Novu requires the `class-validator-jsonschema` package to generate JSON schemas from your DTOs. You may also need the `reflect-metadata` package.
  </Step>

  <Step title="Use Class Validator in your workflow">
    After installation, the Class Validator DTOs can be used interchangeably with the `controlSchema` and `payloadSchema` options in your workflow definitions.

    ```tsx
    import { workflow } from '@novu/framework';
    import { IsString, IsBoolean, IsNotEmpty, IsOptional, Type, NestedValidation } from "class-validator";

    class TestComponent {
        @IsString()
        subject: string;

        @IsString()
        content: string;
    }

    class TestControlSchema {
        @IsBoolean()
        hideBanner: boolean;

        @IsString()
        @IsNotEmpty()
        @IsOptional()
        subject?: string;

        // Allowing no code control over the component in the Dashboard UI
        @Type(() => NewSignUpComponent)
        @NestedValidation({ each: true })
        @IsOptional()
        components?: NewSignUpComponent[];
    }

    class TestPayloadSchema {
        @IsString()
        username: string;
    }

    export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
        await step.email('send-email', async (controls) => {
            return {
                subject: controls.subject,
                body: 'Hello, World!',
            };
        },
        {
            controlSchema: TestControlSchema,
        });
    }, {
        payloadSchema: TestPayloadSchema,
    });
    ```
  </Step>
</Steps>

## Controls and Payload UI

When you define a `controlSchema` for a step, Novu will automatically generate a UI for the controls in the workflow editor.

* **Form Input Title** - Will be derived from the key of the Class Validator schema. Unfortunately Class Validator does not support custom titles at this point.
* **Form Input Type** - Will be derived from the Class Validator schema type, with support for `string`, `number`, `boolean`, and `enum` and `array` types.
* **Default Value** - Unfortunately Class Validator does not support default values at this point.
* **Validation** - Will be derived from the Class Validator schema validation decorators, including `@Min`, `@Max`, `@IsEmail`, `@IsUrl` and etc...


# JSON Schema Validation (/framework/schema/json-schema)

Learn how to use JSON Schema to define the workflow payload and step inputs

JSON Schema can be used to define the [workflow payload](/framework/payload) and [step inputs](/framework/typescript/steps).
It provides a strongly-typed way to define the structure of the data that is expected by the workflow or Step.
And also as a contract for changing the workflow behaviour using the Platform User Interface.

Learn more about JSON schema at [json-schema.org](https://json-schema.org/).

## Examples

### Simple

```json
{
  "type": "object",
  "required": ["firstName", "lastName"],
  "properties": {
    "firstName": {
      "type": "string",
      "title": "First name",
      "default": "Chuck"
    },
    "lastName": {
      "type": "string",
      "title": "Last name"
    },
    "age": {
      "type": "integer",
      "title": "Age"
    }
  }
}
```

### Nested array structure

```json
{
  "type": "object",
  "required": ["title"],
  "properties": {
    "title": {
      "type": "string",
      "title": "Task list title"
    },
    "tasks": {
      "type": "array",
      "title": "Tasks",
      "items": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": {
            "type": "string",
            "title": "Title",
            "description": "A sample title"
          },
          "details": {
            "type": "string",
            "title": "Task details",
            "description": "Enter the task details"
          },
          "done": {
            "type": "boolean",
            "title": "Done?",
            "default": false
          }
        }
      }
    }
  }
}
```

### Reference and reuse blocks

```json
{
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        }
      },
      "required": ["street_address", "city", "state"]
    },
    "node": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/node"
          }
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing_address": {
      "title": "Billing address",
      "$ref": "#/definitions/address"
    },
    "shipping_address": {
      "title": "Shipping address",
      "$ref": "#/definitions/address"
    },
    "tree": {
      "title": "Recursive references",
      "$ref": "#/definitions/node"
    }
  }
}
```

### Any of schemas

```json
{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "title": "Age"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "anyOf": [
          {
            "properties": {
              "foo": {
                "type": "string"
              }
            }
          },
          {
            "properties": {
              "bar": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  },
  "anyOf": [
    {
      "title": "First method of identification",
      "properties": {
        "firstName": {
          "type": "string",
          "title": "First name",
          "default": "Chuck"
        },
        "lastName": {
          "type": "string",
          "title": "Last name"
        }
      }
    },
    {
      "title": "Second method of identification",
      "properties": {
        "idCode": {
          "type": "string",
          "title": "ID code"
        }
      }
    }
  ]
}
```

### One of schema

```json
{
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "lorem": {
          "type": "string"
        }
      },
      "required": ["lorem"]
    },
    {
      "properties": {
        "ipsum": {
          "type": "string"
        }
      },
      "required": ["ipsum"]
    }
  ]
}
```

### If then else

```json
{
  "type": "object",
  "properties": {
    "animal": {
      "enum": ["Cat", "Fish"]
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "animal": {
            "const": "Cat"
          }
        }
      },
      "then": {
        "properties": {
          "food": {
            "type": "string",
            "enum": ["meat", "grass", "fish"]
          }
        },
        "required": ["food"]
      }
    },
    {
      "if": {
        "properties": {
          "animal": {
            "const": "Fish"
          }
        }
      },
      "then": {
        "properties": {
          "food": {
            "type": "string",
            "enum": ["insect", "worms"]
          },
          "water": {
            "type": "string",
            "enum": ["lake", "sea"]
          }
        },
        "required": ["food", "water"]
      }
    },
    {
      "required": ["animal"]
    }
  ]
}
```

### Enum objects

```json
{
  "definitions": {
    "locations": {
      "enumNames": ["New York", "Amsterdam", "Hong Kong"],
      "enum": [
        {
          "name": "New York",
          "lat": 40,
          "lon": 74
        },
        {
          "name": "Amsterdam",
          "lat": 52,
          "lon": 5
        },
        {
          "name": "Hong Kong",
          "lat": 22,
          "lon": 114
        }
      ]
    }
  },
  "type": "object",
  "properties": {
    "location": {
      "title": "Location",
      "$ref": "#/definitions/locations"
    },
    "locationRadio": {
      "title": "Location Radio",
      "$ref": "#/definitions/locations"
    },
    "multiSelect": {
      "title": "Locations",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "$ref": "#/definitions/locations"
      }
    },
    "checkboxes": {
      "title": "Locations Checkboxes",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "$ref": "#/definitions/locations"
      }
    }
  }
}
```

### Regex validation

The following example matches a simple North American telephone number with an optional area code:

```json
{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
    }
  }
}
```

## Other resources

* [Examples](https://json-schema.org/learn/miscellaneous-examples)
* [React JSON schema](https://rjsf-team.github.io/react-jsonschema-form/)
* [JSON schema validator](https://www.jsonschemavalidator.net/)
* [JSON schema lint](https://jsonschemalint.com/)


# Zod Schema Validation (/framework/schema/zod)

Learn how to integrate Zod with Novu Framework

Novu Framework allows you to use [Zod](https://zod.dev/) to define the [Control](/framework/controls) and [Payload](/framework/payload) schemas for your workflows. *(Supports Zod v3)*

## Add Zod to your project

<Steps>
  <Step title="Install Zod Packages">
    ```bash
    npm install zod
    ```

    <Callout type="info">
      Novu Framework supports Zod v3. Make sure you're using this version for optimal performance and feature support.
    </Callout>
  </Step>

  <Step title="Use Zod in your workflow">
    ```typescript
    import { workflow } from '@novu/framework';
    import { z } from 'zod';

    export const testWorkflow = workflow('test-workflow', async ({ step, payload }) => {
        await step.email('send-email', async (controls) => {
            return {
                subject: controls.subject,
                body: 'Hello World',
            };
        },
        {
            controlSchema: z.object({
                subject: z.string().default('A Successful Test on Novu from {{userName}}'),
            }),
        });
    }, {
        payloadSchema: z.object({
            userName: z.string().default('John Doe'),
        }),
    });
    ```
  </Step>
</Steps>

## Controls and Payload UI

When you define a `controlSchema` for a step, Novu will automatically generate a UI for the controls in the workflow editor.

* **Form Input Title** - Will be derived from the key of the Zod schema. Unfortunately Zod does not support custom titles at this point.
* **Form Input Type** - Will be derived from the Zod schema type, with support for `string`, `number`, `boolean`, and `enum` and `array` types.
* **Default Value** - Will be derived from the Zod schema default value.
* **Validation** - Will be derived from the Zod schema validation rules, including `min`, `max`, `email`, `url`, `regex` and etc...


# Framework Client (/framework/typescript/client)

Learn how to configure and use the Novu Framework Client for managing global settings

The `Client` is an optional Class you can pass to the `serve` function to override some global settings.
By default, we will inject a new instance of the `Client` class in your `serve` method with the following defaults:

## Client Interface

### secretKey

* **Type**: `string`
* **Default**: `process.env.NOVU_SECRET_KEY`
* **Description**: Your Novu Secret Key, used to sign the HMAC header to guarantee the authenticity of our requests.

### strictAuthentication

* **Type**: `boolean`
* **Default**: `process.env.NODE_ENV !== 'development'`
* **Description**: This bypasses the HMAC signature verification, required for local development and testing against [Local Studio](/framework/studio).

## Environment Variables

Unless specified in the `Client` constructor the `Client` class will look for the following environment variables:

* `NOVU_SECRET_KEY` - Your Novu Secret Key
* `NOVU_API_URL` - Defaults to `https://api.novu.co`. For EU customers, this should be set to `https://eu.api.novu.co`.

## Development Environment

When your service is running in development mode `process.env.NODE_ENV=development`, the following rules will auto apply:

* `strictAuthentication` will be set to `false`.

## Code Example

```tsx
import { Client as NovuFrameworkClient } from '@novu/framework';
import { serve } from '@novu/framework/next';
import { passwordResetWorkflow } from './workflows';

export const { GET, POST, OPTIONS } = serve({
  client: new NovuFrameworkClient({
    secretKey: process.env.NOVU_SECRET_KEY,
    strictAuthentication: false,
  }),
  workflows: [
    /* all workflows */
    passwordResetWorkflow,
  ],
});
```


# Novu Framework TypeScript Overview (/framework/typescript/overview)

Learn how to use Novu's TypeScript SDK to build type-safe notification workflows with advanced features like payload validation and step controls.

Although you can trigger Novu workflows from any programming language using our Rest API SDKs.

We believe that the best way to build your notification strategy is to treat your templates and workflows as your Notification Design System.
Building reusable components to be consumed and embedded by your non-technical peers in any combination.

Typescript SDKs enable the creation of stunning channel content like E-mails using modern technologies like React/Vue/etc...
Treating your emails as a front-end concern opens up a world of possibilities to reuse design tokens, components, and even entire templates across your applications for consistent branding and a cohesive user experience.

Novu Framework was built and optimized with extreme focus on Developer Experience.
Our `@novu/framework` SDK is written in Typescript, and we recommend using Typescript for your own projects as well.

## Type-safe workflow payloads

When defining a [workflow payload](/framework/payload) schema, our SDK will automatically infer it to a Typescript interface.

```tsx
import { workflow } from '@novu/framework';

const myWorkflow = workflow(
  'new-signup',
  async ({ step, payload }) => {
    await step.email('send-email', () => {
      return {
        subject: 'Hello World',
        // The payload object here is type-safe
        body: `Hi ${payload.name}, welcome to our platform!`,
      };
    });
  },
  {
    payloadSchema: { properties: { name: { type: 'string' } } },
  }
);
```

## Type safe steps

Similarly, when defining a [step](/framework/typescript/steps) schema, our SDK will automatically infer it to a Typescript interface.

## Step controls

Build and define type safe controls to expose no-code editing capabilities to your teammates.

## Explore the SDK

* [Client](/framework/typescript/client)
* [Workflow](/framework/typescript/workflow)
* [Steps](/framework/typescript/steps)

<Callout type="info">
  The `@novu/framework` SDK is compatible with Node.js version 20.0.0 and above.
</Callout>


# Novu Framework Workflow Interface (/framework/typescript/workflow)

Learn about the Novu Framework workflow interface and its configuration options

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## Example Usage

```tsx
import { workflow } from '@novu/framework';

workflow(
  'my-workflow',
  async ({ step, payload, subscriber }) => {
    await step.inApp('send-in-app', async () => {
      return {
        body: 'Hello there',
      };
    });
  },
  {
    payloadSchema: z.object({
      body: z.string(),
    }),
    name: 'My Workflow',
    description: 'This is a workflow',
    tags: ['business', 'critical'],
    preferences: {
      channels: {
        inApp: { enabled: true },
      },
    },
  }
);
```

## Interface

```typescript
import { workflow } from '@novu/framework';

workflow(workflowId, handler, options);
```

### Parameters

#### workflowId

* **Type**: `string`
* **Required**: Yes
* **Description**: This id should be unique within your organization.

#### handler

* **Type**: `(context: WorkflowContext) => Promise<void>`
* **Required**: Yes
* **Description**: The definition function of the workflow.

#### options

* **Type**: `WorkflowOptions`
* **Required**: No
* **Description**: An optional options object for workflow level configurations

##### options.payloadSchema

* **Type**: `JsonSchema | ZodSchema`
* **Description**: The schema to validate the event payload against, can be used to provide default values.

##### options.name

* **Type**: `string`
* **Description**: The name of the workflow. This is used to display a human-friendly name for the workflow in the Dashboard and `<Inbox />` component. If no value is specified, the `workflowId` will be used as the name.

##### options.description

* **Type**: `string`
* **Description**: The description of the workflow. This is used to provide a brief overview of the workflow in the Dashboard.

##### options.tags

* **Type**: `string[]`
* **Description**: The tags assigned to the workflow. Tags can be used to filter workflows in the dashboard, and can be used by channels such as Inbox to sort Notifications into different categories for a better user experience.

##### options.preferences

* **Type**: `WorkflowPreferences`
* **Description**: The preferences for the workflow. Read more about [Workflow Channel Preferences](/platform/concepts/preferences#workflow-channel-preferences).

###### preferences.all

* **Type**: `WorkflowPreference`
* **Properties**:
  * `enabled`: `boolean` (default: `true`) - A flag specifying if notification delivery is enabled for the workflow.
  * `readOnly`: `boolean` (default: `false`) - A flag specifying if the preferences are read-only.

###### preferences.channels

* **Type**: `ChannelPreferences`
* **Description**: The preferences for each channel. Read more about [Workflow Channel Preferences](/platform/concepts/preferences).
* **Properties**:
  * `inApp`: `{ enabled: boolean }` - In-app channel preferences
  * `email`: `{ enabled: boolean }` - Email channel preferences
  * `sms`: `{ enabled: boolean }` - SMS channel preferences
  * `chat`: `{ enabled: boolean }` - Chat channel preferences
  * `push`: `{ enabled: boolean }` - Push channel preferences

## Workflow Context

This context is passed by the workflow engine to provide contextual information about current workflow execution.

### subscriber

* **Type**: `Subscriber`
* **Properties**:
  * `subscriberId`: `string` (required) - The id of the subscriber, as passed during `/events/trigger` request.
  * `firstName`: `string` (nullable) - The first name of the subscriber.
  * `lastName`: `string` (nullable) - The last name of the subscriber.

### payload

* **Type**: `InferProperties<payloadSchema>`
* **Description**: The payload of the event that triggered the workflow, will be validated against the `payloadSchema` if provided.

### step

* **Type**: `object`
* **Description**: The object that contains all the step functions, read more at [Step Functions](/framework/typescript/steps).

## Workflow Channel Preferences

With Workflow channel preferences, you can control the default delivery preference for a channel and whether a subscriber can change it. Novu will show the subscriber preferences in `<Inbox/>` component. Subscribers can enable and disable any active channel in the workflow.

In the `all` object, you can specify default preferences for all channels. The `enabled` field on the `all` object is used as fallback value if a channel is not specified explicitly in `channels`.

The `readOnly` field controls whether subscribers can change the delivery preference for a channel. Critical workflows are defined with `{ readOnly: true }`.

In the `channels` object, you can specify In-App, SMS, Email, Chat, and Push channel preferences. Each channel takes an object with an optional `enabled` flag that controls whether a notification delivery channel is enabled or disabled by default for subscribers.

### Default values

By default, `enabled` is `true` for all channels. The `readOnly` flag is `false`.

<Callout type="info">
  These preferences can also be controlled from the Novu Dashboard per workflow. To do so, click on
  the cog icon at the top right of your screen, and then select the "Preferences" tab.
</Callout>

<Tabs items={['Default', 'In-App Only - Editable', 'All Enabled - Editable']}>
  <Tab value="Default">
    ```tsx
    const newWorkflow = workflow(
      'default-preferences',
      async ({ step }) => {
        await step.inApp('send-in-app', () => ({
          body: 'Hello there',
        }));
      },
      {
        preferences: {
          all: { enabled: true, readOnly: false },
          channels: {
            inApp: { enabled: true },
            email: { enabled: true },
            sms: { enabled: true },
            chat: { enabled: true },
            push: { enabled: true },
          },
        },
      }
    );
    ```
  </Tab>

  <Tab value="In-App Only - Editable">
    ```tsx
    const newWorkflow = workflow(
      'only-in-app-channel',
      async ({ step }) => {
        await step.inApp('send-in-app', () => ({
          body: 'Hello there',
        }));
      },
      {
        preferences: {
          all: { enabled: false },
          channels: {
            inApp: { enabled: true },
          },
        },
      }
    );
    ```
  </Tab>

  <Tab value="All Enabled - Editable">
    ```tsx
    const newWorkflow = workflow(
      'all-enabled-editable',
      async ({ step }) => {
        await step.inApp('send-in-app', () => ({
          body: 'Hello there',
        }));
      },
      {
        preferences: {
          all: { enabled: true },
        },
      }
    );
    ```
  </Tab>
</Tabs>


# Authentication Setup (/platform/account/authentication)

Configure authentication for Novu with OAuth, SSO, MFA, and more. Available for Enterprise customers on Novu Cloud.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';

<Callout type="info">
  This feature is only available to Enterprise customers on our [Cloud
  platform](https://dashboard.novu.co/?utm_campaign=docs_account_authentication). For more
  information, please see our [Enterprise plan](https://novu.co/pricing) in the pricing page.
</Callout>

## Key capabilities

### Out-of-the-box OAuth providers

Currently providing authentication via Github, with the plan to expand to a number of other providers such as:

* Google
* Facebook
* Apple
* Microsoft
* LinkedIn

### SSO, SAML and OpenID connect

Novu provides a streamlined implementation of SAML and OpenID Connect protocols, allowing integration with a wide range of enterprise IdPs. Arrange setup of known providers like Okta, Microsoft Entra ID, Google workspace or a custom SSO provider.

Novu adheres to industry-standard security protocols to ensure secure and reliable user authentication.

### Advanced security features

<Accordions>
  <Accordion title="Multi-Factor Authentication (MFA)">
    Robust MFA options including SMS passcodes, authenticator apps, hardware keys, and recovery
    codes, enhancing security and reducing the risk of unauthorized access.
  </Accordion>

  <Accordion title="Session Management">
    Comprehensive session management features including active device monitoring, session
    revocation, and adaptive session durations to balance security and user convenience.
  </Accordion>
</Accordions>

### User management and customization

<Cards>
  <Card title="Roles and permissions">
    Detailed control over user roles and permissions to tailor access levels and ensure appropriate
    access control.
  </Card>

  <Card title="User invitations and Onboarding">
    Smooth onboarding processes with customizable invitation workflows, ensuring a positive initial
    user experience.
  </Card>

  <Card title="Profile management">
    Intuitive profile management for users to update their information and authentication methods
    easily.
  </Card>
</Cards>


# Billing and Payments (/platform/account/billing)

Manage your billing and payment information, view invoices, and upgrade your subscription plan.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

## Frequently Asked Questions

<Accordions>
  <Accordion title="How to purchase a paid plan?">
    Paid plans can be purchased from billing settings in the Novu dashboard. Click on the avatar icon in the top right corner of the dashboard, then click on **Billing Plans** in the left side menu to access the billing settings. From there, you can select the desired subscription tier and complete the purchase.

    <img alt="Upgrade subscription from billing settings" src="/images/account/billing/purchase-business-tier.gif" />
  </Accordion>

  <Accordion title="How to access past invoices?">
    Past invoices can be accessed from the billing settings in the Novu dashboard. Click on the avatar icon in the top right corner of the dashboard, then click on **Billing Plans** on the side menu to access the billing settings. From there, click on the **Manage Subscription** option in your subscribed tier to view past invoices.

    <img alt="Access past invoices using manage subscription option" src="/images/account/billing/manage-invoices.gif" />
  </Accordion>
</Accordions>


# Team members (/platform/account/manage-members)

How to invite, manage, update permissions for, and remove members from your Novu organization

You can manage the members of your organization from the **Settings** page in your Novu dashboard. From there, you can assign responsibilities, manage permissions, and control access to workflows and other features.

Only members with the **Owner** role can invite or manage members.

![Managing organization members](/images/account/managing-members-overview.png)

## Invite a new member to your organization

1. In the dashboard, go to **Settings** > **Team**
2. Click **Invite**. You can do this from the **Members**, **Invitations**, or **Requests** tab.
3. Enter the member’s email address into the email field provided.
4. (Optional) Assign a role to the new member. If no role is selected, then the member is assigned the **Viewer** role by default.
5. Click **Send invitation**.

The invited user appears under the **Invitations** tab until they accept. Once accepted, they automatically move to the **Members** tab.

![Managing organization members](/images/account/managing-members-invites.png)

## Add a verified domain for automatic or request-based onboarding

You can simplify member onboarding by allowing users with your organization's email domain to join automatically or request to join your Novu organization.

1. In the dashboard, go to **Settings** > **Organization**
2. Scroll to the **Verified Domains** section.
3. Click **Add Domain**.
4. Enter the email domain you want to verify (for example, `novu.co`) into the email field provided.
5. Click **Save**.
6. Confirm the verification process, if prompted.

![Add a verified domain for automatic or request-based onboarding](/images/account/add-a-verified-domain.png)

Once added:

* Anyone who signs up using a verified domain can either join automatically or send a request to join, depending on your organization’s configuration.
* These users are assigned the Viewer role by default.

<Callout type="info">Only users with non-public domains (for example, not `gmail.com`) can be auto-joined. You must have at least one Owner from the domain before it can be verified.</Callout>

## Revoke a pending invitation

You can revoke an invitation if a user hasn't accepted it yet. Revoking an invite immediately makes the link invalid.

1. In the dashboard, go to **Settings** > **Team**.
2. Click the **Invitations** tab to view all pending invites.
3. In the **Actions** column, click the (⋯) menu next to the user whose invite you want to revoke.
4. Click **Revoke invitation**

![How to revoke a pending invitation](/images/account/revoke-invitation.png)

<Callout type="info">You can still send a new invitation after revoking the previous one.</Callout>

## Manage join requests

Users with a verified email domain can request to join your Novu organization. Only owners can approve or decline these requests.

1. In the dashboard, go to **Settings** > **Team**.
2. Open the **Requests** tab.
3. Review the list of users who have requested to join your organization.
4. In the **Actions** column, click the (⋯) menu next to their name.
5. Accept or decline their request.

Users who are approved will be added to your organization and assigned the Viewer role by default.

## Update a member's role

You can update a member's role to control what they can access and manage within your organization. Only Owners can change roles.

1. In the dashboard, go to **Settings** > **Team**.
2. Click the **Members** tab.
3. Find the user whose role you want to change.
4. In the **Role** column, click the list next to their current role.
5. Select a new role from the list of [available account roles](/platform/account/roles-and-permissions).

![Updating a member's role](/images/account/managing-members-update-roles.png)

<Callout type="info">The last owner of an organization cannot have their role changed. Every organization must have an owner.</Callout>

## Remove a member from your organization

You can remove members who no longer need access to your Novu organization. This action immediately revokes their access to your organization dashboard and signs them out. Only owners can perform this action.

1. In the dashboard, go to **Settings** > **Team**.
2. Click the **Members** tab.
3. Find the member you want to remove.
4. Click the action menu (⋯) next to their name.
5. Click **Remove member**.

![Removing members from your organization](/images/account/managing-members-remove.png)

<Callout type="info">The owner who created the organization cannot be removed. Members can also leave your organization.</Callout>


# Roles and permissions (/platform/account/roles-and-permissions)

Learn how roles and permissions are managed within Novu organizations

Novu uses a role-based access control (RBAC) model at the [organization level](/platform/how-novu-works#organization-and-environments). Each member in the organization is assigned a role that determines the actions they can perform within the Novu dashboard. Every user can belong to more than one organization, each with separate configurations and permissions.

When you invite a team member to your organization, you can assign them a role that determines the actions they can perform within that organization. You can later update their role from the [Team section](https://dashboard.novu.co/settings/team) in your organization settings.

<Callout type="info">
  This feature is available to users on the Team and Enterprise pricing plans, and it is supported on both the new dashboard and the legacy dashboard.
</Callout>

Below is an overview of the four roles available in Novu:

* **Owner**. For your primary account administrator. This role has full access across the platform, including organization-level settings, billing, API keys, environment management, and user administration. Each Novu organization must have at least one owner.

* **Admin**. For users who manage configuration and operational aspects of Novu. Admins can manage workflows, integrations, subscribers, environments, and message logs. They do not have access to billing.

* **Author**. For users who design and update notification workflows. Authors can create and modify workflows, preview steps, manage topics, and trigger events. They do not have access to organization-level settings, billing, or member management.

* **Viewer**. For read-only users. Viewers can view workflows, environments, logs, and messages, but cannot create, update, or delete resources.

## Roles and permissions table

Below is a detailed table showing which permissions are associated with each role.

Legend:

* 📖 - Read access
* ✏️ - Write (full access: read, write, delete)
* ❌ - No access

| Permission                     | **Viewer** | **Author** | **Admin** | **Owner** |
| ------------------------------ | ---------- | ---------- | --------- | --------- |
| Create and manage environments | ❌          | ❌          | ✏️        | ✏️        |
| Create and manage messages     | 📖         | ✏️         | ✏️        | ✏️        |
| Create and manage topics       | 📖         | ✏️         | ✏️        | ✏️        |
| Create and manage webhooks     | 📖         | 📖         | ✏️        | ✏️        |
| Create and manage workflows    | 📖         | ✏️         | ✏️        | ✏️        |
| Manage API keys                | ❌          | ❌          | ✏️        | ✏️        |
| Manage billing                 | ❌          | ❌          | ❌         | ✏️        |
| Manage bridges                 | ❌          | ❌          | ✏️        | ✏️        |
| Manage custom domains          | 📖         | 📖         | ✏️        | ✏️        |
| Manage integrations            | 📖         | 📖         | ✏️        | ✏️        |
| Manage organization metadata   | ❌          | ❌          | ❌         | ✏️        |
| Manage organization profile    | ❌          | ❌          | ❌         | ✏️        |
| Manage partner integrations    | 📖         | 📖         | ✏️        | ✏️        |
| Manage subscribers             | 📖         | ✏️         | ✏️        | ✏️        |
| Trigger events                 | ❌          | ✏️         | ✏️        | ✏️        |
| View and manage team members   | 📖         | 📖         | 📖        | ✏️        |
| View notifications             | 📖         | 📖         | 📖        | 📖        |
| Environment Variables          | 📖         | ✏️         | ✏️        | ✏️        |


# Single Sign-On (SSO) for your account (/platform/account/sso)

Learn how to enable Single Sign-On (SSO) for your account.

import { Card, Cards } from 'fumadocs-ui/components/card';

<Callout type="info">
  This feature is only available to Enterprise customers on our Cloud platform. For more
  information, please visit our [Enterprise Plan](https://novu.co/pricing) page.
</Callout>

Novu provides a SAML SSO (Single Sign-On) integration, enabling you to authenticate your organization’s users with your existing SAML infrastructure.

Novu is compatible with any SAML 2.0 compliant Identity Provider (IdP), including but not limited to:

Okta
Microsoft Entra ID (formerly Azure AD)
Google Workspace
Any other SAML 2.0 compliant IdP
To enable SAML SSO for your account, please reach out to your account manager or contact us at [sales@novu.co](mailto:sales@novu.co).


# Common Errors (/platform/additional-resources/errors)

Understand common errors in your notification workflows and how to resolve them

The Activity Feed page in the Novu dashboard displays all the events that occur when a workflow is triggered. Each triggered workflow includes a log for every step, showing whether a notification failed and why. Below are some common errors that you might encounter.

## Webhook URL for the chat channel is missing

This happens when the subscriber is missing the required chat channel provider credentials, specifically, the webhook URL. Chat providers require a valid webhook URL to receive notifications.

**Solution:**

Ensure that the correct webhook URL is configured for the subscriber’s chat provider. [Read more about updating webhook URLs](/platform/integrations/chat#update-credential-webhookurl).

## All chat channels failed to send the message

When the workflow engine attempts to send a chat message, it tries all active chat providers. This error occurs when every configured provider fails to deliver the message.

**Solution:**

Check the individual chat provider configurations and logs to identify why each failed. Verify credentials, webhook URLs, and provider availability.

## Subscriber is missing a phone number

To send an SMS, the subscriber must have a valid phone number. If this field is missing, then the system cannot deliver the message.

**Solution:**

Update the subscriber profile with a valid phone number. Similar errors may include missing recipient details. [Learn how to create and update subscriber attributes](/platform/concepts/subscribers).

## Subscriber does not have an active integration

The system couldn't send the message because the required chat or push providers are not configured in the integration store. As a result, the subscriber lacks the credentials needed to use these channels.

**Solution:**

Configure the appropriate chat or push provider in the integration store. This allows the subscriber to inherit the necessary credentials.

## Subscriber does not have a configured channel

This error indicates that the subscriber is not associated with any configured credentials for chat or push channels.

**Solution:**

Ensure the subscriber is mapped to an integration that supports the desired channel. [Read more on configuring chat and push channels](/platform/integrations/push).

## Message content could not be generated

This usually happens due to invalid characters in the step editor content. For example, if it’s an email step, it could be caused by a syntax error in the email editor.

**Solution:**

Review the content in the step editor and ensure it contains valid syntax and characters. Correct any formatting or special character issues.

## Novu's provider limit has been reached

Each environment in Novu is provisioned with demo providers for email and SMS channels. These demo providers are limited to 300 emails and 20 SMS per month.

**Solution:**

Upgrade to a production provider or reset the limit for testing. Avoid using demo providers for production use cases.

## Bridge execution failed

This error occurs when the bridge URL is invalid or unreachable during the execution of a workflow step.

**Solution:**

Verify that the bridge URL is correctly set, publicly accessible (if needed), and responds within a reasonable timeout.


# Novu Glossary (/platform/additional-resources/glossary)

Definitions

## Introduction

In this section, you'll find a list of key terms, their definitions and various concepts associated with Novu. Familiarising yourself with these will help you understand and use Novu better. They will help you navigate our docs more effectively and utilise Novu to its maximum potential.

If you have any questions or need further clarification on any of the terms listed above, please feel free to reach out to our support team or join our community!

## List of key terms and definitions

### Actor

An `actor` refers to a user or subscriber who initiates actions that trigger events within the system. Each actor is uniquely identified by an "actorId," also known as "subscriberId". Actors hold user-related variables and can enhance notifications by allowing their avatars to be displayed.

### Channels

Novu lets you send notifications across different communication mediums, including emails, in-app messages, push notifications, SMS, and chat. Each of these five communication mediums is referred to as a notification 'channel'.

### Delay Actions

Delay actions introduce time intervals between workflow steps, optimizing message delivery timing.

### Digest Engine

The digest engine aggregates multiple trigger events into a single message, ensuring efficient communication.

### Environments

Novu runs all your requests in the context of an environment. By default, Novu creates two environments:

1. Development environment: For testing purposes and validating notification changes
2. Production environment: Your live environment (read-only, changes must be promoted from development)

Data associated with an environment includes:

* Subscribers (can't be promoted to production)
* Workflows (can be promoted to production)
* Messages
* Execution logs
* Connected integrations (can't be promoted to production)
* Notification feeds (can be promoted to production)
* Brand-related assets and settings

### Layouts

Layouts are HTML designs or structures to wrap the content of email notifications. Layouts can be manipulated and assigned to new or existing workflows within the Novu platform.

### Notification

A brief message or alert that informs users about events, updates, or some other information.

### Organizations

Organizations allow separation of notifications across multiple products, managed through the Novu web dashboard.

### Providers

Providers are responsible for handling message delivery across various channels. Novu currently supports multiple notification channels, each with its own set of providers.

* Chat: Discord, MS Teams, Slack, Zulip
* Email: Sendgrid, Amazon SES, Brevo, Resend, SparkPost, Postmark, Mailjet, Mailtrap, Plunk, Braze, Mailersend, Outlook 365, Mailgun, Mandrill, Netcore, Infobip, Custom SMTP
* SMS: Twilio SMS, SMS77, Africa's Talking, Infobip, Nexmo, Plivo, Sendchamp, AWS SNS, Telnyx, Termii, Firetext, Gupshup, Clickatell, Azure SMS, BulkSMS, SimpleTexting, MessageBird
* Push Notification: Firebase Cloud Messaging (FCM), Expo Push, Apple Push Notification Service (APNS), One Signal, Pushpad, Pusher Beams, Push Webhook
* Inbox: React component, Angular component, Vue component, Web component, iFrame embed, Custom styling, Headless Inbox

### Step Filter

Step filters customize workflow by specifying notification criteria, enhancing communication efficiency.

### Subscribers

Subscribers are entities designated to receive the notifications you send. Each subscriber in Novu is uniquely identified by their `subscriberId`.

### Team members

Members of a team have access to the Novu web dashboard. This allows you to have individuals work on and manage templates and notifications.

### Topics

Topics facilitate bulk notifications to multiple subscribers simultaneously, streamlining communication.

### Workflow

Workflow templates define the flow of messages sent to subscribers.


# Legacy documentation (/platform/additional-resources/legacy-documentation)

Access the legacy v0.x Novu documentation for older versions of the platform.

## v0.x documentation

The v0.x documentation is available at [https://v0.x-docs.novu.co/getting-started/introduction](https://v0.x-docs.novu.co/getting-started/introduction).


# Security and Compliance (/platform/additional-resources/security)

Learn about Novu security certifications, compliance standards, data residency, and privacy policies

## How to Request SOC and ISO Reports

You can access our compliance reports and certifications directly from our Trust Center at [trust.novu.co](https://trust.novu.co). The Trust Center provides self-service access to:

* SOC 2 Type II report
* ISO 27001 certification
* HIPAA compliance documentation
* Security policies and procedures
* Live compliance controls status

Simply visit [trust.novu.co](https://trust.novu.co) to request and download any security documentation you need.

## Compliance Certifications

### SOC 2 Type II

Novu Cloud is SOC 2 Type II compliant. We have completed penetration tests, security training, evidence collection, and follow secure development lifecycle (SDL) practices. You can see live control updates on our [Trust Center](https://trust.novu.co/).

### ISO 27001

Novu Cloud is ISO 27001 compliant. We have completed both Stage 1 and Stage 2 audits and fully defined ISMS requirements. This includes:

* Creating comprehensive organization processes
* Defining organization risk assessment policies
* Building Incident Response & Disaster Recovery plans

### HIPAA

Novu Cloud is HIPAA compliant and we offer Business Associate Agreements (BAA) for customers who require them. This enables healthcare organizations and their partners to use Novu while maintaining compliance with healthcare data protection requirements.

### GDPR

Yes, Novu is fully GDPR compliant. You can see the complete compliance report on our [Trust Center](https://trust.novu.co/). Novu provides separate data residency options in both the EU and the US to support your compliance needs.

## Data Residency

### Available Regions

Novu Cloud is available in the following regions:

| Region          | Location                |
| --------------- | ----------------------- |
| **US**          | Virginia, United States |
| **EU**          | Frankfurt, Germany      |
| **UK**          | United Kingdom          |
| **Singapore**   | Singapore               |
| **Australia**   | Australia               |
| **Japan**       | Japan                   |
| **South Korea** | South Korea             |

As part of our GDPR compliance, you can choose which region your data resides in when creating your account. Enterprise regions (UK, Singapore, Australia, Japan, South Korea) are available on enterprise plans.

### Switching Regions

To maintain data residency integrity, we cannot copy or move data between data warehouses in different regions. If you need to switch regions, please contact us at [sales@novu.co](mailto:sales@novu.co) to discuss your options.

### Self-Hosted and Hybrid Options

* **Open Source**: You control where your data is stored
* **Novu Hybrid-Cloud**: We help you deploy within your selected network infrastructure

## Data Storage and Retention

By default, data is stored using the following retention periods:

| Data Type          | Free    | Pro     | Team    | Enterprise |
| ------------------ | ------- | ------- | ------- | ---------- |
| Activity Feed Logs | 24 hrs  | 7 days  | 90 days | Custom     |
| Inbox Messages     | 30 days | 90 days | 90 days | Custom     |
| Other Messages     | 30 days | 90 days | 90 days | Custom     |

If you need to delete specific data or information, reach out to us at [support@novu.co](mailto:support@novu.co).

## Regulatory and PII Concerns

We regularly work with large enterprises and are happy to provide guidance on various compliance requirements. Our compliance reports and certifications are available through our [Trust Center](https://trust.novu.co/) to help ease your security and legal team's review process.

If you have specific concerns about PII, you have several options:

* Use our **open source** version for full control
* Choose the **Novu Hybrid-Cloud** enterprise plan
* Contact us at [sales@novu.co](mailto:sales@novu.co), [support@novu.co](mailto:support@novu.co), or via [Discord](https://discord.novu.co)

## Reporting Security Vulnerabilities

We are committed to our users' data security and highly appreciate responsible disclosure of security vulnerabilities. To report a security issue:

* Submit a [GitHub security advisory](https://github.com/novuhq/novu/security/advisories/new)
* Email us at [security@novu.co](mailto:security@novu.co)


# Agent Toolkit (/platform/build-with-ai/agent-toolkit)

Expose Novu notification workflows as tools for LLM agents with the @novu/agent-toolkit package. Works with OpenAI, LangChain, and Vercel AI SDK.

## What is the Agent Toolkit?

The `@novu/agent-toolkit` package lets you expose [Novu](https://novu.co) notification workflows as tools for LLM agents. It works with **OpenAI**, **LangChain**, and **Vercel AI SDK**.

The toolkit automatically discovers your Novu workflows and converts them into strongly-typed tools that an LLM can invoke, letting your AI agent send notifications, manage subscriber preferences, and trigger any workflow you've built in Novu.

<Callout type="info">
  The Agent Toolkit is a code-level SDK for embedding Novu tools inside your own AI agents. For giving AI coding assistants (Claude Code, Cursor, Copilot) context about Novu, see [Agent Skills](/platform/build-with-ai/skills). For connecting AI tools to Novu via the Model Context Protocol, see [MCP](/platform/build-with-ai/mcp).
</Callout>

## Installation

```bash
npm install @novu/agent-toolkit
```

Then install the peer dependency for the AI framework you use:

| Framework     | Peer Dependency            | Import Path                     |
| ------------- | -------------------------- | ------------------------------- |
| OpenAI        | `openai >= 4.0.0`          | `@novu/agent-toolkit/openai`    |
| LangChain     | `@langchain/core >= 0.2.0` | `@novu/agent-toolkit/langchain` |
| Vercel AI SDK | `ai >= 6.0.0`              | `@novu/agent-toolkit/ai-sdk`    |

## Quick Start

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/openai';
import OpenAI from 'openai';

const openai = new OpenAI();

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Send a welcome email to user-123' }],
  tools: toolkit.tools,
});

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await toolkit.handleToolCall(toolCall);
  console.log(result);
}
```

## Configuration

Every adapter's `createNovuAgentToolkit` accepts a `NovuToolkitConfig` object:

```typescript
type NovuToolkitConfig = {
  secretKey: string;
  subscriberId: string;
  backendUrl?: string;
  workflows?: {
    tags?: string[];
    workflowIds?: string[];
  };
};
```

| Option                  | Required | Description                                                                                                       |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `secretKey`             | Yes      | Your Novu API secret key from [dashboard.novu.co/settings/api-keys](https://dashboard.novu.co/settings/api-keys). |
| `subscriberId`          | Yes      | Default subscriber ID used when triggering workflows.                                                             |
| `backendUrl`            | No       | Custom Novu API URL (defaults to Novu Cloud).                                                                     |
| `workflows.tags`        | No       | Filter discovered workflows by tags.                                                                              |
| `workflows.workflowIds` | No       | Restrict discovered workflows to specific IDs.                                                                    |

## Framework Adapters

Each adapter exposes a `createNovuAgentToolkit` function that returns tools in the native format for that framework.

### OpenAI

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/openai';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools          — OpenAI function tool definitions
// toolkit.handleToolCall — execute a tool call and return a tool message
```

The returned `toolkit` provides:

* **`tools`** — Array of OpenAI-compatible function tool definitions.
* **`handleToolCall(toolCall)`** — Executes a tool call and returns a `{ role: 'tool', tool_call_id, content }` message ready to append to the conversation.

**Full example with tool-call loop:**

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/openai';
import OpenAI from 'openai';

const openai = new OpenAI();
const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

const messages = [
  { role: 'user', content: 'Send a welcome email to user-123' },
];

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages,
  tools: toolkit.tools,
});

const assistantMessage = response.choices[0].message;
messages.push(assistantMessage);

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await toolkit.handleToolCall(toolCall);
  messages.push(result);
}
```

### LangChain

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/langchain';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools — DynamicStructuredTool[] ready for LangChain agents
```

The returned `toolkit` provides:

* **`tools`** — Array of `DynamicStructuredTool` instances that can be passed directly to LangChain agents or executors.

**Example with a LangChain agent:**

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/langchain';
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

const llm = new ChatOpenAI({ model: 'gpt-4o' });

// Pass toolkit.tools directly to agent creation
const agent = await createOpenAIFunctionsAgent({
  llm,
  tools: toolkit.tools,
  prompt: yourPrompt,
});

const executor = new AgentExecutor({ agent, tools: toolkit.tools });
const result = await executor.invoke({ input: 'Notify user-123 about their order' });
```

### Vercel AI SDK

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/ai-sdk';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools — ToolSet compatible with generateText / streamText
```

The returned `toolkit` provides:

* **`tools`** — A `ToolSet` object that can be passed to `generateText`, `streamText`, or other Vercel AI SDK functions.

**Example with `generateText`:**

```typescript
import { createNovuAgentToolkit } from '@novu/agent-toolkit/ai-sdk';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: toolkit.tools,
  prompt: 'Send a welcome email to user-123',
});
```

## Built-in Tools

The toolkit ships with two built-in tools that are always available regardless of which workflows you have configured.

### `trigger_workflow`

Triggers any Novu workflow by its identifier. Use this as a generic entry point to send notifications.

| Parameter       | Type                      | Required | Description                                                     |
| --------------- | ------------------------- | -------- | --------------------------------------------------------------- |
| `workflowId`    | `string`                  | Yes      | The workflow identifier to trigger.                             |
| `payload`       | `Record<string, unknown>` | No       | Data passed to the workflow for rendering notification content. |
| `overrides`     | `Record<string, unknown>` | No       | Provider-specific configuration overrides.                      |
| `subscriberId`  | `string`                  | No       | Target subscriber (defaults to configured `subscriberId`).      |
| `transactionId` | `string`                  | No       | Unique key for deduplication.                                   |

### `update_preferences`

Updates notification channel preferences for a subscriber, either globally or for a specific workflow.

| Parameter      | Type     | Required | Description                                                |
| -------------- | -------- | -------- | ---------------------------------------------------------- |
| `workflowId`   | `string` | No       | Scope to a specific workflow. Omit for global preferences. |
| `channels`     | `object` | No       | Channel toggles: `email`, `sms`, `push`, `inApp`, `chat`.  |
| `subscriberId` | `string` | No       | Target subscriber (defaults to configured `subscriberId`). |

## Dynamic Workflow Tools

On initialization the toolkit fetches your Novu workflows and creates a dedicated tool for each one. These tools are named `trigger_<workflow_id>` (with hyphens replaced by underscores) and include the workflow's payload schema so the LLM knows exactly what data to provide.

Filter which workflows are exposed using the `workflows` config option:

```typescript
const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
  workflows: {
    tags: ['ai-agent'],
    workflowIds: ['welcome-email', 'order-confirmation'],
  },
});
```

For example, if you have a workflow with ID `welcome-email`, the toolkit generates a `trigger_welcome_email` tool whose parameter schema matches the workflow's `payloadSchema`. The LLM sees a purpose-built tool instead of a generic trigger, which improves accuracy and reduces prompt engineering.

## Use Cases

* **Customer support agents** — Let an AI agent send order confirmations, shipping updates, or support ticket notifications through Novu workflows.
* **Internal tooling** — Build Slack bots or internal agents that trigger team notifications, incident alerts, or onboarding workflows.
* **Preference management** — Allow users to manage their notification preferences through a conversational AI interface.
* **Multi-channel broadcasting** — Enable agents to send coordinated notifications across email, SMS, push, in-app, and chat from a single tool call.

## Source Code

The `@novu/agent-toolkit` package is part of the [Novu monorepo](https://github.com/novuhq/novu/tree/next/packages/agent-toolkit) on the `next` branch.

### Package Structure

```
packages/agent-toolkit/
├── src/
│   ├── index.ts              # Main entry point
│   ├── core/                  # Core toolkit classes and types
│   │   ├── novu-toolkit.ts    # NovuToolkit class (initialization, workflow discovery)
│   │   ├── novu-tool.ts       # NovuTool factory function
│   │   └── types.ts           # NovuToolkitConfig, NovuToolDefinition types
│   ├── tools/                 # Built-in tool definitions
│   │   ├── trigger-workflow.ts
│   │   ├── preferences.ts
│   │   └── workflows-as-tools.ts  # Dynamic workflow-to-tool conversion
│   ├── openai/                # OpenAI adapter
│   ├── langchain/             # LangChain adapter
│   └── ai-sdk/                # Vercel AI SDK adapter
├── package.json
├── tsconfig.json
└── tsup.config.ts
```

### Available Exports

| Import Path                     | Description                                              |
| ------------------------------- | -------------------------------------------------------- |
| `@novu/agent-toolkit`           | Core `NovuToolkit` class, `NovuTool` factory, and types. |
| `@novu/agent-toolkit/openai`    | OpenAI adapter with `createNovuAgentToolkit`.            |
| `@novu/agent-toolkit/langchain` | LangChain adapter with `createNovuAgentToolkit`.         |
| `@novu/agent-toolkit/ai-sdk`    | Vercel AI SDK adapter with `createNovuAgentToolkit`.     |
| `@novu/agent-toolkit/core`      | Core classes and types (for building custom adapters).   |


# MCP Server (/platform/build-with-ai/mcp)

Connect your AI tools to Novu using MCP and manage notifications using natural language.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

The Novu MCP Server exposes Novu's notification infrastructure as tools that AI assistants can discover and use in real time.

Once connected, you can use natural language to manage notifications in Novu directly from your AI tool.
For example, you can prompt your AI assistant to:

* Trigger workflows for specific subscribers
* Search and inspect subscriber data
* Update subscriber notification preferences
* Debug failed notifications and delivery issues
* Analyze notification activity and logs
* Create and manage workflows

## How Novu MCP works

The Novu MCP Server exposes your notification system as a set of tools.

When your AI assistant connects:

1. It authenticates using your API key.
2. It discovers available tools.
3. It executes actions based on your prompts.

Instead of calling APIs directly, the AI translates your request into tool calls and executes them against your Novu environment.

## Prerequisite

To use the Novu MCP Server, you'll need:

* A [Novu API key](https://dashboard.novu.co/settings/api-keys)
* An MCP-compatible AI tool (Cursor, Codex, Claude Code, Claude Desktop)

<Callout>Some tools like Claude Desktop require Node.js to run MCP servers locally.</Callout>

## Setup

Follow these steps to setup the Novu MCP server:

### 1. Get your secret key

Your secret key authenticates your AI tool with Novu. To retrieve it:

1. Go to the [Novu Dashboard](https://dashboard.novu.co)
2. Navigate to **API Keys**
3. Under **Secret Keys**, copy your secret key

### 2. Identify your region

Your region determines which URL your AI tool connects to. To identify it, check your dashboard URL:

| Dashboard URL          | Region | MCP URL                          |
| ---------------------- | ------ | -------------------------------- |
| `dashboard.novu.co`    | US     | `https://mcp.novu.co/`           |
| `eu.dashboard.novu.co` | EU     | `https://mcp.novu.co/?region=eu` |

The MCP URL above is what you'll use in the next step when configuring your tool.

### 3. Configure your tool

The following sections cover setup for the most common MCP-compatible AI tools. Before you start, keep two things in mind as you work through the examples:

* **Replace the API key.** Each example uses `your-novu-api-key` as a placeholder. Replace it with the API key you copied earlier.
* **Use the correct URL for your region.** The examples use the US endpoint (`https://mcp.novu.co/`). If you're on the EU region, replace it with `https://mcp.novu.co/?region=eu`.

#### Cursor

Cursor supports remote MCP servers through its built-in settings UI, which writes to an `mcp.json` file. To add the Novu MCP Server:

1. Open **Cursor Settings**, and select **Tools & Integrations**.

2. Under **MCP Tools**, select **New MCP Server**. This opens your `mcp.json` file.

3. Add the following to the `mcpServers` object:
   ```json
   {
     "mcpServers": {
       "novu": {
         "url": "https://mcp.novu.co/",
         "headers": {
           "Authorization": "Bearer your-novu-api-key"
         }
       }
     }
   }
   ```

4. Save the file. Cursor detects the new server automatically.

#### Codex

Codex reads MCP configuration from `~/.codex/config.toml`. The CLI and IDE extension share this file, so you only need to configure the server once. To add the Novu MCP Server:

1. Export your API key as an environment variable in your shell:
   ```bash
   export NOVU_API_KEY="your-novu-api-key"
   ```

2. Open `~/.codex/config.toml` in your preferred text editor and add the following:
   ```toml
   [mcp_servers.novu]
   url = "https://mcp.novu.co/"
   bearer_token_env_var = "NOVU_API_KEY"
   ```

3. Save the file and restart Codex.
   To verify the connection, run `/mcp` inside the Codex TUI. You should see `novu` listed as a connected server.

#### Claude Code

Claude Code manages MCP servers through its `claude mcp` command. To add the Novu MCP Server:

1. In your terminal, run:
   ```bash
   claude mcp add --transport http novu https://mcp.novu.co/ \
     --header "Authorization: Bearer your-novu-api-key"
   ```

2. To make Novu available across all your projects instead of just the current one, add the `--scope user` flag:
   ```bash
   claude mcp add --scope user --transport http novu https://mcp.novu.co/ \
     --header "Authorization: Bearer your-novu-api-key"
   ```

3. Verify the connection by running `claude mcp list`. You can also run `/mcp` inside Claude Code to check server status.

#### Claude Desktop

Claude Desktop connects to remote MCP servers through a local proxy (`mcp-remote`), which requires Node.js 18 or higher. To add the Novu MCP Server:

1. Open Claude Desktop, go to **Settings**, and find the **Developer** section.

2. Select **Edit Config**. This opens your `claude_desktop_config.json` file.

3. Add the following to the `mcpServers` object (or create the object if it doesn't exist):
   ```json
   {
     "mcpServers": {
       "novu": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://mcp.novu.co/",
           "--header",
           "Authorization: Bearer ${NOVU_API_KEY}"
         ],
         "env": {
           "NOVU_API_KEY": "your-novu-api-key"
         }
       }
     }
   }
   ```

4. Save the file and restart Claude Desktop.

#### Other tools

Any MCP-compatible tool can connect to the Novu MCP Server. Use the following connection details:

* **URL**:
  * US: `https://mcp.novu.co/`
  * EU: `https://mcp.novu.co/?region=eu`
* **Transport**: Streamable HTTP (recommended).
* **Authentication**: Send your API key in the `Authorization` header as `Bearer your-novu-api-key`.

## Test your setup

To verify that the connection works, try any of the prompts below in your AI assistant:

```
"Check my Novu API key status"
"Show me all my notification workflows"
"Find subscriber with email user@example.com"
```

If you get results back, the Novu MCP Server is connected and working.

## Available tools

The Novu MCP server currently provides 23 tools for interacting with your Novu environment:

### Core operations

These tools let you inspect your account configuration:

| Tool                 | Description                                   |
| -------------------- | --------------------------------------------- |
| `get_api_key_status` | Check API key status and region configuration |
| `get_environments`   | List development and production environments  |

### Subscriber management

These tools let you create, inspect, and manage your subscribers:

| Tool                | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `create_subscriber` | Create a new subscriber with attributes like name, email, phone, and custom data |
| `get_subscriber`    | Retrieve a single subscriber by their `subscriberId`                             |
| `update_subscriber` | Update an existing subscriber's attributes                                       |
| `delete_subscriber` | Delete a subscriber by their `subscriberId`                                      |
| `find_subscribers`  | Search for subscribers using various query parameters                            |

### Preferences

These tools let you view and update how subscribers receive notifications:

| Tool                            | Description                                                      |
| ------------------------------- | ---------------------------------------------------------------- |
| `get_subscriber_preferences`    | Get subscriber notification preferences for all channels         |
| `update_subscriber_preferences` | Update subscriber notification preferences for specific channels |

### Workflow management

These tools let you create, inspect, and manage notification workflows:

| Tool              | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| `create_workflow` | Create a new workflow with comprehensive configuration including steps |
| `get_workflow`    | Get detailed information about a specific workflow                     |
| `get_workflows`   | Get all available workflows                                            |
| `update_workflow` | Update an existing workflow                                            |
| `delete_workflow` | Delete an existing workflow by its unique identifier                   |

### Triggering and events

These tools let you execute workflows and manage pending notifications:

| Tool                     | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| `trigger_workflow`       | Trigger a workflow to send notifications to a subscriber |
| `bulk_trigger_workflow`  | Trigger multiple workflows in a single API call          |
| `cancel_triggered_event` | Cancel a pending triggered event                         |

### Notifications

These tools let you inspect delivery and execution data:

| Tool                | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `get_notification`  | Get a specific notification by ID with detailed execution logs |
| `get_notifications` | Get notifications and events with advanced filtering options   |

### Integrations

These tools let you manage the channel providers connected to your Novu account:

| Tool                      | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `get_integrations`        | List all channel integrations (email, SMS, push, chat, in-app) |
| `get_active_integrations` | List only the active integrations                              |
| `delete_integration`      | Delete an integration by its `integrationId`                   |
| `set_primary_integration` | Mark an integration as the primary for its channel             |

## Troubleshooting

If your setup isn't working, the following sections cover the most common issues.

<Accordions type="single">
  <Accordion title="Authentication errors">
    * Verify your API key is valid and has no extra spaces or line breaks
    * Check that you're using the correct header format: `Authorization: Bearer your-api-key`
  </Accordion>

  <Accordion title="Empty results">
    Confirm you're using the correct region. If your dashboard is at `eu.dashboard.novu.co`, you need the EU endpoint
  </Accordion>

  <Accordion title="Connection issues">
    * Restart your AI assistant after making configuration changes
    * For Claude Desktop, ensure Node.js is installed and accessible from your terminal
    * For Claude Code, run `claude mcp list` to confirm the server is registered
    * For Codex, run `/mcp` in the TUI to check server status
  </Accordion>
</Accordions>


# Agent Skills (/platform/build-with-ai/skills)

Learn how to use Novu Agent Skills to help AI agents build multi-channel notification systems.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## What are Agent Skills?

Agent Skills are an open standard that gives AI agents (Claude Code, Cursor, Copilot, etc.) the context they need to work with specific tools and platforms. Novu's skills provide AI agents with everything required to build multi-channel notification systems — triggering workflows, managing subscribers, integrating the in-app inbox, and configuring preferences.

## Prerequisites

* A Novu account
* Secret key from [dashboard.novu.co/settings/api-keys](https://dashboard.novu.co/settings/api-keys)

## Setup

Install the Novu skills into your project using the `skills` CLI:

```bash
npx skills add novuhq/skills
```

This pulls the skills from the [novuhq/skills](https://github.com/novuhq/skills) GitHub repository and makes them available to your AI agent (Claude Code, Cursor, Copilot, etc.).

***

## Available Skills

| Skill                                                                                   | Description                                                                |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [trigger-notification](https://github.com/novuhq/skills/tree/main/trigger-notification) | Send single, bulk, broadcast, and topic-based notifications                |
| [manage-subscribers](https://github.com/novuhq/skills/tree/main/manage-subscribers)     | CRUD operations on subscribers and topics                                  |
| [inbox-integration](https://github.com/novuhq/skills/tree/main/inbox-integration)       | Integrate the in-app notification inbox into React, Next.js, or vanilla JS |
| [manage-preferences](https://github.com/novuhq/skills/tree/main/manage-preferences)     | Configure workflow and subscriber notification preferences                 |

## Quick Routing

Use this guide to pick the right skill for your task:

* **"Send a welcome notification"** → `trigger-notification`
* **"Create subscriber"** → `manage-subscribers`
* **"Add a bell icon to my app"** → `inbox-integration`
* **"Let users opt out of emails"** → `manage-preferences`

## Common Combinations

* **Full notification system**: `trigger-notification` + `manage-subscribers`
* **In-app notifications**: `trigger-notification` + `inbox-integration`
* **Complete stack**: all four skills together

## SDK Overview

| Package              | Side   | Purpose                                                             |
| -------------------- | ------ | ------------------------------------------------------------------- |
| `@novu/api`          | Server | Trigger notifications, manage subscribers/topics/workflows via REST |
| `@novu/react`        | Client | React Inbox component, Notifications, Preferences, Bell             |
| `@novu/nextjs`       | Client | Next.js-optimized Inbox integration                                 |
| `@novu/react-native` | Client | React Native hooks-based Inbox integration                          |
| `@novu/js`           | Client | Vanilla JavaScript client for non-React apps                        |

## Skill Reference

### Trigger Notification

Send notifications by triggering Novu workflows. Supports single, bulk, broadcast, and topic-based delivery.

<Tabs items={['Single', 'Bulk', 'Broadcast', 'Topic']}>
  <Tab value="Single">
    ```typescript
    import { Novu } from "@novu/api";

    const novu = new Novu({ secretKey: process.env.NOVU_SECRET_KEY });

    await novu.trigger({
      workflowId: "welcome-email",
      to: "subscriber-123",
      payload: {
        userName: "Jane",
        activationLink: "https://app.example.com/activate",
      },
    });
    ```
  </Tab>

  <Tab value="Bulk">
    Send up to **100 events** in a single request:

    ```typescript
    await novu.triggerBulk({
      events: [
        { workflowId: "welcome-email", to: "subscriber-1", payload: { userName: "Alice" } },
        { workflowId: "welcome-email", to: "subscriber-2", payload: { userName: "Bob" } },
      ],
    });
    ```
  </Tab>

  <Tab value="Broadcast">
    Send to **all subscribers** in the environment:

    ```typescript
    await novu.triggerBroadcast({
      name: "system-announcement",
      payload: { message: "Scheduled maintenance at 2am UTC" },
    });
    ```
  </Tab>

  <Tab value="Topic">
    Send to all subscribers in a topic:

    ```typescript
    await novu.trigger({
      workflowId: "project-update",
      to: [{ type: "Topic", topicKey: "project-alpha-watchers" }],
      payload: { update: "New release deployed" },
    });
    ```
  </Tab>
</Tabs>

**Key trigger parameters:**

| Parameter       | Required | Description                                                    |
| --------------- | -------- | -------------------------------------------------------------- |
| `workflowId`    | Yes      | The workflow identifier (not the display name)                 |
| `to`            | Yes      | Subscriber ID string, subscriber object, or topic target       |
| `payload`       | No       | Data passed to the workflow, validated against `payloadSchema` |
| `overrides`     | No       | Provider-specific overrides per channel                        |
| `transactionId` | No       | Unique ID for idempotency and cancellation                     |
| `actor`         | No       | Subscriber representing who triggered the action               |
| `context`       | No       | Key-value pairs for multi-tenancy / organizational context     |

***

### Manage Subscribers

Subscribers are the recipients of your notifications. Each subscriber has a unique `subscriberId` — typically your application's user ID.

<Tabs items={['Create', 'Retrieve', 'Update', 'Delete', 'Bulk Create']}>
  <Tab value="Create">
    ```typescript
    await novu.subscribers.create({
      subscriberId: "user-123",         // required
      email: "jane@example.com",
      firstName: "Jane",
      lastName: "Doe",
      phone: "+15551234567",
      data: { plan: "pro" },            // custom key-value data
    });
    ```
  </Tab>

  <Tab value="Retrieve">
    ```typescript
    const subscriber = await novu.subscribers.retrieve("user-123");
    ```
  </Tab>

  <Tab value="Update">
    ```typescript
    await novu.subscribers.patch(
      { firstName: "Jane", data: { plan: "enterprise" } },
      "user-123"
    );
    ```
  </Tab>

  <Tab value="Delete">
    ```typescript
    await novu.subscribers.delete("user-123");
    ```
  </Tab>

  <Tab value="Bulk Create">
    Create up to **500 subscribers** in one request:

    ```typescript
    await novu.subscribers.createBulk({
      subscribers: [
        { subscriberId: "user-1", email: "alice@example.com", firstName: "Alice" },
        { subscriberId: "user-2", email: "bob@example.com", firstName: "Bob" },
      ],
    });
    ```
  </Tab>
</Tabs>

**Topics** are named groups of subscribers for group-based notification targeting:

```typescript
// Create a topic
await novu.topics.create({ key: "engineering-team", name: "Engineering Team" });

// Add subscribers
await novu.topics.subscriptions.create(
  { subscriptions: ["user-1", "user-2", "user-3"] },
  "engineering-team"
);
```

***

### Inbox Integration

Add an in-app notification center to your web application. The Inbox provides a bell icon, notification feed, read/archive management, and real-time WebSocket updates.

<Tabs items={['React', 'Next.js', 'Vanilla JS']}>
  <Tab value="React">
    ```bash
    npm install @novu/react
    ```

    ```tsx
    import { Inbox } from "@novu/react";

    function App() {
      return (
        <Inbox
          applicationIdentifier="YOUR_NOVU_APP_ID"
          subscriberId="subscriber-123"
          subscriberHash="HMAC_HASH"  // Required if HMAC encryption is enabled
        />
      );
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```bash
    npm install @novu/nextjs
    ```

    ```tsx
    // components/NotificationInbox.tsx
    "use client"; // Required for App Router

    import { Inbox } from "@novu/nextjs";

    export function NotificationInbox() {
      return (
        <Inbox
          applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID!}
          subscriberId="subscriber-123"
          subscriberHash="HMAC_HASH"
        />
      );
    }
    ```
  </Tab>

  <Tab value="Vanilla JS">
    ```bash
    npm install @novu/js
    ```

    ```typescript
    import { Novu } from "@novu/js";

    const novu = new Novu({
      applicationIdentifier: "YOUR_NOVU_APP_ID",
      subscriberId: "subscriber-123",
    });
    ```
  </Tab>
</Tabs>

**HMAC Authentication** is required in production to prevent subscriber impersonation. Generate the hash server-side:

```typescript
import { createHmac } from "crypto";

const subscriberHash = createHmac("sha256", process.env.NOVU_SECRET_KEY!)
  .update(subscriberId)
  .digest("hex");
```

***

### Manage Preferences

Novu uses a two-level preference system: **workflow defaults** and **subscriber overrides** (set by end users).

**Workflow-level defaults**: Workflow level defaults can be configured in the Novu Dashboard. To do so, click on the workflow you want to configure and then click on the `Manage Preferences` option.

**Subscriber-level overrides**:

<Tabs items={['Workflow level', 'Global level']}>
  <Tab value="Workflow level">
    ```typescript
    await novu.subscribers.preferences.update(
      {
        workflowId: "weekly-newsletter",
        channels: { email: false, inApp: true },
      },
      "subscriber-123"
    );
    ```
  </Tab>

  <Tab value="Global level">
    ```typescript
    await novu.subscribers.preferences.update(
      {
        channels: { email: false, inApp: true },
      },
      "subscriber-123"
    );
    ```
  </Tab>
</Tabs>

**Preference resolution order** (most specific wins):

1. Subscriber workflow preference
2. Subscriber global preference
3. Workflow default
4. System default (all channels enabled)

The `Inbox` component includes a built-in Preferences panel accessible via the settings icon, or use `<Preferences />` as a standalone component.

For additional help, check the [Novu documentation](https://docs.novu.co) or contact us at [support@novu.co](mailto:support@novu.co).


# Integrations (/platform/concepts/integrations)

Learn how Novu integrations connect you to third-party providers

In Novu, integrations are configured connections to third-party services that deliver notifications across supported channels, which are email, SMS, push, and chat.

The In-App channel is handled internally by Novu and does not require a third-party integration.

Each integration connects Novu to a specific provider, which workflows use to deliver notifications over the related channel.

## How integrations fit into the notification flow

Workflows in Novu handle the logic of what message to send and when. Integrations handle how that message is delivered by routing the message through a specific provider.

When a workflow step executes a channel-based action (such as sending an email), Novu:

* Resolves the correct integration for the channel.
* Applies any configuration, such as sender name or title overrides.
* Hands off the message to the provider through the integration.

If no active integration exists for the required channel, the workflow step fails, and no message will be delivered.

## Providers vs integrations

It’s helpful to distinguish between providers and integrations:

* A provider is the third-party service responsible for sending messages (for example, Twilio, SendGrid, Slack).
* An integration is your instance of that provider, configured with the necessary credentials and settings.

You can have multiple integrations for the same provider, for example, using two different SendGrid accounts for staging and production environments. Novu allows you to manage these as separate, named integrations.

Refer to this resource to see the full list of [providerIds used in Novu](https://github.com/novuhq/novu/blob/next/packages/framework/src/shared.ts#L103).

<Callout type="info">Novu also lets you use [Trigger Overrides](/platform/integrations/trigger-overrides) to modify the default behavior of a message during workflow trigger, such as overriding the notification title or content, or using a different integration than the primary integration. This works alongside integrations to fine-tune delivery behavior. </Callout>

## Environment-scoped behavior

Each integration is scoped to a specific environment—such as development, staging, or production. This means you must configure separate integrations for each environment, even if they point to the same provider.

This separation ensures that test messages don’t accidentally go to production users, and different credentials or delivery settings can be safely isolated across environments.

## Primary and active integrations

Each environment can support multiple active integrations per channel, but only one can be marked as the primary integration for email and SMS channels. However, for push and chat channels, all active integrations are used in parallel to deliver messages.

The primary integration serves as the default route when a message is sent over that channel unless explicitly overridden. You can update which integration is marked as primary or deactivate an integration entirely.

## Integration credentials

Integrations require credentials to authenticate with third-party providers. These credentials are encrypted at rest and managed securely within Novu.

Alongside credentials, integrations may also define metadata, such as sender addresses or credentials, including API keys or tokens, as well as optional configuration settings depending on the provider.

## Available integrations

Novu supports a wide range of providers across different channels:

<Cards>
  <Card title="Email" description="Configure email providers and settings" href="/platform/integrations/email" />

  <Card title="SMS" description="Set up SMS messaging capabilities" href="/platform/integrations/sms" />

  <Card title="Push" description="Enable push notification delivery" href="/platform/integrations/push" />

  <Card title="Chat" description="Integrate with chat platforms" href="/platform/integrations/chat" />
</Cards>


# Notification event (/platform/concepts/notification-event)

Learn about the Novu notifications lifecycle and the key entities that make up a notification.

In Novu, notifications are the core building blocks of your product’s communication experience. When your user receives a message via an in-app alert, an email, or a push notification, what they’re seeing is the final output of a notification.

Notifications represent the complete journey of a message triggered by an event in your application and delivered to a specific user across one or more channels. They encapsulate all the execution logic and delivery metadata in a single traceable unit.

## Notification lifecycle

A notification doesn't exist in isolation, it’s the result of a sequence of interconnected entities working together. Here’s how it works in Novu:

<img src="/images/concepts/notifications/notification-life-cycle.png" alt="Notification lifecycle" className="rounded-lg border w-[800px]" />

### Event

Something meaningful happens in your application, such as a user signing up, a password reset being requested, or a comment being posted. You emit this event to Novu using the [Event Trigger API](/api-reference/events/trigger-event).

Each event contains:

* A name that maps to a specific workflow (user\_signed\_up)
* A payload with dynamic data
* One or more subscribers
* Optional overrides or metadata

This is how your application tells Novu, “It’s time to send something.”

### Workflow

Novu matches the incoming event to a predefined workflow. This workflow is your logic for determining:

* What channels to use (email, in-app, SMS, etc.)
* What message templates to render
* When and how messages should be sent

The workflow is where message personalization, conditional logic, and multi-channel orchestration happens.

<Callout title="Want to learn more?" type="info">Refer to the [Workflows documentation](/platform/concepts/workflows).</Callout>

### Notification

Once the workflow starts executing, Novu creates a notification for each subscriber involved. This notification acts as the central entity tracking everything that happens - every job, message, and delivery status. It includes:

* The subscriber details
* The workflow (template) used
* The event payload
* Jobs executed
* Messages generated
* Delivery status updates and errors

Think of it as the container for all activity triggered by a single event for a single user.

<Callout>
  In simpler terms, when a workflow is triggered to a subscriber, it creates an event. One event is one notification.
</Callout>

### Message

Each channel step in the workflow results in one or more messages. These are the actual pieces of content sent to users' emails, push notifications, SMS, and in-app alerts.

Messages are live entities, tracked in real-time, with full visibility into:

* Rendering logic
* Channel used
* Delivery status
* Provider responses or errors

<Callout>Each message has a unique ID and status, learn more about this in the [Messages API](/api-reference/messages/message-schema).</Callout>

## Notification structure

A notification in Novu is more than just a message, it’s a full record of what happened from the moment an event was triggered to when one or more messages were delivered or failed to deliver.

Each notification encapsulates a set of properties that describe its creation, context, execution, and result. These properties are essential for debugging, analytics, and tracking user communications.

### Notification properties

| Property        | Description                                                                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId` | A unique identifier for this specific notification execution run. Useful for tracing across APIs and logs.                                          |
| `template`      | The workflow (template) that was executed. Defines the steps and channels used.                                                                     |
| `subscriber`    | The user who received the notification. Includes subscriber ID and metadata.                                                                        |
| `payload`       | Dynamic data passed in from the event, used to render personalized message content.                                                                 |
| `jobs`          | A list of steps (jobs) that were executed as part of the workflow. Each job corresponds to a workflow action, for example, send email or run delay. |
| `messages`      | The individual messages generated for each channel. Contains delivery status, content, and provider response.                                       |
| `status`        | The current execution state of the notification (`pending`, `completed`, `failed`, and so on).                                                      |

These fields are accessible via the [Notifications API](/api-reference/notifications/list-all-events) and are also displayed in the Novu dashboard’s [Activity Feed](https://dashboard.novu.co/activity-feed) for visual traceability.

## Frequently asked questions

These are some of the most frequently asked questions about notifications in Novu.

### What is the difference between a notification and an event?

A notification is the result of an event. An event is the trigger of a workflow to a subscriber that causes a notification to be created.

### What is the difference between a notification and a message?

One notification event can have multiple messages as per the workflow configuration. Messages are the actual "notification message" to the end user.


# Notification Preferences Concepts (/platform/concepts/preferences)

Learn how to manage subscriber preferences in Novu.

Novu provides a way to store subscriber preferences. This allows subscribers, your users, to specify and manage their preferences and customize their notifications experience.

**Levels of preferences:**

* Workflow channel preferences
* Subscriber channel preferences per workflow
* Subscriber global preferences

## Workflow channel preferences

Each workflow has its own channel preferences. By default, all channel preferences are enabled. If disabled, the subscriber will not receive notifications for that channel step.

Steps to manage workflow channel preferences:

1. Go to the [Workflows page](https://dashboard.novu.co/workflows) in Novu dashboard
2. Click the workflow you want to manage channel preferences for
3. A node-based editor will appear. On the right side of the editor, click the `Configure channel preferences` option
4. Click on the All Channels checkbox to enable or disable all channels for the workflow
5. You will be able to change the preferences for only those steps which are present in the workflow. Non existing channel steps will be disabled.
6. The `Mark as critical` toggle will make this workflow critical. Read more about [critical workflows](#critical-workflows)

<Callout type="info">
  If a workflow has only `in-app` and `email` steps, then it will have only `in-app` and `email` preferences.
</Callout>

![Workflow channel preferences](/images/concepts/preferences/workflow-channel-preferences.png)

### Critical workflows

In some cases, you don't want the subscriber to be able to unsubscribe from mandatory notifications such as Account Verification, Password Reset, etc...

In those cases, you can mark a workflow as `critical` in the workflow channel preferences. Critical workflows are not displayed in subscriber preferences, so subscribers cannot change preferences for that workflow.

## Subscriber global preferences

Subscribers can set global channel preferences, which override individual settings. For instance, if there are 10 workflows, and a subscriber wants to disable SMS notifications for all of them, they can do so with via global preferences.

![Preferences](/images/inbox/preferences@2x.png)

## Subscriber channel preferences per workflow

For each workflow, each subscriber has their own channel preferences. Subscribers can manage these preferences from the <Method href="/platform/inbox/configuration/preferences">{`<Inbox />`}{" "}</Method> Preferences view.

![Subscriber channel preferences](/images/concepts/preferences/subscriber-workflow-preferences.png)

<Callout type="info">Inbox displays only channels present in the current workflow.</Callout>

## Priority of preferences

Since there are three types of preferences, the priority order is as follows:

Workflow channel preferences > Subscriber global preferences > Subscriber channel preferences per workflow

Examples:

1. If the `email` channel is disabled in workflow channel preferences, global and subscriber preferences are ignored, and subscribers will not receive email notifications for this workflow.
2. If the `in-app` channel is enabled in workflow channel preferences but the workflow is marked as critical, subscribers cannot change their preferences and will always receive in-app notifications.
3. If both `chat` and `email` channels are enabled in the workflow but `email` is disabled in subscriber global preferences, the subscriber will receive only chat notifications for this workflow.

## Subscriber preferences APIs

Subscriber preferences can be retrieved and updated using following APIs:

<Cards>
  <Card title="Retrieve subscriber preferences" href="/api-reference/subscribers/retrieve-subscriber-preferences" description="Retrieve subscriber preferences for a subscriber" />

  <Card title="Update subscriber preferences" href="/api-reference/subscribers/update-subscriber-preferences" description="Update subscriber preferences for a subscriber" />
</Cards>


# Subscribers (/platform/concepts/subscribers)

Learn what a subscriber is in Novu, how they’re identified, and how they fit into the notification system.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

In Novu, a subscriber represents a user or system entity that is intended to receive notifications. Subscribers are central to Novu’s delivery model: workflows are triggered with one or more targeted subscribers, and all delivery logic, such as channel routing, preferences, and personalization is applied at the subscriber level.

## How Novu identifies a subscriber

Each subscriber is uniquely identified in Novu by a `subscriberId`. This ID is defined by your application and serves as the reference point for all subscriber-related operations whether sending messages, retrieving preferences, or managing user data.

Unlike email addresses or phone numbers, which may change or be shared across users, the `subscriberId` must remain stable and unique within your system. It acts as the anchor that connects a subscriber’s profile, activity history, and delivery settings across all channels and workflows.

<Callout>Use your application's internal user ID as the `subscriberId` to ensure consistency across your systems.</Callout>

## Subscriber metadata and profile structure

A subscriber’s profile holds all relevant data Novu uses to personalize, deliver, and manage notifications. These fields can power dynamic content in your templates, define conditional logic in workflows, and control which channels a subscriber can receive notifications through.

All metadata tied to a subscriber is centralized and accessible via API or dashboard. This structure ensures that when notifications are triggered, Novu references the most up-to-date context for delivery and personalization.

These data includes:

### User data

Data stored in the subscriber object that you can easily access in your notification templates. This contains basic info such as `email`, `phone`, `firstName`, `locale` and others. This data is fixed and structured.

### Custom data

Apart from the above fixed structured user data, any unstructured custom data such as user's `address`, `membershipLevel`, `preferredTopics`, or `companySize` can also be stored in the `data` field using key-value pairs.

### Channel specific credentials

To deliver messages through push or chat-based channels, Novu also supports storing delivery credentials on the subscriber profile:

* `deviceTokens`: Used to target mobile devices via push notifications.
* `webhookUrl`: Used by chat providers such as, Slack, Discord to reach the subscriber.

These fields ensure Novu can deliver messages reliably to all supported destinations, even when the channel requires platform-specific configuration.

<Callout>Each subscriber channel is limited to a maximum of **100 device tokens**. Requests that exceed this limit will be rejected. See [Platform Limits](/platform/developer/limits) for details.</Callout>

Learn more about subscriber attributes and schema in the [Subscribers API](/api-reference/subscribers/subscriber-schema).

## Subscriber creation in Novu

Before you can send notifications, a subscriber must exist in Novu. Asides from manually creating a subscriber via the Novu dashboard, Novu supports multiple approaches to subscriber creation depending on your application’s architecture and user lifecycle.

### Just in time

Novu allows you to create a subscriber automatically at the moment a notification is triggered. If the subscriber doesn't already exist, Novu uses the information provided in the workflow trigger to create the subscriber on the fly. If the subscriber exists, Novu updates the stored data with the latest values.

This approach is useful when:

* Your system does not store subscriber profiles ahead of time.
* Notifications are sent during real-time events like sign-ups or transactions.
* You want to keep the creation and delivery logic tightly coupled.

```typescript
import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.trigger({
  to: {
    subscriberId: "subscriber_unique_identifier",
    firstName: "Albert",
    lastName: "Einstein",
    email: "albert@einstein.com",
    phone: "+1234567890",
  },
  workflowId: "workflow_identifier",
});
```

### Ahead of trigger

Alternatively, you can create and store subscriber profiles ahead of time — typically during onboarding, registration, or data sync events. This approach allows you to manage subscriber preferences, enrich profiles, and inspect delivery readiness before any notification is triggered.

```typescript
import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.subscribers.create({
  subscriberId: "subscriber_unique_identifier",
  firstName: "Albert",
  lastName: "Einstein",
  email: "albert@einstein.com",
  phone: "+1234567890",
  data: {
    address: "123 Main St, Anytown, USA",
    membershipLevel: "Gold",
    preferredTopics: ["News", "Sports"],
  },
});
```

This is recommended when:

* You want to decouple user creation from notification logic.
* You rely on persistent user data or prefer strict validation before delivery.
* You plan to use advanced segmentation or preference-based delivery.

### Bulk Import

For scenarios like data migration, syncing large lists, or preloading subscribers, Novu supports bulk creation. This is especially useful when integrating with existing systems or importing subscriber data from external sources. Bulk create method supports creating up to 500 subscribers at once.

```typescript
import { Novu } from "@novu/api";
 
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
 
await novu.subscribers.createBulk({
  subscribers: [
    {
      subscriberId: "subscriber_unique_identifier_1",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
    },
    {
      subscriberId: "subscriber_unique_identifier_2",
      firstName: "Isaac",
      lastName: "Newton",
      email: "isaac@newton.com",
      phone: "+1234567891",
    },
  ],
});
```

## Where to manage subscriber data

Subscriber data in Novu can be managed from the Novu dashboard or using the [Subscribers API](/api-reference/subscribers/subscriber-schema). Both offer full access to view, update, and organize subscriber profiles, but they serve different use cases depending on your requirements.

### Dashboard

The Novu dashboard provides a visual interface for exploring and editing subscriber data. It’s useful for:

* Searching and filtering subscribers by ID, email, phone and name.
* Inspecting user profiles, including structured fields, custom data, topic subscriptions and channel preferences.
* Performing manual updates or troubleshooting delivery issues

This is ideal for non technical team members responsible for managing subscribers or teams that want to audit or manage subscriber data without relying on code.

### API

For programmatic control, the Novu API offers endpoints to create, update, delete, and retrieve subscriber records at scale. It supports:

* Automated onboarding or sync processes
* Bulk operations such as imports or exports
* Integration with external systems like CRMs or identity platforms

Use the API when managing subscribers is part of your backend workflows or when changes need to happen dynamically based on user actions.

## Subscriber preferences and personalization

Novu allows each subscriber to define how they want to receive notifications. These preferences influence both the delivery channels and the types of messages a subscriber will receive.

### Global preferences

Subscribers can configure preferences that apply across all workflows. These include:

* Opting in or out of specific channels, for example, email, SMS, push, or in-app
* Disabling notifications altogether

These global settings act as a default and are respected unless explicitly overridden in specific workflows.

### Subscriber workflow specific preferences

In some cases, a subscriber may want to receive certain notifications but only through specific channels. Novu supports fine-grained overrides at the workflow level. This allows you to:

* Adjust channel preferences per notification type
* Honor granular user choices while maintaining global defaults

### Template personalization

Subscriber data, both structured fields such as `firstName`, `email` and custom data can be used to personalize templates. This enables dynamic content such as:

* Greeting users by name
* Including location-based content
* Adjusting language or tone based on locale or membership level

Subscriber preferences and metadata personalization ensure that each subscriber receives relevant, well-targeted messages through the channels they care about.

### Subscriber API reference

<Cards>
  <Card title="Create a subscriber API" href="/api-reference/subscribers/create-a-subscriber" description="Create a new subscriber in Novu" />

  <Card title="Update a subscriber API" href="/api-reference/subscribers/update-a-subscriber" description="Update subscriber attributes for an existing subscriber" />

  <Card title="Bulk create subscribers API" href="/api-reference/subscribers/bulk-create-subscribers" description="Create bulk subscribers in Novu to migrate large number of users" />

  <Card title="Retrieve subscriber subscriptions API" href="/api-reference/subscribers/retrieve-subscriber-subscriptions" description="Retrieve all topics a subscriber is subscribed to" />

  <Card title="Update subscriber credentials API" href="/api-reference/subscribers/update-provider-credentials" description="Update chat and push channel credentials for a single subscriber" />

  <Card title="Update subscriber preferences API" href="/api-reference/subscribers/update-subscriber-preferences" description="Update channel preferences for a single subscriber" />
</Cards>

## Frequently asked questions

These are some of the most frequently asked questions about subscribers in Novu.

### Can two subscribers have the same email address?

Yes, two subscribers can have the same email address, phone number, or any other attributes. However, each subscriber must have a unique subscriberId.

### Do I have to use subscriberId as same as the system userId?

No, you don't need to use the same subscriberId as the system userId. You can use any unique ID as subscriberId. Novu recommends using userId as subscriberId to avoid any confusion. Some of our customers use a pattern like `auth0|userId` as a value for `subscriberId`.

### Can a notification be sent without adding a subscriber?

No, a notification cannot be sent without adding a subscriber. A subscriber is an entity to which notification messages are sent. You must add a subscriber to Novu before triggering the workflow.

### How do I migrate millions of users to Novu?

To migrate millions of users to Novu, use the [Bulk Create Subscribers](/api-reference/subscribers/bulk-create-subscribers) API endpoint. This endpoint allows you to create multiple subscribers in bulk.

### Can subscriber credentials for chat and push channels be added when creating a new subscriber?

Subscriber credentials for Push and Chat channel providers can be added while creating a new subscriber using the `channels` field in the [create subscriber](/api-reference/subscribers/create-a-subscriber) request payload.


# Multi-tenancy Concepts in Novu (/platform/concepts/tenants)

Learn about how to implement multi-tenant notifications in Novu

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';

Multi-tenancy is a common use case for a lot of companies that have multiple organizations that use their applications. In some cases, there is a need to separate the behavior of the notification system depending on the individual tenants.

Tenants are also commonly called workspaces or organizations.

Some of the common multi-tenancy use cases are:

* Group subscribers notification feeds by the tenant
* Adjust the content of the notification depending on the tenant

## How to implement multi-tenancy in Novu

Novu supports multi-tenancy out of the box, the most simple way to implement tenant separation is by prefixing the subscriber identifier with the :tooltip\[tenant identifier]{label="The tenant identifier is a unique identifier for the tenant in your application. Usually the tenant id in your database."}

```typescript
const subscriberId = `${tenantId}:${userId}`;

await novu.trigger({
  workflowId,
  to: {
    subscriberId,
  },
  payload: {
    tenantId,
  },
});
```

### Tenant in Inbox

When using the Inbox feature, you can use the tenant identifier to group notifications by tenant.

```tsx
import { Inbox } from "@novu/react";

function InboxComponent({ tenantId, userId }) {
  return <Inbox subscriber={`${tenantId}:${userId}`} />;
}
```

Each subscriber in a tenant will have it's own unique inbox feed, including a separate preference configuration set.

## Adjusting notification content based on tenant

When triggering a notification, you can pass a custom tenant object or identifier and use it to manipulate workflows or content.

```typescript
const subscriberId = `${tenantId}:${userId}`;

await novu.trigger({
  workflowId,
  to: {
    subscriberId,
  },
  payload: {
    tenant: {
      id: tenantId,
      name: "Airbnb",
      logo: "https://airbnb.com/logo.png",
      primaryColor: "red",
    }
  },
});
```

The tenant object will be available to use in the workflow editor as a variable for the following areas:

* Content (use `{{payload.tenant.name}}` to display the tenant name in an email or any other channel)
* Step Conditions (use `{{payload.tenant.id}}` to conditionally execute a step based on the tenant)
* Use the Inbox [data object](/platform/inbox/configuration/data-object) to filter notifications by tenant.

## Frequently asked questions

The following are the frequently asked questions about multi-tenancy in Novu.

### Can I use a different delivery provider for each tenant?

Currently, we do not support using a different delivery provider for each tenant. You can reach out to [support@novu.co](mailto:support@novu.co) in case this is a feature required for your use case.

### Can I specify different workflow preferences for each tenant?

We don't support specifying different workflow preferences for each tenant. You can reach out to [support@novu.co](mailto:support@novu.co) in case this is a feature required for your use case.


# Topics in Novu (/platform/concepts/topics)

Learn how topics work in Novu and how they help you organize and target groups of subscribers efficiently.

In Novu, a *topic* is a way to group subscribers under a shared label so that you can broadcast a message to many users with a single workflow trigger. This fan-out mechanism removes the need to manage individual subscriber IDs for each notification, streamlining scenarios like product announcements, feature rollouts, or status updates.

## Topics identifiers

Each topic is uniquely identified by a topic key, a permanent, internal reference in your system. You can also assign a name to help describe its purpose, for example, "Task Updates" or "Comment Thread Subscribers".

The `topicKey` must be unique and cannot be changed after creation; Novu enforces this uniqueness behind the scenes. Example: `task:taskId` or `post:postId`.

Common use cases for topics:

* Notifying all members of a specific team or project
* Messaging users who commented on a post
* Updating subscribers to a specific product or feature

## How topics fit into Novu's model

Novu’s notification system is built around workflows, which are triggered for one or more recipients. Topics act as a special type of recipient, representing a group of subscribers instead of an individual.

When you trigger a workflow using a topic:

* The `to` field accepts the topic’s key.
* Novu looks up all subscribers assigned to the topic.
* A separate workflow event is created for each subscriber.

Topics let you target large groups with a single API call, removing the need to loop through subscribers or send multiple workflow triggers.

<Callout>Topics don’t replace individual targeting. You can still trigger workflows for specific subscribers or arrays of subscribers when needed.</Callout>

## Dynamic and decoupled grouping

Once a topic is created, you can assign or remove subscribers at any time. Subscribers don’t need to know they belong to a topic, and it doesn’t affect their personal notification preferences.

Topics are dynamic and reflect real-time states. For example, a topic might include:

* Users who are currently watching a post
* Team members assigned to a project

This makes topics especially useful for modeling dynamic relationships in your application.

## Scalability and limits

Topics are designed for high-volume, high-efficiency use cases:

* Each topic supports up to 100,000 subscribers.
* A separate workflow event is created for each subscriber when a workflow is triggered to the topic

## Autogenerated topics

Novu supports on-the-fly topic creation. If you attempt to add subscribers to a topic key that doesn't exist for the selected environment and organization, Novu will automatically create a new topic named `Autogenerated-<TOPIC_KEY>` and assign the subscribers to it. This auto-generated topic can then be renamed and managed just like any other topic created manually.

<Callout type="info">
  Topics can be managed from [Novu dashboard](https://dashboard.novu.co/topics) or using [Topics APIs](/api-reference/topics/topic-schema)
</Callout>

## Trigger workflow

As mentioned above, a workflow can be triggered to a topic in the same way as it is triggered to subscribers.

### To a single topic

To trigger a workflow to a topic, use `to` field with type `Topic` and topicKey.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      to: { type: "Topic", topicKey: "topic_key" },
      workflowId: "workflow_identifier",
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": {
            "type": "Topic",
            "topicKey": "topic_key"
        }
    }'
    ```
  </Tab>
</Tabs>

### To multiple topics

`to` field also accepts array of topics. This is useful when you want to trigger a workflow to multiple topics at once.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      to: [
        { type: "Topic", topicKey: "topic_key_1" }, 
        { type: "Topic", topicKey: "topic_key_2" }
      ],
      workflowId: "workflow_identifier",
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": [
          {
              "type": "Topic",
              "topicKey": "topic_key_1"
          },
          {
              "type": "Topic",
              "topicKey": "topic_key_2"
          }
        ]
    }'
    ```
  </Tab>
</Tabs>

### Exclude actor

When a workflow is triggered to a topic, notification is sent to all subscribers present in the topic. However, you can exclude a specific subscriber from receiving the notification by using the `actor` field. Here actor is the subscriberId of the subscriber you want to exclude.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      to: [{ type: "Topic", topicKey: "topic_key_1" }],
      workflowId: "workflow_identifier",
      actor: "actor_subscriber_Id"
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": [
          {
              "type": "Topic",
              "topicKey": "topic_key_1"
          }
        ],
        "actor": "actor_subscriber_Id"
    }'
    ```
  </Tab>
</Tabs>

## Explore the topics APIs

These are commonly used topics APIs. Explore all topics APIs on topics [api reference page](/api-reference/topics/topic-schema).

<Cards>
  <Card title="Create a topic API" href="/api-reference/topics/create-a-topic" description="Create a new topic with name and topicKey" />

  <Card title="Update a topic API" href="/api-reference/topics/update-a-topic" description="Update existing topic using topicKey" />

  <Card title="Create topic subscription API" href="/api-reference/topics/create-topic-subscriptions" description="Add multiple subscribers into a topic" />

  <Card title="List topic subscriptions API" href="/api-reference/topics/list-topic-subscriptions" description="List all subscribers present in a single topic" />

  <Card title="List all topics API" href="/api-reference/topics/list-all-topics" description="List all topics in an environment" />

  <Card title="Check subscriber subscription API" href="/api-reference/topics/check-topic-subscriber" description="Check if a subscriber is present in a topic" />
</Cards>

## Frequently asked questions

Below are some of the most frequently asked questions about topics:

### Do topics override subscriber preferences?

No. Topics only define delivery groups. Each subscriber’s individual notification preferences remain intact.

### Is a topic like a mailing list?

Conceptually, yes. Topics group users to receive shared messages. However, topics are more dynamic and integrated into your application logic.

### Can a subscriber belong to multiple topics?

Yes. Subscribers can be members of any number of topics. This allows overlapping targeting strategies (for example, `task-updates`, `project-X`, and `admin-notifications`).

### Can I reuse the same topic key across environments?

Topic keys must be unique within each [environment](/platform/developer/environments). You can reuse the same key (for example, `feature-release`) in different environments like staging and production.

### What happens if I trigger a workflow to a topic with no subscribers?

The workflow is processed, but no notifications are delivered and, hence, this trigger is not counted for billing.


# Triggering Workflows (/platform/concepts/trigger)

Managing Trigger Events from Request to Processing

## Trigger Request

A trigger request is the initial step in handling a trigger event. It contains crucial details such as the template identifier, a list of subscribers who will receive the notification, the payload of the notification, and any overrides that need to be applied.

## Trigger Endpoint

Upon sending the request to the [event/trigger](/api-reference/events/trigger-event) endpoint, a series of essential steps are initiated:

1. **Subscriber Mapping and Validation:** The first step involves mapping and validating the subscribers for the specified event. This ensures that notifications are sent to the correct recipients.

2. **Workflow Validation:** Following subscriber validation, the workflow associated with the event is validated. This validation process considers factors such as the active status to determine if it meets the necessary criteria for processing.

3. **Attachment Upload:** Once the validation process is successfully completed, any attachments associated with the event are uploaded to the designated storage service.

4. **Event Queuing:** The trigger event, now enriched with mapped subscribers and attachment links, is appended to the **trigger event queue**. This queuing mechanism optimizes response times, ensuring efficient event processing.

## Trigger Event Processing

When an event is picked up by the **trigger queue worker**, the processing phase begins. Here's what happens:

* **Subscriber Upsert:** The worker validates the subscribers associated with the event and either creates or updates the subscriber with the information passed in the `to` object.
* **Notification Entity Creation:** For each subscriber listed in the trigger event, a corresponding notification entity is created. This entity contains essential data related to the organization, template, subscriber, and event payload.
* **Job Creation:** Based on the notification template's defined steps, jobs are generated. These jobs are responsible for carrying out specific tasks related to the event notification. Additionally, the notification entity is updated with a "channels" field generated from these steps, indicating the communication channels through which notifications will be sent.

## Jobs

Jobs play a crucial role in the trigger event lifecycle. They are created based on the steps outlined in the workflow.

### Job Statuses

| Status        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PENDING**   | This status is assigned to a job before it is added to the worker queue. It indicates that the job is waiting to be processed.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **QUEUED**    | After the initial validation and just before adding a job to the worker queue, it is set to `QUEUED`. This status signifies that the job is ready for processing but is awaiting its turn in the queue.                                                                                                                                                                                                                                                                                                                                              |
| **RUNNING**   | When a job is picked up by a worker from the queue, its status is changed to `RUNNING`. This indicates that the job is currently being processed by a worker.                                                                                                                                                                                                                                                                                                                                                                                        |
| **COMPLETED** | Once a job has been successfully executed and processed, its status is changed to `COMPLETED`. This signifies that the job has been successfully completed.                                                                                                                                                                                                                                                                                                                                                                                          |
| **FAILED**    | If a job encounters an issue during processing or execution, its status is changed to `FAILED`. This indicates that the job has not been successfully completed, and there may have been errors or problems during processing.                                                                                                                                                                                                                                                                                                                       |
| **DELAYED**   | The `DELAYED` status is applied to specific types of jobs, such as `digest` or `delay` jobs, to indicate that they are delayed and not immediately processed. For `digest` jobs, it means that the digesting process is running or scheduled for a later time. For `delay` jobs, it signifies that the job is set to be executed at a specified delay time.                                                                                                                                                                                          |
| **CANCELED**  | When a job is canceled for any reason, its status is set to `CANCELED`. This indicates that the job will not be processed further and is effectively removed from the processing queue.                                                                                                                                                                                                                                                                                                                                                              |
| **MERGED**    | The `MERGED` status is assigned to events that are part of a `digest`. It indicates that an event will be merged into the digesting event. In a digesting process, there is typically a primary or initial event that serves as the digesting event, and subsequent events are merged into it. Instead of having a separate `COMPLETED` status for these merged events, they are marked as `MERGED` to indicate their specific role in the digesting process.                                                                                        |
| **SKIPPED**   | The `SKIPPED` status is used in the context of backoff versions of digesting. In this scenario, the first event's digesting is skipped, and the second event takes on the digesting role. The `SKIPPED` status is applied to the first event's digesting, indicating that it was intentionally skipped in the digesting process. Subsequent events may be merged into the second event's digesting process, as explained with the `MERGED` status. The `SKIPPED` status helps differentiate the skipped event from others in the digesting sequence. |

## Frequently asked questions

### What is an event?

An event is a request (for instance, an API call to [/v1/events/trigger](/api-reference/events/trigger-event)) that starts off an action in the Novu Workflow Engine. Events can make many different types of actions, including digests, delays, and sending notifications to various channels, as well as filters and user preference checks.

### How events are billed?

If a workflow is triggered to a [subscriber](/platform/concepts/subscribers), then it is billed as 1 event. So if workflow is triggered to group of 15 subscribers, then it is billed as 15 events. Similary, if a workflow is triggered to a [topic](/platform/concepts/topics), Novu creates one event per topic subscriber, this means that a workflow trigger to a topic with 100 subscribers creates 100 events.

### If notifications were filtered out, are they still billed?

Yes, they are still billed. The number of billed events is the number of subscribers or topic subscribers the workflow was triggered to, regardless of whether notifications were filtered out as per subscriber's [workflow channel preferences](/platform/concepts/preferences#workflow-channel-preferences), [global channel preferences](/platform/concepts/preferences#subscriber-global-preferences) or [step conditions](/platform/workflow/add-and-configure-steps/step-conditions).

### How events are billed for digested events?

As a workflow triggered to one subscriber is billed as 1 event. if events are digested 15 times and a single digested notification is sent, then 15 events will be billed.


# Workflows (/platform/concepts/workflows)

Learn what workflows are and how they work in Novu.

In Novu, a workflow is the blueprint that defines the end-to-end process for delivering a notification to one or more subscribers. It acts as the central logic layer for routing messages across different channels such as email, SMS, in-app, push, or chat and controlling what notification to send, when to send it and through which channels they are sent.

You can think of a workflow as a CI/CD pipeline for notifications or an assembly line:

* The event enters at the start.
* The logic defines how it moves through conditions, waits, and transformations.
* Each step performs a specific action.
* At the end, the user receives one or more messages based on the outcome.

Workflows can be simple:

* When a user signs up, send them a welcome email.

Or complex:

* When a payment fails, wait 30 minutes, check the user type, then send an email and an in-app message. If no response in 24 hours, follow up with an SMS message.

It can also be extended further than these depending on your use case.

## Workflow steps

A workflow in Novu is built as a sequence of steps, each representing a distinct action or delivery mechanism. These steps are the building blocks of your notification logic. They determine what happens, when it happens, and how the message is sent to the user.

You define and arrange steps using the Workflow Editor in the Novu dashboard, where each node on the canvas represents a single step in the execution flow.

Each step operates independently, meaning that if one step fails, others can still succeed. This makes workflows both modular and fault-tolerant.

### Types of steps

Each workflow can contain two types of steps: channel steps and action steps.

#### Channel steps

Channel steps deliver the actual notification through one of Novu’s supported channels. Each step contains its own notification template, content editor, and channel-specific settings.

Supported channel types include:

* Email (SendGrid, Mailgun, or SMTP)
* In-App (Inbox component)
* SMS (Twilio)
* Push (FCM, OneSignal)
* Chat (Slack, Microsoft Teams)

<Callout title="Note" type="warn">
  A channel step only runs if:

  * The subscriber has `email` field for `email` step, `phone` field for `sms` step and required credentials for `push` and `chat` channel steps.
  * A valid integration is configured for that channel in the environment.
</Callout>

#### Action steps

These steps allow you to introduce logic and flow control into the workflow. They don’t send notifications, but instead alter the timing or shape of the delivery pipeline.

Common action steps include:

* **Delay**: Pause the workflow for a fixed amount of time before moving to the next step.
* **Digest**:  Group multiple similar events into a single message (for example “You have 5 new mentions”).

### Designing multi-channel sequences

Because steps are chainable, you can build complex notification sequences such as:

1. Send an in-App message.
2. Wait 24 hours (Delay).
3. If the in-app message is unread, send an email.
4. If the subscriber is a premium user, then follow up with an SMS message.

This allows Novu workflows to adapt to user behavior and preferences while keeping the configuration visual and testable.

## Workflows editor

All workflows in Novu are defined within the Workflow Editor, accessible via the Novu dashboard. This visual builder let's you define the sequence of steps such as sending emails, SMS, or in-app notifications that happen when a notification event is triggered.

Workflows created in the dashboard run via Novu’s Shared Bridge Endpoint, a centralized infrastructure that securely handles workflow execution for all customers. This means that your app doesn’t need to manage orchestration logic; Novu takes care of triggering, step execution, retries, and delivery flow behind the scenes.

<Callout type="info">
  While most users rely on the Shared Bridge Endpoint, Novu allows advanced users to host their own Bridge application and define workflows in code using the [Novu Framework](/framework).
</Callout>

To learn more about building workflows using the workflow editor, filters, and personalizing templates, refer to the [Building Workflows documentation](/platform/workflow).

## Workflow identifier

Each workflow has a unique `identifier` used to reference it during API calls. While the workflow name can be changed, the workflow identifier becomes immutable after creating the workflow.

Workflow identifiers must be unique within one environment and are typically lowercase with hyphens (for example, `order-confirmation`).

<Callout type="info">
  When naming a workflow, choose a clear, descriptive name that reflects its purpose. This name helps teams distinguish between multiple workflows and maintain clarity as your notification system grows.
</Callout>

## Workflow status

Workflows can exist in one of three states:

| **Status**        | **What it means**                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `active`          | The workflow is ready to be triggered. Steps are valid, templates are complete, and all required integrations are connected.  |
| `inactive`        | The workflow is paused. It cannot be triggered, but you can still edit its structure or steps.                                |
| `action required` | The workflow contains one or more errors, such as missing required fields or unconnected channels. It can still be triggered. |

## Workflow tags

Tags are labels that help you organize and group workflows. They don’t affect delivery, but they play a major role in how notifications are filtered, displayed, or managed by both your app and your users via the Inbox component.

Use tags to:

* Group related notifications, for example, `security`, `account-activity`, and `marketing`.
* Support filtered views on your frontend; for example, show only promotional messages.
* Categorize workflows for better team visibility and long-term maintainability.

Think of tags as your notification system's folders; they help your team stay organized.

### Example use cases:

* Show only `security` tagged notifications in a high-priority tab.
* Let users mute or opt out of `marketing` tagged workflows via preferences.
* Organize large numbers of workflows by function, region, or product area.

## Critical workflows

Critical workflows are notifications that must always be delivered to users, regardless of their personal preferences. These workflows are essential to the user experience and system integrity, and users cannot disable them through notification settings.

Marking a workflow as critical ensures that high-priority messages are delivered without exception. This is particularly important for notifications that carry security, financial, or access-related information, where missing a message could have some consequences.

Examples of critical workflows include:

* **Security alerts**: Password resets or suspicious login attempts.
* **Invitations**: Granting users access to workspaces, projects, or systems.
* **Onboarding flows**: Guiding new users through setup steps.
* **Payment and billing updates**: Confirmations or failed transactions.
* **Order and shipping notifications**: Providing delivery status or tracking details.

## Syncing workflows between environments

In Novu, syncing a workflow means copying it from one environment (typically development or staging) to another (such as production). This is how you deploy workflow changes without having to rebuild them manually across environments.

Instead of editing workflows directly in production, it's best practice to design and test them in a non-production environment first. Once validated, you can sync the workflow to production with a single action.

### When a workflow is synced:

* A copy is created or updated in the target environment.
* The workflow identifier remains the same, ensuring existing triggers continue to function correctly.
* Any updates to the template, steps, or configuration are reflected in the destination environment.

### Syncing is supported across environments based on your plan:

* Team and enterprise plans support syncing to any available environment.
* Lower-tier plans support syncing only between development and production.

## Triggering workflows

Every workflow in Novu is initiated by a trigger, which can be an external event or action that starts the notification flow. Triggers connect real-world events, such as a comment being posted or an order being placed, to a specific workflow using a unique identifier, the `workflowId`.

When you trigger a workflow, you send event data, including subscriber information, payload details, and optional overrides, to Novu’s API. Novu then validates the event, processes it, and orchestrates notification delivery across your defined channels.

Behind the scenes, Novu manages the full lifecycle: subscriber validation, workflow matching, attachment uploads (if applicable), queuing, job execution, retries, and status tracking.

To learn more about triggering workflows via API, handling payloads, and understanding the request lifecycle, refer to [Triggering Workflows](/platform/concepts/trigger).

## Workflow activity feed

After a workflow is triggered, Novu tracks the full execution process in the [Activity Feed](https://dashboard.novu.co/activity-feed). The feed gives you real-time visibility into each step, helping you debug issues, trace delivery problems, and understand how notifications behave in production. Each environment has its separate feed.

You can filter the Activity Feed by workflow name, channel type, time period, or transaction ID to easily find and inspect specific workflow executions.

## Workflow channel preferences

When setting up a workflow, you can define channel preferences that determine how notifications are delivered to subscribers. In the Novu dashboard, you can set default preferences for each workflow, specifying which channels, such as email, in-app, SMS, or push, should be used by default during notification delivery.

These defaults ensure that subscribers receive messages through the most appropriate channels, even if they haven’t customized their own preferences. To learn more about channel preferences, refer to [preferences](/platform/concepts/preferences).

## Workflow step conditions

Step conditions in Novu are used to control whether a step in your workflow should be executed, based on dynamic logic. This lets you create more intelligent and personalized workflows that respond to dynamic user and application data.

Conditions can be based on subscriber fields, payload data, or the results of previous steps. For example, you might skip sending an SMS if the user is already online, or send a follow-up email only if an in-app message hasn’t been read within 24 hours.

To learn more about all supported condition types, operators, and usage example, refer to the [Step Conditions documentation](/platform/workflow/add-and-configure-steps/step-conditions).

## Frequently asked questions

These are some of the most frequently asked questions about workflows in Novu.

### Do I have to create a workflow to send notifications?

Yes, creating a workflow is mandatory to send notifications.

### Can workflows be created and managed via code?

Yes, workflows can be managed via code, if you are using Node.js, you can use the [Novu Framework](/framework/introduction)

### Can all workflows be synced at once to another environment?

Currently, only a single workflow can be synced at a time.


# API Keys Management (/platform/developer/api-keys)

Manage authentication credentials and connection endpoints for your Novu integration.

Novu provides a set of keys and hostnames that your application uses to authenticate requests, send events to the Novu API, and to interact with the <Method href="/platform/inbox">{`<Inbox />`}</Method>.

Your API keys are environment specific and allow Novu to tie all request to a particular Novu environment.

## Finding your API keys

Follow these steps to find your environment-specific API keys:

1. Login to the Novu dashboard.
2. On the developer section, click **API Keys** to find all your environment keys, whiich are:
   * Application Identifier
   * Secret Keys
   * API URLs
     ![API Keys](/images/developer-tools/api-keys.png)

## Application identifier

The Application Identifier is a unique identifier for your application within Novu. It is considered a public key and is safe to expose in client-side code.

The application identifier is used to initialize the <Method href="/platform/inbox">{`<Inbox />`}</Method> component.

## Secret key

The Secret Key is a private token used to authenticate and authorize requests sent to the API service. It proves that your application is allowed to access resources.

This key grants full administrative access to your account. It should never be used in publicly accessible code, such as frontend applications or public repositories (GitHub, GitLab).

<Callout type="error"> Keep your secret key private.</Callout>

You can regenerate the secret key from the API Keys dashboard. This will invalidate the old key and require you to update your environment variables.

## API URLs

The following hostnames are used to connect to the Novu cloud platform.

| **Endpoint**           | **URL**               | **Description**                                                                                                                          |
| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **API Hostname**       | `https://api.novu.co` | The domain that your application sends API requests to. It identifies the Novu API server.                                               |
| **WebSocket Hostname** | `https://ws.novu.co`  | The domain used to establish a WebSocket connection. Similar to the API Hostname, but specifically for real-time, two-way communication. |


# Environment Variables in Novu (/platform/developer/environment-variables)

Create reusable, environment-scoped variables in the dashboard and reference them in workflows.

Environment variables in Novu are named values you define once in the dashboard and reuse across workflows. Each [Novu environment](/platform/developer/environments) can hold its own value for the same variable, so Development and Production (and any custom environments) stay isolated without duplicating workflow logic.

Environment variables help you avoid hardcoding URLs, feature flags, or copy in every step, and give you a single place to update shared configuration when something changes.

<Callout type="info">
  This feature is available in [PRO](https://novu.co/pricing) and higher plans.
</Callout>

## What you can do

* Define variables with a **key** and a value per environment.
* Reference variables in workflow content with Liquid using the `env` namespace.
* See when a variable is missing in an environment so you can fix it before executions fail or behave unexpectedly.

## Create and manage variables

1. Log in to the [Novu dashboard](https://dashboard.novu.co).
2. Open **Environment variables** from the developer area of the dashboard (same general area as API keys and other workspace settings).
3. Create a variable: set the **key**, and enter the value for each environment that should have one.
4. Save. Workflows that reference the key pick up the current value for the environment where the workflow runs.

![Create and manage variables](/images/platform/environment-variables/create-a-variable.gif)

You can update values per environment, rotate secrets by replacing the stored value, or remove a variable when it is no longer needed. After you change a value, the next workflow executions use the new value without editing individual steps.

### Values per environment

Each environment stores its own value for a given key. For example, the same variable might point to a staging API base URL in Development and a production URL in Production. You configure both from the environment variables screen, often in one table so you can compare environments side by side.

If a variable has no value in an environment where a workflow references it, Novu can surface a warning on the Environment variables page (for example when a value is missing in one environment but set in others) and in workflow step preview or execution context, so you can add or correct the value before relying on it in production.

## Reference variables in workflows

Use Liquid with the `env` namespace. Keys are case-sensitive: use the same spelling and capitalization as in the dashboard when the variable was created, character for character. For example:

```liquid
{{ env.MY_API_BASE_URL }}
```

![Using variables in workflows](/images/platform/environment-variables/using-variable-in-email.gif)

You can use these references anywhere Novu accepts Liquid syntax, including:

* Channel step editors
* HTTP request steps (URL, headers, body)
* Layouts
* Step conditions and other Liquid-enabled fields

The preview context in the dashboard can list the environment variables available for the current environment, which makes it easier to pick the correct key while editing.

## Use cases

**Shared API base URL**\
Store the base URL for an internal or partner API in one variable. Point Development at a sandbox host and Production at the live host. Every HTTP step or template uses `{{ env.PARTNER_API_URL }}` so a host change is one dashboard edit, not a sweep through every workflow.

**Feature flags and toggles**\
Keep a simple string or flag value in a variable and branch conditions or template copy on it. Product or ops can flip behavior per environment without opening the workflow graph.

**Credentials for HTTP steps**\
Put bearer tokens or API keys in secret variables and reference them in HTTP step headers. The value never appears in plain text in the UI after save, but workflows can still send authenticated requests.

**Consistent branding or legal text**\
Store support email, terms link, or footer line in variables so marketing updates the text in one place and all templates stay aligned.

**Multi-workflow consistency**\
When several workflows call the same external system or use the same webhook path, one variable avoids drift between copies of the same string.

## Related documentation

* [Environments](/platform/developer/environments) for how Development, Production, and custom environments differ.
* [Personalize content](/platform/workflow/add-notification-content/personalize-content) for more on Liquid and template variables beyond `env`.


# Environments (/platform/developer/environments)

Understanding and managing environments in Novu

Novu uses environments to separate your workflows and its data. This lets you safely test changes, like a new workflow, in one environment before moving it to a live production environment.

## Types of environments

When you create a Novu account, you are provided with a development and production environment by default. On certain plans, you can also create custom environments to match your team’s workflow.

* **Development environment**: Use the development environment to build and test new workflows, layouts, translations, and experiment with different configurations before publishing to other environments.
* **Production environment**: The production environment is used to send notifications to your subscribers. To ensure stability and prevent unintended changes, this environment is view-only for workflows, layouts, and translations. Changes are not made here directly, they are made from other environment and then published to this production environment.
* **Custom environment**: Custom environments are only available on <a href="https://novu.co/pricing" target="_blank" rel="noopener noreferrer">Team and Enterprise plans</a>. You can use them to reflect your release process, for example, staging or QA.

## Create a custom environment

To create a custom environment:

1. Log in to the Novu dashboard.
2. Go to the [Environments page](https://dashboard.novu.co/environments) in the Novu dashboard.
3. Click **Create environment**. A menu appears.
4. Enter your preferred environment name in the **Name** field.
5. Assign unique colors to easily distinguish between environments.
   ![Publish changes](/images/developer-tools/create-environment.png)
6. Click **Create environment**.
   The new environment is created and is available in the environments list.

## What's unique to each environment?

Each environment in Novu has it's own isolated resources, while the development environment has assets that can be published to other environments.

Each environment maintains some isolated set of resources, while you can share or promote other assets through publishing.

### Environment-specific resources

These resources are completely separate and unique to each environment. Data in one environment has no connection to data in another. They are:

* Activity feed
* API keys (application identifier and secret key)
* Integrations (Provider credentials)
* Subscribers
* Topics
* Webhooks

### Publishable assets

These assets are managed centrally in the development environment and then published to other environments.

* Layouts
* Translations
* Workflows

### Environment credentials

Each environment has two unique identifiers:

* **Application Identifier**
  * Public ID for client-side apps
  * Used with <Method href="/platform/inbox">{`<Inbox />`}</Method>
  * Different for each environment
  * Safe to expose in frontend code

* **API Secret Key**
  * Used for backend API authentication
  * Keep this secure and never expose publicly
  * Different for each environment

<Callout>Configure these credentials in your application based on the active environment, similar to how you manage other service credentials.</Callout>

## Publish changes to other environments

Novu provides a publish mechanism that allows you to promote changes from your development environment to production or other custom environments. This process ensures that all changes are deliberate, reviewed, and deployed in a controlled manner.

The publishing process bundles all modifications made to workflows, layouts, and translations since the last publish event.

You can promote changes to other environments by following these steps:

1. Ensure you are in the **Development** environment. All changes must originate from here.
2. Click **Publish changes**. A list of available environments appears.
   ![Publish changes](/images/developer-tools/publish-changes.png)
3. Select the environment that you want to publish to.
   ![Publish changes](/images/developer-tools/list-of-environment.png)
4. Select the checkboxes next to the workflows that you want to publish. A menu appears, showing all the available workflows.
   ![Publish changes](/images/developer-tools/publish-changes-modal.png)
5. Click the publish button to publish the selected workflows to the selected environment.


# System Limits and Quotas (/platform/developer/limits)

System limits, quotas, and constraints for the Novu platform.

Novu enforces default limits on specific resources and configurations. These limits apply to all new accounts by default as per subscription plan.

| Resource                             | Free    | Pro     | Team    | Enterprise |
| ------------------------------------ | ------- | ------- | ------- | ---------- |
| Workflows                            | 20      | 20      | 100     | Custom     |
| Layouts                              | 1       | 100     | 100     | Custom     |
| Steps per workflow                   | 20      | 20      | 20      | Custom     |
| Context per trigger                  | 5       | 5       | 5       | Custom     |
| Environments                         | 2       | 2       | 10      | Custom     |
| Delay duration                       | 1 day   | 7 days  | 30 days | Custom     |
| Digest duration                      | 1 day   | 7 days  | 30 days | Custom     |
| Throttle duration                    | 1 hr    | 24 hrs  | 7 days  | Custom     |
| Inbox feed retention                 | 30 days | 90 days | 90 days | Custom     |
| Activity feed retention              | 1 day   | 7 days  | 90 days | Custom     |
| Team members                         | 3       | 3       | Custom  | Custom     |
| Device tokens per subscriber channel | 100     | 100     | 100     | Custom     |
| Environment variables                | -       | 10      | 10      | Custom     |

Reach out to us at [support@novu.co](mailto:support@novu.co) if you are looking for a custom limit.

## Frequently Asked Questions

### What happens if I exceed the default workflow or step limit?

Exceeding the default limit may result in restricted functionality or errors. We recommend upgrading to a higher plan to avoid any restrictions. [Contact support](mailto:support@novu.co) to help with the upgrade.

### Is there a cost associated with custom limits?

Custom limits may incur additional costs depending on the resources required. [Support](mailto:support@novu.co) will provide details during the approval process.


# Headless mode (/platform/inbox/headless-mode)

Learn how to build custom Inbox UI for your application using Novu custom hooks

Build a fully custom notification inbox with Novu's headless React hooks without being constrained by the default <Method href="/platform/inbox">{`<Inbox />`}</Method> UI or dependencies.

The [**`@novu/react`**](/platform/sdks/react) package provides a set of hooks, such as `useNotifications` and `useCounts`. You handle the layout, styling, and interactions, while Novu provides the notification state, real-time updates, and actions.

<Callout type="info">
  Not using React? You can access the same data manually using the [JavaScript SDK](/platform/sdks/javascript).
</Callout>

## Install the React SDK package

Run the following command in your terminal:

<Tabs groupId="package-manager" persist items={}>
  <Tab value="npm">
    ```bash
    npm i @novu/react
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @novu/react
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @novu/react
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @novu/react
    ```
  </Tab>
</Tabs>

## Add the `NovuProvider`

Wrap your application or the components that need access to notifications with the `NovuProvider`. This component initializes the Novu client and provides it to all child hooks via [context](/platform/workflow/advanced-features/contexts).

```jsx
import { NovuProvider } from '@novu/react';

function App() {
  return (
    <NovuProvider
      subscriber="[notificationSoundRef, novu]icationSoundRef, novu]IBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      {/* Your app components */}
    </NovuProvider>
  );
}
```

<Callout> For more `NovuProvider` options, such as HMAC encryption, see the [Novu provider documentation](/platform/sdks/react/hooks/novu-provider). </Callout>

## Fetch and display notifications

Use the `useNotifications` hook to fetch and display a list of notifications. The hook manages loading states, pagination (`hasMore`, `fetchMore`), and real-time updates for you.

```jsx
import { useNotifications } from "@novu/react";

function NotificationsList() {
  const { notifications, isLoading, error } = useNotifications();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div className="space-y-4">
      {notifications?.map((notification) => (
        <div key={notification.id} className="p-4 border rounded-lg">
          <h3 className="font-medium">{notification.subject}</h3>
          <p>{notification.body}</p>
        </div>
      ))}
    </div>
  );
}
```

## Show notification counts

A common use case is showing a badge with the unread count on a bell icon. The `useCounts` hook is designed for this. It fetches unread, unseen, or total counts and updates them in real-time.

```jsx
import { useCounts } from "@novu/react";

function BellButton() {
  const { counts } = useCounts({ 
    filters: [
      { read: false }, // Unread notifications
    ] 
  });
  
  const unreadCount = counts?.[0]?.count ?? 0;

  return (
    <button>
      <BellIcon />
      {unreadCount > 0 && (
        <span className="badge">{unreadCount}</span>
      )}
    </button>
  );
}
```

## Adding notification actions

To perform actions on notifications such as marking as read, unread, or archiving, you can use the `useNovu` hook. This hook gives you direct access to the Novu client instance to call its API methods.

The hooks `useNotifications` and `useCounts` automatically refetch and update your UI when these actions are performed.

```jsx
import type { Notification as INotification } from "@novu/react";
import { useNovu } from "@novu/react";

function NotificationItem({ notification }: { notification: INotification }) {
  const novu = useNovu();

  const markAsRead = async () => {
    try {
      await novu.notifications.readAll({ notificationId: notification.id });
    } catch (error) {
      console.error("Failed to mark as read:", error);
    }
  };

  const archive = async () => {
    try {
      await novu.notifications.archiveAll({ notificationId: notification.id });
    } catch (error) {
      console.error("Failed to archive:", error);
    }
  };

  return (
    <div className="p-4 border rounded-lg">
      <h3 className="font-medium">{notification.subject}</h3>
      <p>{notification.body}</p>
      <div className="flex gap-2 mt-2">
        <button
          onClick={markAsRead}
          className="px-2 py-1 text-sm bg-blue-50 text-blue-600 rounded"
          disabled={notification.isRead}
        >
          Mark as read
        </button>
        <button
          onClick={archive}
          className="px-2 py-1 text-sm bg-gray-50 text-gray-600 rounded"
          disabled={notification.isArchived}
        >
          Archive
        </button>
      </div>
    </div>
  );
}
```

## Showing product updates banner

`@novu/react` hooks can be used to show a product updates banner in your application along with  `<Inbox />` component notifications. Differences between product update banner and `<Inbox />` component notifications are:

* `<Inbox />` component notifications are displayed in `Popover` when bell is clicked while product update banner is displayed as a standalone top banner in the application.
* `<Inbox />` component notifications are unique to the user while product update banner is displayed to all users.

To show a product update banner use following steps:

1. Create a new workflow in the dashboard with in-app steps
2. Edit in-app step content and make this workflow as critical so that this workflow is not displayed in preferences.
3. Create a **system subscriber** in the dashboard with subscriberId `product-updates-subscriber` for product updates banner. This system subscriber will be used to show the product updates banner to all users.
4. Create `ProductUpdateBanner` component and use `useNotifications` hook to get the product updates notifications and show them in the banner.

```jsx title="components/ProductUpdateBanner.tsx"
import { NovuProvider, useNotifications } from "@novu/react";

import React from "react";

const BannerNotification = () => {
  const { notifications } = useNotifications({
    // with limit:1 and archived:false we are getting the latest product update notification
    limit: 1,
    archived: false,
  });

  if (notifications && notifications.length > 0) {
    // customize the banner as per your needs
    return <div dangerouslySetInnerHTML={{ __html: notifications[0].body }} />;
  }
  return null;
};

export const ProductUpdateBanner = async () => {
  return (
    <NovuProvider
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="product-updates-subscriber" // this subscriberId is common for all users
    >
      <BannerNotification />
    </NovuProvider>
  );
};
```

5. Use `ProductUpdateBanner` component in your application. In below example we are using `ProductUpdateBanner` component with `<Inbox />` component to show the product updates banner along with `<Inbox >` notifications.

```jsx title="components/NovuNotifications.tsx"
import { Inbox } from "@novu/react";
import { ProductUpdateBanner } from "./ProductUpdateBanner";

export const NovuNotifications = () => {
  return (
    <div>
      <ProductUpdateBanner />
      <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID" />
    </div>
  );
}
```

6. Use `NovuNotifications` component in your application.

7. Trigger the step 1 workflow to system subscriber `product-updates-subscriber`.

8. As per product release requirements, [Permanently delete](/api-reference/messages/delete-a-message) or [archive](/platform/sdks/javascript#archive) the product update notification to hide the banner.

Using above steps, two instances of Novu notifications will be shown in your application:

* Product updates banner with common subscriberId `product-updates-subscriber`
* `<Inbox />` notifications with user specific subscriberId `YOUR_SUBSCRIBER_ID`

## Real-time updates

The `useNotifications` and `useCounts` hooks automatically listen for real-time events and update your component state.

If you need to listen for events manually, then you can use the `novu.on()` method from the `useNovu` hook. For example, you might want to show a toast notification when a new message arrives.

```jsx
import { useNovu } from "@novu/react";
import { useEffect } from "react";
import type { Notification as INotification } from "@novu/react";

function NotificationListener() {
  const novu = useNovu();

  useEffect(() => {
    // Handler for new notifications
    const handleNewNotification = ({ result }: { result: INotification }) => {
      console.log("New notification:", result.subject);
      // You can use a toast library here
      // toast.show(result.subject);
    };

    // Handler for unread count changes
    const handleUnreadCountChanged = ({ result }: { result: number }) => {
      document.title = result > 0 ? `(${result}) My App` : "My App";
    };

    // Subscribe to events
    novu.on("notifications.notification_received", handleNewNotification);
    novu.on("notifications.unread_count_changed", handleUnreadCountChanged);

    // Cleanup function
    return () => {
      novu.off("notifications.notification_received", handleNewNotification);
      novu.off("notifications.unread_count_changed", handleUnreadCountChanged);
    };
  }, [novu]);

  return null; // This component doesn't render anything
}
```

### Using websocket events

The websocket event `notifications.notification_received` can be used to play a sound and show a toast message on the screen when a notification is received.

```jsx
import { useNovu } from "@novu/react";
import { useEffect, useRef } from "react";
import type { Notification as INotification } from "@novu/react";

function NotificationSoundPlayer() {
  const novu = useNovu();

  // Keep audio instance stable across renders
  const notificationSoundRef = useRef<HTMLAudioElement | null>(null);

  useEffect(() => {
    // Initialize sound once
    notificationSoundRef.current = new Audio("/notification.mp3");
    notificationSoundRef.current.preload = "auto";

    // Handler for new notifications
    const handleNewNotification = ({ notification }: { notification: INotification }) => {
      console.log("New notification:", notification.subject);

      // Play notification sound
      notificationSoundRef.current
        ?.play()
        .catch((err) => {
          // This can fail if user hasn’t interacted with the page yet
          console.warn("Notification sound could not be played:", err);
        });

      // Example: toast notification
      // toast({
      //   title: notification.subject,
      //   description: notification.body,
      // });
    };

    // Subscribe to events
    novu.on("notifications.notification_received", handleNewNotification);

    // Cleanup
    return () => {
      novu.off("notifications.notification_received", handleNewNotification);
    };
  }, [novu, notificationSoundRef]);

  return null;
}

export default NotificationListener;
```


# Introduction to Inbox (/platform/inbox)

Learn how to integrate Novu Inbox component, a pre-built notification center component for real-time in-app notifications in your application.

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Bell, Code, Layout, Sliders } from 'lucide-react';

The Novu Inbox is a prebuilt, ready-to-use, and fully customizable UI component for delivering real-time in-app notifications. It gives your subscribers a centralized place to view and manage notifications.

With just a few lines of code, you can embed a polished, real-time notification experience directly into your application.

![Introduction to inbox](/images/inbox/intro-to-inbox.png)

## Composable architecture

The Novu Inbox is built with a composable architecture. It is composed of other sub-components:

<Cards>
  <Card title="Bell" icon={<Bell />} href="/platform/inbox/advanced-customization/customize-bell#bell-component">
    Used to display the bell icon and trigger the notification component when clicked
  </Card>

  <Card title="Notifications" icon={<Code />} href="/platform/inbox/advanced-customization/customize-popover#notifications-component">
    Displays the notifications list
  </Card>

  <Card title="InboxContent" icon={<Layout />} href="/platform/inbox/advanced-customization/customize-popover#inboxcontent-component">
    Displays the content of the `<Inbox />` menu
  </Card>

  <Card title="Preferences" icon={<Sliders />} href="/platform/inbox/configuration/preferences#using-the-preferences--component">
    Used to display the preferences modal
  </Card>
</Cards>

![Fully functional and customizable React Inbox component](/images/inbox/overview@2x.png)

By composing these individual components, you can create multiple popular inbox layouts that fit perfectly within your application's design.

<Callout type="info" title="Design files">To aid your design process, we provide a [free Figma file](https://www.figma.com/community/file/1425407348374863860) that contains all of the design assets. Make a copy of the file into your own account to get started with customizing your graphical Inbox elements.</Callout>

## Key feature

* Full stack integration: The Inbox handles UI, unread states, routing, and preferences all in one place.
* Highly customizable: Override styles, replace every UI elements and icons.
* Flexible layouts: Use the default Inbox UI layout or build your own.
* Built-in support for  Tabs and filters, localization, snoozing, preferences management, and more.

## How it works

At a high level, the Inbox abstracts away the complexity of building a notification center.

1. When you drop the Inbox component into your application, it securely connects to Novu's services.
2. It automatically fetches user notifications and manages the real-time unread count displayed on the bell icon.
3. When a user clicks the bell, it presents the list of notifications and user preferences.
4. All user interactions, such as marking a notification as read or changing a preference, are automatically synchronized with the Novu backend in real-time.

## Ways to implement the Novu Inbox

There are two integration approaches, depending on your needs for speed versus customization.

### The "Plug-and-Play" approach

This is the fastest way to integrate the Novu Inbox. The Inbox component, encapsulate all the UI and logic. You simply drop the component into your application, configure it with the necessary properties, and you're done.

### "Build-Your-Own" Approach

For maximum flexibility and complete control over the look and feel, use the [@novu/react SDK](/platform/sdks/react) for react hooks or [@novu/js SDK](/platform/sdks/javascript) for framework agnostic javascript methods.

You get the power of Novu's notification engine while building a user interface that perfectly matches your application's design system.


# Migrate to the New Inbox (/platform/inbox/migration-guide)

This guide outlines the key differences between the `@novu/notification-center` package and the new `@novu/react` package and how to migrate to the latest Inbox version.

<Callout type="info">
  * Use [@novu/react](/platform/sdks/react) Inbox React component and
    [@novu/js](/platform/sdks/javascript) headless package with new dashboard workflows and [@novu/framework](/platform/workflow)-based workflows.

  * With legacy dashboard based workflows, use
    [@novu/notification-center](https://v0.x-docs.novu.co/notification-center/client/react/get-started) package.
</Callout>

The `@novu/react` package introduces a more flexible and customizable way to display notifications in your application. This guide outlines the key differences between the `@novu/notification-center` package and the new `@novu/react` package.

Follow the steps below to migrate your application to the latest Inbox version.

## Why you should upgrade to `@novu/react`

* **Customization**: The `@novu/react` package provides more customization options for the appearance and behavior of the notification components.
* **Flexibility**: The new package offers more flexibility in handling notifications and integrating with third-party libraries.
* **Performance**: It is optimized for performance and provides a smoother user experience.
* **Bundle Size**: The new package has a smaller bundle size and improved tree-shaking capabilities.
* **Compatibility with the `@novu/framework`**: The `@novu/react` package is designed to work seamlessly with the `@novu/framework` package for creating and managing notifications.

## Breaking Changes

The `@novu/react` package introduces several breaking changes compared to the `@novu/notification-center` package. Here are the key differences:

### Components

* The `PopoverNotificationCenter` component has been replaced with the `Inbox` component.
* The `NotificationCenter` component has been replaced with the `Notifications` component.
* The `NotificationBell` component has been replaced with the `Bell` component.

### Styling

* The `styles` prop is replaced by an enhanced, easy to use `appearance` prop to customize the notification components. For more information on `appearance` customization, visit [here](/platform/inbox/configuration/styling).

### Notification

* Removal of `seen` , `lastSeenDate`, `content`, `templateIdentifier`, `payload`, `cta` properties from the Notification object.
* We have introduced `archive` functionality to the Notification object.

```diff title="Notification object"
type Notification = {
- _id: string;
+ id: string;

- content: string;
+ body: string;

- cta: IMessageCTA;
+ redirect?: Redirect;
+ primaryAction?: Action;
+ secondaryAction?: Action;

- channel: ChannelTypeEnum;
+ channelType: ChannelType;

- payload: Record<string, unknown>;
+ data?: Record<string, unknown>;

- subscriber: Subscriber;
+ to: Subscriber;

- seen: boolean;
- lastSeenDate: string;
- templateIdentifier: string;

+ subject?: string;
+ isRead: boolean;
+ isSeen: boolean;
+ isArchived: boolean;
+ isSnoozed: boolean;
+ readAt?: string | null;
+ archivedAt?: string | null;
+ avatar?: string;
+ tags?: string[];
+ avatar?: string;
+ workflow: Workflow;
+ deliveredAt: string | null;
+ firstSeenAt: string | null;

updatedAt: string;
createdAt: string;
};
```

```ts title="Types"
type Workflow = {
  critical: boolean;
  id: string;
  identifier: string;
  name: string;
  tags: string[];
};

type Subscriber = {
  id: string;
  firstName?: string;
  lastName?: string;
  avatar?: string;
  subscriberId: string;
};

type Redirect = {
  url: string;
  target?: '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop';
};

type Action = {
  label: string;
  isCompleted: boolean;
  redirect?: Redirect;
};
```

## Getting started

To begin, install the `@novu/react` package.

<Tabs groupId="package-manager" persist items={}>
  <Tab value="npm">
    ```bash
    npm install @novu/react
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @novu/react
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @novu/react
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @novu/react
    ```
  </Tab>
</Tabs>

## Basic usage

### Legacy implementation with `@novu/notification-center`

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}
export default Novu;
```

### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID" />
  );
}

export default Novu;
```

## Notification center without bell icon

The @novu/react package introduces a flexible way to display notifications as a list without the default bell icon. Use the `Inbox` and `Notifications` components to achieve this functionality.

### Legacy implementation with `@novu/notification-center`

```tsx
import { NovuProvider, NotificationCenter } from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <NotificationCenter colorScheme="dark" />
    </NovuProvider>
  );
}

export default Novu;
```

### Current implementation with `@novu/react`

```tsx
import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID">
      <Notifications />
    </Inbox>
  );
}

export default Novu;
```

## Custom bell icon

Customize the bell icon that triggers the notifications popover using the `renderBell` prop.

### Legacy implementation with `@novu/notification-center`

```tsx
import { NovuProvider, PopoverNotificationCenter } from '@novu/notification-center';
import CustomBell from './CustomBell'; // Your custom bell icon component

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter colorScheme="dark">
        {({ unseenCount }) => (
          <CustomBell
            unseenCount={unseenCount}
            colorScheme="dark"
            unseenBadgeBackgroundColor="#FFFFFF"
            unseenBadgeColor="#FF0000"
          />
        )}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';
import CustomBell from './CustomBell'; // Your custom bell icon component

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderBell={(unreadCount) => <CustomBell unreadCount={unreadCount} />}
    />
  );
}

export default Novu;
```

## Notification actions

Handle user interactions with notifications effectively using the action handlers provided by `@novu/react`.

### onNotificationClick

Trigger a callback function when a user clicks on a notification item.

#### Legacy implementation with `@novu/notification-center`

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
  IMessage,
} from '@novu/notification-center';

function Novu() {
  function handleOnNotificationClick(message: IMessage) {
    // your logic to handle the notification click
    if (message?.cta?.data?.url) {
      window.location.href = message.cta.data.url;
    }
  }

  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter colorScheme="dark" onNotificationClick={handleOnNotificationClick}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

#### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    // Your custom logic here
    console.log('Notification clicked:', notification);
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;
```

### onPrimaryActionClick and onSecondaryActionClick

Handle primary and secondary actions within a notification explicitly.

#### Legacy implementation with `@novu/notification-center`

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  IMessage,
  MessageActionStatusEnum,
  useUpdateAction,
  ButtonTypeEnum,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  const CustomNotificationCenter = () => {
    const { updateAction } = useUpdateAction();

    const handleOnActionClick = async (
      templateIdentifier: string,
      btnType: ButtonTypeEnum,
      notification: IMessage
    ) => {
      if (templateIdentifier === 'friend-request') {
        if (btnType === 'primary') {
          /** Call your API to accept the friend request here **/

          /** And then update Novu that this action has been taken, so the user won't see the button again **/
          updateAction({
            messageId: notification._id,
            actionButtonType: btnType,
            status: MessageActionStatusEnum.DONE,
          });
        }
      }
    };

    return (
      <PopoverNotificationCenter colorScheme={'dark'} onActionClick={handleOnActionClick}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    );
  };

  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <CustomNotificationCenter />
    </NovuProvider>
  );
}

export default Novu;
```

#### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handlePrimaryActionClick = (notification) => {
    // Handle primary action
    console.log('Primary action clicked:', notification);
  };

  const handleSecondaryActionClick = (notification) => {
    // Handle secondary action
    console.log('Secondary action clicked:', notification);
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onPrimaryActionClick={handlePrimaryActionClick}
      onSecondaryActionClick={handleSecondaryActionClick}
    />
  );
}

export default Novu;
```

## Avatar icons

In the legacy implementation, you could set a notification’s avatar icon by enabling the Add an avatar option in the workflow UI. Novu would then use the avatar field of the actor subscriber as the icon.

In the new implementation, you can set the avatar icon for a notification by adding the avatar icon in the workflow UI. There are three options to choose from:

* Use a default avatar icon.
* Use a hard-coded avatar icon URL.
* Use a payload variable to dynamically set the avatar icon.

For more information, refer to [Icons](/platform/inbox/configuration/icons#change-or-remove-a-in-app-notification-avatar).

## Popover positioning

For advanced positioning and styling of the notifications popover, integrate third-party popover libraries such as Radix UI.

### Legacy implementation with `@novu/notification-center`

```tsx
import {
  PopoverNotificationCenter,
  NotificationBell,
  NovuProvider,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter position="left-start" offset={20}>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

### Current implementation with `@novu/react` and Radix UI as an example

```tsx
import React from 'react';
import * as RadixPopover from '@radix-ui/react-popover';
import { Inbox, Bell, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID">
      <RadixPopover.Root>
        <RadixPopover.Trigger asChild>
          <Bell />
        </RadixPopover.Trigger>
        <RadixPopover.Portal>
          <RadixPopover.Content side="bottom" align="end" sideOffset={10}>
            <Notifications />
            <RadixPopover.Arrow />
          </RadixPopover.Content>
        </RadixPopover.Portal>
      </RadixPopover.Root>
    </Inbox>
  );
}

export default Novu;
```

## Custom notification item

Customize the appearance and structure of individual notification items using the `renderNotification` prop.

### Legacy implementation with `@novu/notification-center`

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider subscriber="YOUR_SUBSCRIBER_ID" applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter
        colorScheme={colorScheme}
        onNotificationClick={handlerOnNotificationClick}
        onActionClick={handlerOnActionClick}
        listItem={(notification, handleActionButtonClick, handleNotificationClick) => {
          return (
            <a
              href="/"
              onClick={(e) => {
                e.preventDefault();
                handleNotificationClick();
              }}>
              {notification.content}
            </a>
          );
        }}>
        {({ unseenCount }) => {
          return <NotificationBell unseenCount={unseenCount} />;
        }}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const renderCustomNotificationItem = (notification) => (
    <div
      className={`notification-item ${notification.isRead ? 'read' : 'unread'}`}
      onClick={() => notification.read()}>
      <img src={notification.avatar} alt="Avatar" className="notification-avatar" />
      <div className="notification-content">
        <h4 className="notification-subject">{notification.subject}</h4>
        <p className="notification-body">{notification.body}</p>
      </div>
    </div>
  );

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={renderCustomNotificationItem}
    />
  );
}

export default Novu;
```

## Styling with appearance prop

Customize the overall look and feel of the notification components using the appearance prop, which supports both CSS objects and class names (including Tailwind CSS classes).

### Legacy implementation with `@novu/notification-center`

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      styles={{ notifications: { listItem: { layout: { color: '#E3554D' } } } }}>
      <PopoverNotificationCenter>
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

### Current implementation with `@novu/react`

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{
        baseTheme: {
          variables: {
            colorBackground: '#1F2937',
            colorForeground: '#F9FAFB',
            colorPrimary: '#3B82F6',
            colorSecondaryForeground: '#9CA3AF',
            colorNeutral: '#374151',
          },
        },
        elements: {
          bellIcon: 'text-white',
          notificationItem: 'custom-class bg-gray-800 hover:bg-gray-700 p-4 rounded-md',
          notificationSubject: {
            color: '#E2E8F0',
            fontSize: '18px',
            fontWeight: 'bold',
          },
          notificationBody: {
            color: '#A0AEC0',
            fontSize: '14px',
          },
        },
      }}
    />
  );
}

export default Novu;
```

For more information on `appearance` customization visit [here](/platform/inbox/configuration/styling).

## Multiple tabs support

Organize notifications into different categories using tabs by leveraging the tags property in workflow definitions and the tabs prop in the Inbox component.

### Create multiple tabs

#### Legacy implementation with `@novu/notification-center`

After defining the feeds on the workflow UI, you were able to filter notifications based on the feedIdentifier.

```tsx
import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
} from '@novu/notification-center';

function Novu() {
  return (
    <NovuProvider
      stores={[
        {
          storeId: 'product-updates',
          query: { feedIdentifier: 'product-updates' },
        },
        {
          storeId: 'user-activity',
          query: { feedIdentifier: 'user-activity' },
        },
      ]}
      subscriber="YOUR_SUBSCRIBER_ID"
      applicationIdentifier="YOUR_APP_ID">
      <PopoverNotificationCenter
        tabs={[
          { name: 'Product Updates', storeId: 'product-updates' },
          { name: 'User Activity', storeId: 'user-activity' },
        ]}
        colorScheme={colorScheme}
        onNotificationClick={handlerOnNotificationClick}
        onActionClick={handlerOnActionClick}>
        {({ unseenCount }) => {
          return <NotificationBell colorScheme={colorScheme} unseenCount={unseenCount} />;
        }}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

export default Novu;
```

#### Current implementation with `@novu/react`

1. Define multiple workflows with relevant tags.

Add tags on the workflow Tags field. One tag can be used for multiple workflows.

2. Use those tags in the `tabs` prop of the `Inbox` component.

```tsx
import { Inbox } from '@novu/react';

const tabs = [
  { label: 'All Notifications', value: [] },
  { label: 'Security', value: ['security'] },
  { label: 'Promotions', value: ['promotions'] },
];

function InboxWithTabs() {
  return (
    <Inbox 
      applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID" 
      tabs={tabs} 
    />
  );
}

export default InboxWithTabs;
```

## Localization

Customize the language and text content of the notification components using the localization prop. Refer to the [localization documentation](/platform/inbox/advanced-features/localization).

## HMAC encryption

The process remains the same as before. For more information, refer to [Secure your inbox with HMAC encryption](/platform/inbox/prepare-for-production#secure-your-inbox-with-hmac-encryption).

## Handling notifications

Handle notifications using the methods provided by the notification object.

### Marking notifications as read

Mark notifications as read using the `read` method provided by the notification object.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    notification.read();
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;
```

### Marking notifications as unread

Mark notifications as unread using the `unread` method provided by the notification object.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    notification.unread();
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;
```

### Marking notifications as archive

Mark notifications as archive using the `archive` method provided by the notification object.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    notification.archive();
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;
```

### Marking notifications as unarchive

Mark notifications as unarchive using the `unarchive` method provided by the notification object.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  const handleNotificationClick = (notification) => {
    notification.unarchive();
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={handleNotificationClick}
    />
  );
}

export default Novu;
```

If you still have questions or need further assistance, please reach out to us at [support@novu.co](mailto:support@novu.co).


# Prepare Inbox component for Production (/platform/inbox/prepare-for-production)

Learn how to prepare your Inbox for production by enabling HMAC encryption for security and managing Novu's branding.

Before deploying the Inbox UI to production, you should secure your integration and configure the correct environment. You can also remove Novu's branding from your notifications.

This ensures that your end users receive notifications safely, without exposure to unnecessary risks, and in a way that aligns with your product branding.

## Set the correct environment

Novu supports multiple environments, including development, production, and any custom environments you create.

When preparing for deployment, choose the environment that will serve as your production environment and update your configuration accordingly:

* Use the API keys for your selected production environment from the [API Keys](https://dashboard.novu.co/api-keys) page in your application.

* Store keys in `.env` file or your server’s environment variables.

* Confirm your `applicationIdentifier` and `subscriber` match the configuration for your chosen production environment.

* Add these two props, if using the EU region:
  * `apiUrl` with value **[https://eu.api.novu.co](https://eu.api.novu.co)**
  * `socketUrl` with value **wss\://eu.socket.novu.co**

## Secure your Inbox with HMAC encryption

When you add the Inbox to your application, you're required to pass:

* `subscriberId`: Identifies the current subscriber.
* `applicationIdentifier`: A public key to communicate with the notification feed API.

<Callout type="warn">Without additional security, a malicious actor could potentially guess another subscriber's `subscriberId` and use your public `applicationIdentifier` to view that user's notifications.</Callout>

You can prevent this by enabling HMAC (Hash-based Message Authentication Code) encryption. This process uses a *secret key* to create a secure signature (`subscriberHash`) for each `subscriberId`. Novu then verifies this hash to ensure that requests to view a notification feed are authentic and not from an impersonator.

Follow these steps to enable HMAC encryption.

### 1. Enable HMAC in the dashboard

Activate the HMAC security feature within your Novu in-app provider settings.

1. Go to [Novu Dashboard](https://dashboard.novu.co).
2. Navigate to the [Integrations Store](https://dashboard.novu.co/integrations) page.
3. Click on the **Novu In-App** for your chosen production environment
4. A side panel opens from the right side of the screen with the provider settings, enable `Security HMAC encryption` toggle in **Integration Credentials** section.
   ![Enabling HMAC in the Novu dashboard](/images/inbox/hmac.png)

### 2. Generate HMAC hash on the server side

Next, use your secret key from the API Keys page on the Novu dashboard to generate an HMAC hash of the `subscriberId` on the server side.

<Tabs items={['Without Context', 'With Context']}>
  <Tab value="Without Context">
    ```tsx title="utils/hmac-hash.ts"
    import { createHmac } from 'crypto';

    // The subscriberId of the logged-in user
    const subscriberId = 'REPLACE_WITH_SUBSCRIBER_ID';

    // The secret key from your Novu API Keys page
    const novuSecretKey = process.env.NOVU_SECRET_KEY;

    // Generate the HMAC hash
    const hmacHash = createHmac('sha256', novuSecretKey)
      .update(subscriberId)
      .digest('hex');
    ```
  </Tab>

  <Tab value="With Context">
    We need to use `canonicalize` here cause context is a dynamic object. `canonicalize` is used to serialize the JSON in a way that the order of keys or whitespaces etc doesn’t matter. The library should be based on [RFC-8259](https://datatracker.ietf.org/doc/html/rfc8259).

    ```tsx title="utils/hmac-hash.ts"
    import { createHmac } from 'crypto';
    import { canonicalize } from '@tufjs/canonical-json';

    // The subscriberId of the logged-in user
    const subscriberId = 'REPLACE_WITH_SUBSCRIBER_ID';

    // The secret key from your Novu API Keys page
    const novuSecretKey = process.env.NOVU_SECRET_KEY;

    // Generate the subscriber hash
    const subscriberHash = createHmac('sha256', novuSecretKey)
      .update(subscriberId)
      .digest('hex');


    const context = {
      tenant: {
        id: "acme-corp",
        data: {
          name: "Acme Corporation",
          plan: "enterprise",
        },
      },
    };

    // Generate the context hash
    const contextHash = createHmac('sha256', novuSecretKey)
      .update(canonicalize(context))
      .digest('hex');
    ```
  </Tab>
</Tabs>

<Callout type="warn">Keep `NOVU_SECRET_KEY` secure and never expose it to the client.</Callout>

### 3. Use the HMAC hash in the Inbox component

Send the `hmacHash` generated in the previous step to the client side application. You can include it in the initial data payload when a subscriber or user logs in or fetch it from a dedicated API endpoint.

Pass the hash to the `subscriberHash` prop in your Inbox component.

<Tabs items={['Without Context', 'With Context']}>
  <Tab value="Without Context">
    ```tsx title="components/InboxWithSubscriberHash.tsx"
    import { Inbox } from '@novu/react';

    // Example: The hmacHash is passed to the frontend
    // as part of the user object after they authenticate.

    const { user } = currentUser();
    const hmacHash = user?.novuSubscriberHash;

    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      subscriberHash={hmacHash}
    />;
    ```
  </Tab>

  <Tab value="With Context">
    ```tsx title="components/InboxWithSubscriberAndContextHashes.tsx"
    import { Inbox } from '@novu/react';

    const { user } = currentUser();
    const subscriberHash = user?.novuSubscriberHash;
    const contextHash = user?.novuContextHash;


    const context = {
      tenant: {
        id: "acme-corp",
        data: {
          name: "Acme Corporation",
          plan: "enterprise",
        },
      },
    };

    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      subscriberHash={subscriberHash}
      context={context}
      contextHash={contextHash}
    />
    ```
  </Tab>
</Tabs>

<Callout type="info">
  If HMAC encryption is active in In-App provider settings and `subscriberHash` along with
  `subscriberId` is not provided, then Inbox will not load
</Callout>

## Remove Novu branding

Users on a paid plan can remove the "Inbox by Novu" branding from the Inbox UI.

To remove the branding:

1. Go to [Novu Dashboard](https://dashboard.novu.co).
2. Navigate to the **Settings** page.
3. Under the **Organization** tab, find the **Branding & Integrations** section.
4. Enable the **Remove Novu branding** toggle.

![Removing Novu branding](/images/inbox/novu-branding.png)


# Set up the Inbox (/platform/inbox/setup-inbox)

Learn how to integrate the Novu Inbox component into your application to display real-time notifications for your subscribers.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import Link from 'next/link';

The Inbox component displays a notification bell by default, which opens a menu containing the subscriber's notifications and preferences.

## Installation

To get started, install the Inbox UI:

<Tabs items={['Next.js', 'React']}>
  <Tab value="Next.js">
    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/nextjs
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/nextjs
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/nextjs
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/nextjs
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="React">
    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/react
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/react
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/react
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/react
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Try Inbox in keyless mode

Keyless mode lets you test the look and features of the Inbox component instantly in your application, no setup required.

![Inbox keyless](/images/inbox/keyless-inbox.png)

<Tabs items={['Next.js', 'React']}>
  <Tab value="Next.js">
    ```tsx
    import { Inbox } from '@novu/nextjs';

    export function Novu() {
      return (
        <Inbox />
      );
    }
    ```
  </Tab>

  <Tab value="React">
    ```tsx
    import { Inbox } from '@novu/react';

    export function Novu() {
      return (
        <Inbox />
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">This is only for testing, the data is temporary (expires in 24h) and not tied to real subscribers.</Callout>

## Use Inbox with real subscribers

To display real-time notifications for your subscribers, connect the Inbox component to your Novu environment using your `applicationIdentifier` and a `subscriberId`. You can create or manage subscribers from the <a href="https://dashboard.novu.co/subscribers" target="_blank" rel="noopener noreferrer" class="nx-text-primary-600 nx-underline">Novu Dashboard</a>.

### US region (default)

<Tabs items={['Next.js', 'React']}>
  <Tab value="Next.js">
    ```tsx
    import { Inbox } from '@novu/nextjs';

    export function Novu() {
      return (
        <Inbox
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriber="SUBSCRIBER_ID"
        />
      );
    }
    ```
  </Tab>

  <Tab value="React">
    ```tsx
    import { Inbox } from '@novu/react';

    export function Novu() {
      return (
        <Inbox
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriber="SUBSCRIBER_ID"
        />
      );
    }
    ```
  </Tab>
</Tabs>

<div className="text-sm text-gray-500 text-center mt-2">
  <Link href="https://dashboard.novu.co/auth/sign-up">Sign in</Link> to get your own API keys
</div>

### EU region

If your Novu account is in the EU region, then include the `backendUrl` and `socketUrl` props to connect to EU-specific API endpoints:

<Tabs items={['Next.js', 'React']}>
  <Tab value="Next.js">
    ```tsx
    import { Inbox } from '@novu/nextjs';

    export function Novu() {
      return (
        <Inbox
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriber="SUBSCRIBER_ID"
          backendUrl="https://eu.api.novu.co"
          socketUrl="wss://eu.socket.novu.co"
        />
      );
    }
    ```
  </Tab>

  <Tab value="React">
    ```tsx
    import { Inbox } from '@novu/react';

    export function Novu() {
      return (
        <Inbox
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriber="SUBSCRIBER_ID"
          backendUrl="https://eu.api.novu.co"
          socketUrl="wss://eu.socket.novu.co"
        />
      );
    }
    ```
  </Tab>
</Tabs>

<div className="text-sm text-gray-500 text-center mt-2">
  <Link href="https://dashboard.novu.co/auth/sign-up">Sign in</Link> to get your own API keys
</div>


# Demo Integrations (/platform/integrations/demo-integration)

Learn about the default Novu Email and SMS provider.

Demo integrations are built-in, sandboxed providers for the email and SMS channels. Their purpose is to allow you to test your notification workflows immediately, without needing to sign up for or connect a real third-party provider.

When you create a Novu account, your environments come pre-configured with two demo email integrations and two demo SMS integrations. All demo integrations are active by default, and you can set any of them as the primary integration for their channel at any time from the **Integration Store**.

<Callout type="info">
  Demo integrations are only available in Novu cloud. This feature doesn't work in community self-hosted version and local environment.
</Callout>

## Limits of the demo integrations

Demo integrations are intended strictly for testing and development. To ensure this, they operate with the following rules:

* Both the demo email and demo SMS integrations are limited to 300 notifications per month each.
* The demo Email integration can only send emails to the address associated with your logged-in Novu account. It does not deliver messages to any other email address.

## How test using a demo integration

Demo integrations are active by default, so you can start testing in just a few steps.

The demo integrations are set as primary by default in new Novu environments.

1. Log in to the Novu dashboard.
2. Click **Workflows**.
3. Click **Create workflow** and [create a new workflow](/platform/workflow/create-a-workflow).
4. Add two steps in the workflow: one for Email and one for SMS.
   ![Add step](/images/channels-and-providers/add-step.png)
5. Click **Test Workflow**.
   ![Test workflow](/images/channels-and-providers/test-workflow.png)
6. Verify the notification. There are two ways to confirm that your test was successful:
   * Check the activity feed or event logs to confirm if the notification was successfully sent to the various channels.
     ![Event logs](/images/channels-and-providers/event-logs.png)
   * Check the inbox of the email address and phone number you use for your Novu account. You should receive a real email and SMS from the demo integration.

## Next step

Once you have finished testing with the demo integrations, select a channel below to find the list of all supported providers integrations and their guides:

<Cards>
  <Card title="Email" href="/platform/integrations/email">
    Integrate Email providers.
  </Card>

  <Card title="SMS" href="/platform/integrations/sms">
    Integrate SMS providers.
  </Card>

  <Card title="Push" href="/platform/integrations/push">
    Integrate Push providers.
  </Card>

  <Card title="Chat" href="/platform/integrations/chat">
    Integrate Chat providers.
  </Card>

  <Card title="In-App" href="/platform/inbox">
    Integrate In-app notifications.
  </Card>
</Cards>


# Integrations Overview (/platform/integrations)

Learn about the providers that Novu supports for Email, Push, SMS and Chant channels, and how to integrate them to send notifications and receive events.

Providers are the third-party services that deliver your notifications through the various channels. These are services such as SendGrid for email, Twilio for SMS, or Slack for chat.

Novu provides a unified integration layer that connects your application to all these different providers. You connect your provider accounts to Novu from the Integration Store on the Novu dashboard, and Novu's API handles the rest.

This approach means you can add, remove, or switch providers at any time without having to change your application's code. It also allows Novu to manage complex logic like provider fallbacks, for example, "If SendGrid fails, try sending with Amazon SES".

## Provider vs. Integration

Understanding the difference between a provider and an integration is key to managing your channels.

* **Provider**: A provider is the third-party service responsible for sending the actual notification such as, Twilio, SendGrid, or Slack. Every provider supported by Novu is identified by a providerId. Refer to this resource to see the full list of provider IDs used in Novu.

* **Integration**: An integration is your specific, configured instance of that provider. It's the provider plus your unique credentials and settings. When creating an integration, you are required to assign it a name and identifier.

  While the name can be changged, the identifier cannot be changed after creation. This identifier is called the `integrationIdentifier`.

![integrationIdentifier](/images/channels-and-providers/integrationidentifier.png)

This means that you can have provider but two separate integrations for that particular provider. Each of these is a unique integration that you can manage and trigger independently.

<Callout type="info">Novu providers demo integrations. To learn more about how to use them for testing, see the [Demo Integration](/platform/integrations/demo-integration) guide.</Callout>

### Primary vs. Active integrations

Each environment can have multiple active integrations for a single channel.

![Primary and active integration](/images/channels-and-providers/primary-active-integrations.png)

* **Active integration**: Any integration that is "on" and ready to send notifications. You can disable an active integration at any time to stop sending messages through it.
* **Primary integration**: This is the default integration used when you trigger a notification.

How the primary integration behaves depends on the channel:

* **Email and SMS channels**: You can have many active integrations, but only one can be marked as the primary at a time. This primary integration is used by default for all email or SMS notifications unless you specifically override it.

* **Push and chat channels**: These channels do not use a single primary integration. Instead, Novu uses all active integrations in parallel to deliver the message.

If you disable an integration that is currently marked as "primary" for Email or SMS channels, then Novu automatically promotes another active integration to be the new primary. You can also manually set which active integration you want to be the primary one from the Integration Store.

## Managing integrations across environments

Each integration is scoped to a specific [environment](/platform/developer/environments). This means you must configure separate integrations for each environment, even if they point to the same provider.

This separation ensures that test messages don’t accidentally go to production users, and different credentials or delivery settings can be safely isolated across environments.

## Override default settings

Novu provides an `overrides` object that can be used to access features that Novu doesn't currently support but are supported by certain providers. This feature includes:

* Setting custom SendGrid headers.
* Using Slack blocks.
* Defining platform-specific sounds for FCM push notifications.

<Callout>For a complete guide on Overrides, refer to the [Trigger Overrides](/platform/integrations/trigger-overrides) documentation.</Callout>

## Integration guides

Select a channel below to find the list of all supported providers integrations and their detailed setup guides:

<Cards>
  <Card title="Email" href="/platform/integrations/email">
    Configure email providers and settings
  </Card>

  <Card title="SMS" href="/platform/integrations/sms">
    Set up SMS messaging capabilities
  </Card>

  <Card title="Push" href="/platform/integrations/push">
    Enable push notification delivery
  </Card>

  <Card title="Chat" href="/platform/integrations/chat">
    Integrate with chat platforms
  </Card>

  <Card title="In-App" href="/platform/inbox">
    Manage in-app notification center
  </Card>
</Cards>


# Trigger Overrides (/platform/integrations/trigger-overrides)

Learn how to customize the behavior of your workflows at trigger time

import { Mail, MessageSquare } from 'lucide-react';
import { Card, Cards } from 'fumadocs-ui/components/card';

Trigger overrides let you to modify the default behavior of specific aspects of a workflow trigger (event), giving you fine-tuned control over how messages are delivered across different channels and providers.

## Channel overrides

Channel overrides let you customize specific channel settings and content during workflow trigger. Each channel has its own supported override options, documented in their respective channel guides.

<Callout>Channel overrides is only available for Email and SMS channels.</Callout>

<Cards>
  <Card title="Email overrides" icon={<Mail className="h-4 w-4" />} href="/platform/integrations/email" />

  <Card title="SMS overrides" icon={<MessageSquare className="h-4 w-4" />} href="/platform/integrations/sms" />
</Cards>

## Provider overrides

Provider overrides give you fine-tuned control over how messages are delivered by allowing direct configuration of the underlying provider SDKs during the workflow's trigger phase.

This feature is designed for advanced use cases where Novu's default message editor or UI does not expose specific provider capabilities.

Use provider overrides to:

* Access native provider features not surfaced by Novu’s abstraction layer. For example, custom headers in SendGrid, topic messaging in FCM, or Slack blocks.
* Adapt to provider-specific options by injecting parameters that Novu doesn’t yet officially support.
* Configure shared or unique settings across steps without altering templates or workflow logic.

This mechanism offers a flexible customization layer that lets you pass deeply nested payloads that align directly with your provider’s native API. It helps decouple workflow behavior from provider-specific implementation details, which is essential when working across multiple channels like email, push, or chat.

<Callout type="info">Because overrides interact directly with provider SDKs, they won’t work if they're misconfigured. Make sure you understand the supported options for each provider before using this feature. </Callout>

### Provider override scopes

Overrides are defined in the `overrides` property of a trigger payload. You can specify configuration values at two levels:

* Workflow-level: Applies to all steps using a specific provider and takes precedence over the default workflow provider settings.
* Step-level: Targets a specific step in the workflow and it takes precedence over both workflow-level overrides and the default workflow provider settings.

### Workflow-level provider overrides

Workflow-level provider overrides apply configuration to all steps that use a given provider in the workflow. They’re useful for applying shared logic across multiple steps, without repeating the same settings in each one.

Use workflow-level overrides when:

* You need to define common metadata like headers, personalization, or layout settings.
* You want consistent behavior across all steps for a given provider.

```typescript
import { Novu } from "@novu/api";

const novu = new Novu("<YOUR_SECRET_KEY_HERE>");

async function run() {
  const result = await novu.trigger({
    to: {
      subscriberId: "subscriber_unique_identifier",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
    },
    workflowId: "workflow_identifier",
    payload: {
      comment_id: "string",
      post: {
        text: "string",
      },
    },
    overrides: {
      providers: {
        sendgrid: {
          template_id: "xxxxxxxx", // Make sure this is a string
          trackingSettings: {
            clickTracking: {
              enable: true,
              enableText: false,
            },
          },
        },
      },
    },
  });
}

run();

```

This configuration affects every step in the workflow that uses SendGrid, unless a step-level override provides a more specific value.

#### Sending extra fields supported by provider SDK

You can also send extra fields supported by the provider SDK. For example, if you want to send a headers to the provider SDK, then you could use the `_passthrough` field.

```json
"overrides": {
  "providers" : {
    "sendgrid": {
      "_passthrough": {
        "headers": {
          "Authorization": "Bearer my-api-key"
        }
      }
    },
  },
},
```

### Step-level overrides

Step-level overrides let you apply provider-specific settings directly to an individual step in your workflow.

Use step-level overrides when:

* You want to send push notifications through the same provider, but with different settings for each step. For example, two steps use FCM, but each sends a different sound or title.
* You need to customize the payload for a specific push step, such as platform-specific settings for Android and iOS, without affecting other steps.

```typescript
import { Novu } from "@novu/api";

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

async function run() {
  const result = await novu.trigger({
    to: {
      subscriberId: "subscriber_unique_identifier",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
    },
    workflowId: "workflow_identifier",
    payload: {
      comment_id: "string",
      post: {
        text: "string",
      },
    },
    overrides: {
      steps: {
        'push-step': {
          providers: {
            fcm: {
              notification: {
                title: 'New Comment',
                body: 'Someone replied to your post!',
                sound: 'default', // Play default system sound
              },
              android: {
                notification: {
                  sound: 'sound_bell' // matches res/raw/sound_bell.mp3
                }
              },
              apns: {
                payload: {
                  aps: {
                    sound: 'notification_bell.caf' // For iOS
                  }
                }
              }
            }
          }
        }
      }
    }
  });
}

run();
```

<Callout>The `push-step` refers to the step identifier, which you can copy directly from your workflow in the Novu dashboard. Use this identifier to target the specific step you want to override. </Callout>

In this example, only the `push-step` is affected, and multiple FCM-specific settings are overridden for that step, which are the notification title, body, and sound configurations for both Android and iOS platforms.


# Novu for Developers (/platform/novu-for/developers)

Novu is a powerful notifications platform designed for developers and engineers to build, manage, and deliver scalable, extensible, and captivating multi-channel notification experiences while empowering product teams with intuitive tools and prebuilt components.

## Who is Novu for?

How you use and get started with Novu depends on your role. While it’s initially implemented by engineering and development teams, Novu unifies everyone in an organization that authors, creates, sends, manages, and measures results from notifications being sent to end users. Novu empowers engineers to deliver notification platforms for product teams.

### Novu for developers and engineers

Novu empowers developers and engineering teams to quickly deliver a fully extensible notifications platform for product teams to create captivating notification experiences.

We provide the following proven stack for developers to simply integrate notifications into their products:

* **[Code-first Notification Framework](/framework/typescript/overview)** Opinionated, yet flexible, Framework for building and managing notification workflows.
* **[JSON Schema Based](/api-reference)** Controls to craft a no-code visual editor to enable non-technical team members to modify content and behaviour.
* **[Prebuilt, customisable UI components](/platform/inbox)** for in-app user notification feeds and preference experiences.
* **[Integration with multiple delivery providers](/platform/integrations)**, allowing you to continue using your preferred vendors with Novu.
* **[Scalable, reliable Novu Cloud SaaS infrastructure](https://dashboard.novu.co)** developed from scratch to meet the demands of high-volume notification delivery and storage (think hundreds of millions of notifications).
* **Observability** for delving into the lifecycle of a notification's success or failure. Eliminate guesswork of how, when, and why a user receives a notification.
* **Comprehensive documentation**, implementation guides, recipes and illustrative examples.
* **Compliance and security** for safely managing your data.
* **Open source** provides transparency you can trust, cultivates community contributions for fast improvement, and enables you to deploy and self-host a Novu instance into any environment of your choosing.

Notification content can be written in a variety of common content tooling, including [React](/framework/content/react-email), [Vue-email](/framework/content/vue-email), MJML, and more. Content can also be customized and hydrated using any datasource.


# No-Code tools to manage your notifications (/platform/novu-for/product)

Change notification messaging, verbiage, and cadence without requiring engineering's help by using the Novu Dashboard UI.

Novu Framework was designed to bridge the gap between developers and non-developers in the team.

* **Developers** - Define and abstract away complex logic, data manipulation, hydration, html, and etc...
* **Non-Developers** - Use the Novu Dashboard UI to control the content and behavior of the notifications using [controls](/framework/controls).

## How to modify controls?

Controls are modified directly in the [Novu Dashboard UI](https://dashboard.novu.co), under the 'Step controls' tab of the **Workflow Editor** page.
Upon saving the changes, the new Control values will be used in the notification sent to your subscribers.

## Dynamic payload data

Dynamic data passed as part of the trigger payload can be easily used inside of the Controls. For example, you can pass a `user_name` as part of the payload and use it in the controls as `{{payload.user_name}}` to personalize the notification.

## Common usecases

### Change notification content

A control can be as broad as `content` or as specific as `2fa_code_title_color`. This allows you to change the content of the notification without needing to touch the code.

### Create new email designs

Novu's built-in email editor enables rich content creation without ever touching the code.

### Change digest or delay frequency

Controls can be used for controlling any aspect of the step configuration, for example:

* Delay amount
* Digest length
* Digest type (daily, weekly, monthly)
* etc...

Read more about [digest strategies and how to prevent notification fatigue.](https://novu.co/blog/digest-notifications-best-practices-example/)

### Control structure and layout

Controls can be used to show/hide or rearrange the layout of the notification.
For example, you can have an input to show/hide a button, or change the position of a specific email section.


# Novu Angular Quickstart Guide (/platform/quickstart/angular)

Create an account and learn how to start using Novu Inbox Notification in your angular application.

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import {
  Code2,
  Library,
  Workflow
} from 'lucide-react';
import { CodeTemplateBlock } from '@/components/quickstart/inbox-code';

This guide walks you through integrating Novu’s Inbox into your Angular application for real time in-app notifications, from setup to triggering your first notification. By the end, you'll have a working notification inbox.

<Callout type="info">
  This guide uses @novu/js javascript sdk to build the Inbox component in Angular. Novu currently does not support native Angular Inbox component.
</Callout>

<Steps>
  <Step>
    ## Create a Novu account

    <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer">Create a Novu account</a> or <a href="https://dashboard.novu.co/auth/sign-in" target="_blank" rel="noopener noreferrer">sign in</a> to access the Novu dashboard.
  </Step>

  <Step>
    ## Create an Angular application

    Run the following command to create a new Angular app using <a href="https://angular.dev/tools/cli/setup-local#install-the-angular-cli" target="_blank" rel="noopener noreferrer">angular cli</a>:

    ```bash
    ng new novu-inbox-angular
    cd novu-inbox-angular
    ```
  </Step>

  <Step>
    ## Install `@novu/js`

    The [Novu JavaScript SDK](/platform/sdks/javascript) gives you access to the Inbox component.

    Run the following command to install the SDK:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/js
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/js
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/js
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/js
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Add the Inbox component

    Update the `src/app/app.ts` file to add the Inbox component. You'll need to provide your :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."}:

    <CodeTemplateBlock templateId="angular-inbox" />

    If you’re signed in to your Novu account, then the :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."} are automatically entered in the code sample above. Otherwise, you can manually retrieve them:

    * `applicationIdentifier` - In the Novu dashboard, click API Keys, and then locate your unique Application Identifier.
    * `subscriberId` - This represents a user in your system (typically the user's ID in your database). For quick start purposes, an auto-generated subscriberId is provided for your Dashboard user.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ## Add the Inbox component to your application

    Add a `#novuInbox` reference to your application in the starting of the `src/app/app.html` file:

    ```html title="src/app/app.html"
    <div #novuInbox></div>
    ```
  </Step>

  <Step>
    ## Run Your Application

    Start your development server:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm run start
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm run start
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn run start
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun run start
        ```
      </Tab>
    </Tabs>

    Once the application is running, a bell icon will appear on the top left side of the screen. Clicking it opens the notification inbox UI.

    Currently, there are no notifications. Let’s trigger one!
  </Step>

  <Step>
    ## Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard-v2.novu.co/auth/sign-in).
    2. In the sidebar, click **Workflows**.
    3. Click **Create Workflow**. Enter a name for your workflow (e.g., "Welcome Notification").
    4. Click **Create Workflow** to save it.
    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.
    6. In the In-App template editor, enter the following:

    * **Subject**: "Welcome to Novu"
    * **Body**: "Hello, world! "

    7. Once you’ve added the subject and body, close the editor.
    8. Click **Trigger**.
    9. Click **Test Workflow**.
  </Step>

  <Step>
    ## View the notification in your app

    Go back to your Angular app, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Javascript SDK API Reference" icon={<Library />} href="/platform/sdks/javascript">
    Explore JavaScript SDK API reference for more advanced use cases.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu Next.js Quickstart Guide (/platform/quickstart/nextjs)

Set up Novu in-app notifications in your Next.js app. Install the SDK, add the Inbox component, and trigger your first notification.

import { Accordion, Accordions } from '@/components/accordion';
import { CodeBlock } from '@/components/codeblock';
import {
    BuildWorkflowStep,
    CreateAccountStep,
    CreateSubscriberStep,
    TriggerNotificationStep,
} from '@/components/quickstart/common-steps';
import { InboxCodeBlock } from '@/components/quickstart/inbox-code';
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import { SignedIn, SignedOut, SignInButton } from '@clerk/nextjs';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import {
  Code2,
  Library,
  Palette,
  Workflow
} from 'lucide-react';

Learn how to integrate Novu’s Inbox for real-time in-app notifications in your Next.js application. By the end of this guide, you’ll have a working notification inbox that displays messages triggered from the Novu dashboard.

<Steps>
  <Step>
    ### Create a Novu account

    <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer">Create a Novu account</a> or <a href="https://dashboard.novu.co/auth/sign-in" target="_blank" rel="noopener noreferrer">sign in</a> to access the Novu dashboard.
  </Step>

  <Step>
    ### Create a new Next.js application

    Run the following command to <a href="https://nextjs.org/docs/app/getting-started/installation" target="_blank">create a new Next.js application</a>:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm create next-app@latest
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm create next-app
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn create next-app
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx create-next-app
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Install `@novu/nextjs`

    Run the following command to install the Next.js Novu SDK:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/nextjs
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/nextjs
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/nextjs
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/nextjs
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Add the notification Inbox to your app

    Import Novu’s built-in <Method href="/platform/inbox">{`<Inbox />`}</Method> component into your layout file and place it in the navbar:

    <InboxCodeBlock />

    If you are signed in to your Novu account, then the :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's ID in your database."} will be automatically populated. Otherwise, retrieve them from:

    * `applicationIdentifier`: On the Novu dashboard, click **API Keys**, and copy your unique Application Identifier.
    * `subscriberId`: This represents a user in your system, usually the user ID from your database. For testing, you can use the auto-generated subscriberId from your Novu dashboard. You can locate it under the Subscribers tab on the Novu dashboard.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ### Run your application

    Start your development server:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm run dev
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun run dev
        ```
      </Tab>
    </Tabs>

    Once your application is running, you would see a **bell icon** in the navbar. Click on it, to open the notification Inbox UI.

    There are no notifications yet, so let’s trigger one!
  </Step>

  <Step>
    ### Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard.novu.co/auth/sign-in).
    2. Click **Workflows**.
    3. Click **Create Workflow** and then enter a name (e.g., "Welcome Notification").
    4. Click **Create Workflow** to save it.
    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.
    6. In the **In-App template editor**, enter:
       * **Subject**: "Welcome to Novu"
       * **Body**: "Hello, world!"
    7. Once you’ve added the subject and body, close the editor.
    8. Click **Trigger**.
    9. Click **Test Workflow**.
  </Step>

  <Step>
    ### View the notification in your app

    Go back to your Next.js app, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Styling" icon={<Palette />} href="/inbox/react/styling">
    Customize the look and feel of your Inbox to match your application's design.
  </Card>

  <Card title="Inbox and preferences UI components" icon={<Library />} href="/platform/inbox">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu React Quickstart Guide (/platform/quickstart/react)

Learn how to integrate the Novu Inbox component into a React application and add routing with React Router.

import { Accordion, Accordions } from '@/components/accordion';
import {
    BuildWorkflowStep,
    CreateAccountStep,
    CreateSubscriberStep,
    TriggerNotificationStep,
} from '@/components/quickstart/common-steps';
import { Step, Steps } from '@/components/steps';
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import {
  Code2,
  Library,
  Palette,
  Workflow
} from 'lucide-react';
import { CodeTemplateBlock } from '@/components/quickstart/inbox-code';

This guide walks you through integrating Novu’s Inbox into your React application for in-app notifications in real-time, from setup to triggering your first notification. By the end, you'll have a working notification inbox.

<Steps>
  <Step>
    ## Create a Novu account

    <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer">Create a Novu account</a> or <a href="https://dashboard.novu.co/auth/sign-in" target="_blank" rel="noopener noreferrer">sign in</a> to access the Novu dashboard.
  </Step>

  <Step>
    ## Create a React app using Vite

    Run the following command to create a new React app using [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project):

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm create vite@latest novu-inbox-react -- --template react-ts
        cd novu-inbox-react
        npm install
        npm run dev
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm create vite novu-inbox-react --template react-ts
        cd novu-inbox-react
        pnpm install
        pnpm run dev
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn create vite novu-inbox-react --template react-ts
        cd novu-inbox-react
        yarn install
        yarn dev
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx create-vite novu-inbox-react --template react-ts
        cd novu-inbox-react
        bun install
        bun run dev
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Install `@novu/react`

    The [Novu React SDK](/platform/sdks/react) gives you access to the Inbox component.

    Run the following command to install the SDK:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/react
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/react
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/react
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/react
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Create the Inbox component

    In the `src` directory, create a `components/novu-inbox.tsx` file and use the <Method href="/platform/inbox">{`<Inbox />`}</Method> component, passing :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."}:

    <CodeTemplateBlock templateId="react-inbox" />

    If you’re signed in to your Novu account, then the :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."} are automatically entered in the code sample above. Otherwise, you can manually retrieve them:

    * `applicationIdentifier` – In the Novu dashboard, click API Keys, and then locate your unique Application Identifier.
    * `subscriberId` – This represents a user in your system (typically the user's ID in your database). For quick start purposes, an auto-generated subscriberId is provided for your Dashboard user.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ## Set up React Router and import the Inbox component

    Now you can set up React Router and add the `NovuInbox` component to your app layout:

    ```tsx title="src/App.tsx"
    import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
    import { NovuInbox } from './components/novu-inbox';

    function Layout({ children }: { children: React.ReactNode }) {
      return (
        <div>
          <nav>
            <NovuInbox />
          </nav>
          {children}
        </div>
      );
    }

    function Home() {
      return <div>Welcome to the Home page!</div>;
    }

    function App() {
      return (
        <Router>
          <Layout>
            <Routes>
              <Route path="/" element={<Home />} />
              {/* Add your routes here */}
            </Routes>
          </Layout>
        </Router>
      );
    }

    export default App;
    ```
  </Step>

  <Step>
    ## Run Your Application

    Start your development server:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm run dev
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun run dev
        ```
      </Tab>
    </Tabs>

    Once the application is running, a bell icon will appear in the navbar. Clicking it opens the notification inbox UI.

    Currently, there are no notifications. Let’s trigger one!
  </Step>

  <Step>
    ## Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard.novu.co/auth/sign-in).

    2. In the sidebar, click **Workflows**.

    3. Click **Create Workflow**. Enter a name for your workflow (e.g., "Welcome Notification").

    4. Click **Create Workflow** to save it.

    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.

    6. In the In-App template editor, enter the following:

       * **Subject**: "Welcome to Novu"
       * **Body**: "Hello, world! "

    7. Once you’ve added the subject and body, close the editor.

    8. Click **Trigger**.

    9. Click **Test Workflow**.
  </Step>

  <Step>
    ## View the notification in your app

    Go back to your React app, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Styling" icon={<Palette />} href="/inbox/react/styling">
    Customize the look and feel of your Inbox to match your application's design.
  </Card>

  <Card title="Inbox and preferences UI components" icon={<Library />} href="/platform/inbox">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu Remix Quickstart Guide (/platform/quickstart/remix)

Integrate Novu in-app notifications into your Remix application. Follow step-by-step setup from install to first notification.

import { Accordion, Accordions } from '@/components/accordion';
import {
    BuildWorkflowStep,
    CreateAccountStep,
    CreateSubscriberStep,
    TriggerNotificationStep,
} from '@/components/quickstart/common-steps';
import { Step, Steps } from '@/components/steps';
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import {
  Code2,
  Library,
  Palette,
  Workflow
} from 'lucide-react';
import { CodeTemplateBlock } from '@/components/quickstart/inbox-code';

This guide walks you through integrating Novu’s Inbox into your Remix application for in-app notifications in real-time, from setup to triggering your first notification. By the end, you'll have a working notification inbox.

<Steps>
  <Step>
    ### Create a Novu account

    <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer">Create a Novu account</a> or <a href="https://dashboard.novu.co/auth/sign-in" target="_blank" rel="noopener noreferrer">sign in</a> to access the Novu dashboard.
  </Step>

  <Step>
    ### Create a Remix application

    Run the following command to create a new Remix app:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npx create-remix@latest
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx create-remix@latest
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx create-remix@latest
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun x create-remix@latest
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Install `@novu/react`

    The [Novu React SDK](/platform/sdks/react) gives you access to the Inbox component.

    Run the following command to install the SDK:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/react
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/react
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/react
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/react
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create an Inbox component

    In the `app` directory, create a `components/notification-center.tsx` file and use the <Method href="/platform/inbox">{`<Inbox />`}</Method> component, passing :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."}:

    <CodeTemplateBlock templateId="remix-inbox" />

    If you’re signed in to your Novu account, then the :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."} are automatically entered in the code sample above. Otherwise, you can manually retrieve them:

    * `applicationIdentifier` – In the Novu dashboard, click API Keys, and then locate your unique Application Identifier.
    * `subscriberId` – This represents a user in your system (typically the user's ID in your database). For quick start purposes, an auto-generated subscriberId is provided for your Dashboard user.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ### Add the Notification Center component to your layout

    Now you can import the `NotificationCenter` component and add it to your app layout:

    ```tsx title="app/root.tsx"
    import { NotificationCenter } from "~/components/notification-center";
    import type { MetaFunction } from "@remix-run/node";
    import {
      Links,
      LiveReload,
      Meta,
      Outlet,
      Scripts,
      ScrollRestoration,
    } from "@remix-run/react";

    export const meta: MetaFunction = () => {
      return [
        { title: "New Remix App" },
        { name: "description", content: "Welcome to Remix!" },
      ];
    };

    export default function App() {
      return (
        <html lang="en">
          <head>
            <Meta />
            <Links />
          </head>
          <body>
            <nav>
              <NotificationCenter />
            </nav>
            <Outlet />
            <ScrollRestoration />
            <Scripts />
            <LiveReload />
          </body>
        </html>
      );
    }
    ```
  </Step>

  <Step>
    ### Run Your Application

    Start your development server:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm run dev
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun run dev
        ```
      </Tab>
    </Tabs>

    Once the application is running, a bell icon will appear in the navbar. Clicking it opens the notification inbox UI.

    Currently, there are no notifications. Let’s trigger one!
  </Step>

  <Step>
    ### Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard.novu.co/auth/sign-in).

    2. In the sidebar, click **Workflows**.

    3. Click **Create Workflow**. Enter a name for your workflow (e.g., "Welcome Notification").

    4. Click **Create Workflow** to save it.

    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.

    6. In the In-App template editor, enter the following:

       * **Subject**: "Welcome to Novu"
       * **Body**: "Hello, world! "

    7. Once you’ve added the subject and body, close the editor.

    8. Click **Trigger**.

    9. Click **Test Workflow**.
  </Step>

  <Step>
    ### View the notification in your app

    Go back to your React app, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Styling" icon={<Palette />} href="/inbox/react/styling">
    Customize the look and feel of your Inbox to match your application's design.
  </Card>

  <Card title="Inbox and preferences UI components" icon={<Library />} href="/platform/inbox">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu Vanilla JS Quickstart Guide (/platform/quickstart/vanilla-js)

Learn how to integrate the Novu Inbox component into a Vanilla JS and HTML project.

import { Accordion, Accordions } from '@/components/accordion';
import {
    BuildWorkflowStep,
    CreateAccountStep,
    CreateSubscriberStep,
    TriggerNotificationStep,
} from '@/components/quickstart/common-steps';
import { Step, Steps } from '@/components/steps';
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import {
  Code2,
  Library,
  Palette,
  Workflow
} from 'lucide-react';
import { CodeTemplateBlock } from '@/components/quickstart/inbox-code';

This guide walks you through integrating Novu’s Inbox into your Vanilla JS and HTML project for in-app notifications in real-time, from setup to triggering your first notification. By the end, you'll have a working notification inbox.

<Steps>
  <Step>
    ### Add Novu ESM script

    Add the following code to your HTML file:

    ```html title="index.html"
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Novu Inbox - Vanilla JS</title>

      <!-- Novu Styles (important for proper UI rendering) -->
      <link
        rel="stylesheet"
        href="https://unpkg.com/@novu/js@3.11.0/dist/index.css"
      />
      <style>
        /*
          Example: hide the 3rd option in the Inbox status dropdown.
          (We add stable custom classes via `appearance.elements.*` and then use plain CSS.)
        */
        .hide-snooze-dropdown-item:nth-child(3) {
          display: none !important;
        }

        .hide-snooze-button {
          display: none !important;
        }
      </style>
    </head>
    <body>
      <h2>Novu Inbox - Vanilla JS Demo</h2>

      <!-- Mount point: Novu will inject Inbox UI here -->
      <div id="novu-inbox"></div>

      <!--
      Novu UI for vanilla HTML:
      - The published UI entrypoint is ESM and has dependencies (SolidJS, etc.)
      - esm.sh bundles those deps so it can run directly in the browser.
    -->
      <script type="module">
        import { NovuUI } from "https://esm.sh/@novu/js@3.11.0/ui?bundle";

        document.addEventListener("DOMContentLoaded", () => {
          const mountEl = document.getElementById("novu-inbox");
          if (!mountEl) {
            console.error("Missing #novu-inbox mount element");
            return;
          }

          const novu = new NovuUI({
            options: {
              applicationIdentifier: "NOVU_APPLICATION_IDENTIFIER",
              subscriberId: "NOVU_SUBSCRIBER_ID",
            },

            // to hide the snooze button and the 3rd option in the Inbox status dropdown
            appearance: {
              elements: {
                notificationSnooze__button: "hide-snooze-button",
                inboxStatus__dropdownItem: "hide-snooze-dropdown-item",
              },
            },
          });

          // Mount Inbox into #novu-inbox
          novu.mountComponent({
            name: "Inbox",
            props: {
              onNotificationClick: (notification) => {
                console.log("notification clicked", notification);
              },
            },
            element: mountEl,
          });

          // Optional cleanup example
          window.addEventListener("beforeunload", () => {
            novu.unmountComponent(mountEl);
          });
        });
      </script>
    </body>
    </html>

    ```
  </Step>

  <Step>
    ### Change subscriberId and applicationIdentifier

    In above code, replace `NOVU_APPLICATION_IDENTIFIER` with actual :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} value and `NOVU_SUBSCRIBER_ID` with actual :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."} value.

    * `applicationIdentifier` – In the Novu dashboard, click API Keys, and then locate your unique Application Identifier.
    * `subscriberId` – This represents a user in your system (typically the user's ID in your database). For quick start purposes, an auto-generated subscriberId is provided for your Dashboard user.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ### Run Your Application

    Open `index.html` in your browser. You should see the Novu Inbox component with a bell icon.
  </Step>

  <Step>
    ### Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard.novu.co/auth/sign-in).

    2. In the sidebar, click **Workflows**.

    3. Click **Create Workflow**. Enter a name for your workflow (e.g., "Welcome Notification").

    4. Click **Create Workflow** to save it.

    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.

    6. In the In-App template editor, enter the following:

       * **Subject**: "Welcome to Novu"
       * **Body**: "Hello, world! "

    7. Once you’ve added the subject and body, close the editor.

    8. Click **Trigger**.

    9. Click **Test Workflow**.
  </Step>

  <Step>
    ### View the notification in your app

    Open `index.html` in your browser, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Styling" icon={<Palette />} href="/inbox/react/styling">
    Customize the look and feel of your Inbox to match your application's design.
  </Card>

  <Card title="Inbox and preferences UI components" icon={<Library />} href="/platform/inbox">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu Vue Quickstart Guide (/platform/quickstart/vue)

Create an account and learn how to start using Novu Inbox in your vue application.

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
import {
  Code2,
  Library,
  Workflow
} from 'lucide-react';
import { CodeTemplateBlock } from '@/components/quickstart/inbox-code';

This guide walks you through integrating Novu's Inbox into your Vue application for real time in-app notifications, from setup to triggering your first notification. By the end, you'll have a working notification inbox.

<Callout type="info">
  This guide uses @novu/js javascript sdk to build the Inbox component in Vue. Novu currently does not support native Vue Inbox component.
</Callout>

<Steps>
  <Step>
    ### Create a Novu account

    <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer">Create a Novu account</a> or <a href="https://dashboard.novu.co/auth/sign-in" target="_blank" rel="noopener noreferrer">sign in</a> to access the Novu dashboard.
  </Step>

  <Step>
    ### Create a Vue application

    Run the following command to create a new Vue app:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm create vue@latest novu-inbox-vue
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm create vue novu-inbox-vue
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn create vue novu-inbox-vue
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx create-vue novu-inbox-vue
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Install `@novu/js`

    The [Novu JavaScript SDK](/platform/sdks/javascript) gives you access to the Inbox component.

    Run the following command to install the SDK:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/js
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/js
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/js
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/js
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Add the Inbox component

    Create the `src/components/NovuInbox.vue` file to add the Inbox component passing :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."}:

    <CodeTemplateBlock templateId="vue-inbox" />

    If you're signed in to your Novu account, then the :tooltip\[applicationIdentifier]{label="The application identifier is a unique identifier for your application. You can find it in the Novu Dashboard under the API keys page."} and :tooltip\[subscriberId]{label="The subscriber ID is the unique identifier for the user in your application, typically the user's id in your database."} are automatically entered in the code sample above. Otherwise, you can manually retrieve them:

    * `applicationIdentifier` - In the Novu dashboard, click API Keys, and then locate your unique Application Identifier.
    * `subscriberId` - This represents a user in your system (typically the user's ID in your database). For quick start purposes, an auto-generated subscriberId is provided for your Dashboard user.

    <Callout type="info">
      **Note:** If you pass a `subscriberId` that does not exist yet, Novu will automatically create a new subscriber with that ID.
    </Callout>
  </Step>

  <Step>
    ### Add the Inbox component to your application

    Import and use the `NovuInbox` component in `src/App.vue` file:

    ```vue title="src/App.vue"
    <script setup lang="ts">
    import NovuInbox from "./components/NovuInbox.vue";
    </script>

    <template>
      <NovuInbox />
    </template>
    ```
  </Step>

  <Step>
    ### Run Your Application

    Start your development server:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm run start
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm run start
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn run start
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun run start
        ```
      </Tab>
    </Tabs>

    Once the application is running, a bell icon will appear on the top left side of the screen. Clicking it opens the notification inbox UI.

    Currently, there are no notifications. Let's trigger one!
  </Step>

  <Step>
    ### Trigger your first notification

    In this step, you'll create a simple workflow to send your first notification via the Inbox component. Follow these steps to set up and trigger a workflow from your Novu dashboard.

    1. Go to your [Novu dashboard](https://dashboard-v2.novu.co/auth/sign-in).
    2. In the sidebar, click **Workflows**.
    3. Click **Create Workflow**. Enter a name for your workflow (e.g., "Welcome Notification").
    4. Click **Create Workflow** to save it.
    5. Click the **Add Step** icon in the workflow editor and then select **In-App** as the step type.
    6. In the In-App template editor, enter the following:

    * **Subject**: "Welcome to Novu"
    * **Body**: "Hello, world! "

    7. Once you've added the subject and body, close the editor.
    8. Click **Trigger**.
    9. Click **Test Workflow**.
  </Step>

  <Step>
    ### View the notification in your app

    Go back to your Vue app, then click the bell icon.

    You should see the notification you just sent from Novu! 🎉
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Javascript SDK API Reference" icon={<Library />} href="/platform/sdks/javascript">
    Explore JavaScript SDK API reference for more advanced use cases.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow">
    Design and manage advanced notification workflows.
  </Card>

  <Card title="Multi Tenancy" icon={<Code2 />} href="/platform/concepts/tenants">
    Manage multiple tenants within an organization.
  </Card>
</Cards>


# Novu SDKs Overview (/platform/sdks)

Explore Novu's server-side and client-side SDKs for integrating notifications across multiple languages and frameworks.

import { Card, Cards } from 'fumadocs-ui/components/card';
/* server side icons */
import { DotnetIcon } from '@/components/icons/dotnet';
import { GolangIcon } from '@/components/icons/golang';
import { JavaIcon } from '@/components/icons/java';
import { LaravelIcon } from '@/components/icons/laravel';
import { PhpIcon } from '@/components/icons/php';
import { PythonIcon } from '@/components/icons/python';
import { RubyIcon } from '@/components/icons/ruby';
import { KotlinIcon } from '@/components/icons/kotlin';
/* client side icons */
import { ReactIcon } from '@/components/icons/react';
import { TypescriptIcon } from '@/components/icons/typescript';
import { JavascriptIcon } from '@/components/icons/javascript';

## Server-side SDKs

### API SDKs

Novu's server-side SDKs simplify the integration with Novu's REST API.

#### Offical SDKs maintained by Novu:

<Cards cols={2}>
  <Card title="Typescript (Official)" icon={<TypescriptIcon />} color="#ea5a0c" href="/platform/sdks/server/typescript">
    Connect your Node app to Novu via the Node.js SDK.
  </Card>

  <Card title="Python (Official)" icon={<PythonIcon />} color="#dc2626" href="/platform/sdks/server/python">
    Connect your Python app to Novu via the Python SDK.
  </Card>

  <Card title="Go (Official)" icon={<GolangIcon />} color="#0285c7" href="/platform/sdks/server/go">
    Connect your Golang app to Novu via the Go SDK.
  </Card>

  <Card title="PHP (Official)" icon={<PhpIcon />} color="#16a34a" href="/platform/sdks/server/php">
    Connect your PHP app to Novu via the PHP SDK.
  </Card>

  <Card title=".NET (Official)" icon={<DotnetIcon />} color="#dc2626" href="/platform/sdks/server/dotnet">
    Connect your C#/.NET app to Novu via the .NET SDK.
  </Card>

  <Card title="Java (Official)" icon={<JavaIcon />} color="#dc2626" href="/platform/sdks/server/java">
    Connect your Java app to Novu via the Java SDK.
  </Card>
</Cards>

#### SDKs maintained by the community:

<Cards cols={2}>
  <Card title="Laravel (Community)" icon={<LaravelIcon />} color="#dc2626" href="/platform/sdks/server/laravel">
    Connect your Laravel app to Novu via the Laravel SDK.
  </Card>

  <Card title="Kotlin (Community)" icon={<KotlinIcon />} color="#dc2626" href="/platform/sdks/server/kotlin">
    Connect your Kotlin app to Novu via the Kotlin SDK.
  </Card>

  <Card title="Ruby (Community)" icon={<RubyIcon />} color="#dc2626" href="/platform/sdks/server/ruby">
    Connect your Ruby app to Novu via the Ruby SDK.
  </Card>
</Cards>

### Framework SDK

The Framework SDK is a TypeScript library that allows you to build notification workflows and execute them in your own runtime environment.

<Callout type="info">
  While triggering notifications is supported in all SDKs, creating and managing notification
  workflows is only supported in the Framework Typescript SDK.
</Callout>

<Cards>
  <Card title="Typescript" icon={<TypescriptIcon />} href="/framework/typescript/overview">
    Build and execute notification workflows in TypeScript
  </Card>
</Cards>

## Web and Mobile SDKs

Novu provides the following web client SDKs to enable integrations with Novu's prebuilt UI components, allowing you to easily add notification functionality to your applications without handling complex notification logic manually.

<Cards>
  <Card title="React" icon={<ReactIcon />} href="/platform/inbox/setup-inbox">
    Official React SDK for Novu's notification center
  </Card>

  <Card title="Headless" icon={<JavascriptIcon />} href="/platform/inbox/headless-mode">
    Framework-agnostic SDK for custom implementations
  </Card>

  <Card title="React-Native" icon={<ReactIcon />} href="/platform/sdks/react-native">
    Official React Native SDK for mobile applications
  </Card>
</Cards>


# Customize and configure (/platform/subscription/customize-and-configure)

Learn how to filter visible preferences, customize styling, and use custom render functions.

The Subscription UI works within the existing Novu environment and uses the same provider and styling architecture as the <Method href="/platform/inbox">{`<Inbox />`}</Method> component.

You can configure which options are visible to your users, apply your brand's theme, or take full control of the rendering.

## Filter using preferences

The `preferences` prop on the <Method href="/platform/subscription/overview">{`<Subscription />`}</Method> component controls which workflows the component displays to the user.

### Default preferences

If you want to simply filter which workflows are visible without changing their labels, then you can pass an array of workflow identifier strings. The component uses the workflow names defined in the Dashboard as the labels.

```tsx
import { NovuProvider, Subscription } from '@novu/react';

export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
        topicKey="product-updates"
        identifier="user-123"
        // Only shows these two workflows
        preferences={["workflow-identifier-1", "workflow-identifier-2"]}
      />
    </NovuProvider>
  )
}
```

### Custom preferences

You can filter using tags, workflow IDs, or both. You can also customize the labels, descriptions, or default states by passing an array of objects.

```tsx
import { NovuProvider, Subscription,  } from '@novu/react';

export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription 
        topicKey="product-updates"
        identifier="user-123"
        preferences={[
          {
            workflowId: "comment-on-task",
            label: "New Comments",
            enabled: true, // Force enabled by default
          },
          {
            // Group multiple workflows under one label and filter using tags
            filter: { tags: ['security', 'admin'] },
            label: 'Security Alerts',
            enabled: false,
          },
          {
            // Group multiple workflows under one label and filter using workflow id
            filter: { workflowIds: ['test-workflow1', 'test-workflow2'] },
            label: 'Test Group',
            enabled: false,
          },
        ]}
      />
    </NovuProvider>
  );
}
```

You can also update the labels for the workflows with the `dynamic` prop of the localization. For full localization options, see the [Inbox localization documentation](/platform/inbox/advanced-features/localization).

## Styling

The <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component shares the same styling architecture as the Inbox component. You can use the `appearance` prop to customize elements, variables, icons and themes.

For full styling and theming options, see the [Inbox styling documentation](/platform/inbox/configuration/styling).

### Dark mode

Novu provides `subscriptionDarkTheme` in the `@novu/react/themes` package to apply the built-in dark theme to the <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component. You can apply this conditionally based on your app's state.

```tsx
import { NovuProvider, Subscription } from '@novu/react';
import { subscriptionDarkTheme } from '@novu/react/themes';

export function Novu() {
  const isDarkMode = true;
  
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
        topicKey="product-updates"
        identifier="user-123"
        appearance={{
          baseTheme: isDarkMode ? subscriptionDarkTheme : undefined,
        }}
      />
    </NovuProvider>
  );
}
```

### Localization

You can customize the text labels used in the component to support different languages or to match your app's voice. This works identically to Inbox localization.

```tsx
import { NovuProvider, Subscription } from '@novu/react';
 
export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
        topicKey="product-updates"
        identifier="user-123"
        localization={{
          "subscription.subscribe": "Join",
          locale: "en-US",
        }}
      />
    </NovuProvider>
  );
}
```

For full localization options, see the [Inbox localization documentation](/platform/inbox/advanced-features/localization).

## Custom rendering

The `renderPreferences` prop on the <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component lets you override how the component displays the list of workflows while still relying on the component to handle data fetching and state management.

The function receives the current `subscription` object and a `loading` boolean. You can map over the `preferences` array and render your own HTML elements.

```tsx
import { NovuProvider, Subscription, TopicSubscription } from '@novu/react';

export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
        topicKey="product-updates"
        identifier="user-123"
        preferences={["workflow-1", "workflow-2"]}
        renderPreferences={(subscription?: TopicSubscription, loading?: boolean) => (
          <div>
            {subscription?.preferences.map((preference, idx) => (
              <div key={`${subscription.identifier}-${idx}`}>
                <label htmlFor={`pref-${idx}`}>{preference.label}</label>
                <span>{preference.description}</span>
                <input
                  id={`pref-${idx}`}
                  type="checkbox"
                  checked={preference.enabled}
                  onChange={(e) =>
                    preference.update({ value: e.target.checked })
                  }
                />
              </div>
            ))}
          </div>
        )}
      />
    </NovuProvider>
  )
}
```


# Headless hooks (/platform/subscription/headless-hooks)

Build a fully custom Subscription interface using hooks.

Novu `@novu/react` package provides Subscription hooks that let you build your own custom subscription experiences from scratch.

These hooks allow you to list, create, update, and delete subscriptions while leveraging Novu's state management.

<Callout type="info"> Hooks are available in [`@novu/nextjs`](/platform/sdks/react), [`@novu/react-native`](/platform/sdks/react-native), [`@novu/react`](/platform/sdks/react). For a complete reference on all available Subscription endpoints, refer to the [API reference documentation](/platform/sdks/react/hooks/subscription).</Callout>

## List all subscriptions

The `useSubscriptions` hook retrieves all subscriptions associated with a specific topic for the current subscriber. This is useful for rendering a list of "My Subscriptions," where subscribers can view all the subscriptions they've subscribed to.

The `subscriptions` array contains `TopicSubscription` objects. You can refer to the [TopicSubscription interface](/api-reference/topics/topic-schema#topicsubscription) for the full type definition.

```tsx
import { useSubscriptions } from '@novu/react';

function SubscriptionList() {
  const { subscriptions, isLoading } = useSubscriptions({ 
    topicKey: 'product-updates' 
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {subscriptions.map((subscription) => (
        <li key={subscription.id}>
          <h3>{subscription.name}</h3>
+         {/* Render your custom subscription UI here */}
        </li>
      ))}
    </ul>
  );
}
```

## Retrieve a single subscription

If you need to manage a specific subscription instance, then use the `useSubscription` hook. This hook fetches the details and preferences for a single subscription.

```tsx
import { useSubscription } from '@novu/react';

function ProjectSettings() {
  const { subscription, isLoading } = useSubscription({ 
    topicKey: 'project-123',
    identifier: 'user-project-alert'
  });

  if (isLoading) return <div>Loading...</div>;

  if (!subscription) return <div>You are not subscribed to this project.</div>;

  return (
    <div>
       <h3>{subscription.name}</h3>
       {/* Render preferences or other subscription details */}
    </div>
  );
}
```

## Create a subscription

To allow users to opt-in to a topic, use the `useCreateSubscription` hook. This is often used on "Follow" or "Subscribe" buttons.

```tsx
import { useCreateSubscription } from '@novu/react';

function SubscribeButton() {
  const { create, isCreating } = useCreateSubscription();

  const handleSubscribe = async () => {
    const { data, error } = await create({ 
      topicKey: 'project-123', 
      identifier: 'user-project-alert',
      // Optional: Set initial preferences
      preferences: [] 
    });

    if (error) {
        console.error('Failed to subscribe', error);
        return;
    }
    
    console.log('Subscribed successfully!', data);
  };

  return (
    <button onClick={handleSubscribe} disabled={isCreating}>
      {isCreating ? 'Subscribing...' : 'Subscribe to Updates'}
    </button>
  );
}
```

## Update a subscription

Use `useUpdateSubscription` to modify an existing subscription. This is primarily used to toggle workflow preferences, enabling, or disabling specific notifications within the subscription.

```tsx
import { useUpdateSubscription } from '@novu/react';

function PreferenceToggle({ identifier, preferences, name, topicKey }) {
  const { update, isUpdating } = useUpdateSubscription();

  const savePreferences = async () => {
    await update({
      topicKey,
      identifier,
      name,
      preferences,
    });
  };

  return (
    <button onClick={savePreferences} disabled={isUpdating}>
      Save preferences
    </button>
  );
}
```

### Update a single preference

If you need to update a single preference, use the dedicated helpers available on the subscription object, such as:

* `subscription.updatePreference(...)`, or
* mapping over `subscription.preferences` and calling `preference.update(...)`

```tsx
import { useSubscription } from '@novu/react';

function PreferenceList() {
  const { subscription } = useSubscription({ 
    topicKey: 'project-123',
    identifier: 'user-project-alert'
  });

  if (!subscription) return null;

  return (
    <div>
      {subscription.preferences.map((preference) => (
        <div key={preference.workflowId}>
          <label>{preference.label}</label>
          <input 
            type="checkbox" 
            checked={preference.enabled} 
            // Update the preference directly using the instance method
            onChange={(e) => preference.update({ value: e.target.checked })}
          />
        </div>
      ))}
    </div>
  );
}
```

## Delete a subscription

To allow users to opt out or unsubscribe, use the `useRemoveSubscription` hook.

```tsx
import { useRemoveSubscription } from '@novu/react';

function UnsubscribeButton({ identifier: string, topicKey: string }) {
  const { remove, isRemoving } = useRemoveSubscription();

  const handleUnsubscribe = async () => {
    await remove({ 
      identifier,
      topicKey,
    });
  };

  return (
    <button onClick={handleUnsubscribe} disabled={isRemoving}>
      {isRemoving ? 'Removing...' : 'Unsubscribe'}
    </button>
  );
}
```


# Subscription preferences (/platform/subscription)

Learn what a Subscription is in Novu, how they fit into the notification system.

Subscriptions introduce topic-level settings that allow subscribers to decide exactly which notifications they want to receive or mute.

While standard preferences allow subscribers to toggle specific channels on or off, Subscriptions provide more precise control through conditional rules. With Subscriptions, subscribers can mute topics, subscribe or unsubscribe to them, and also define conditions that determine when Novu should deliver a notification.

## How subscription fits into the notification flow

The Subscription introduces a filtering layer between the trigger and the subscriber. When you trigger a notification to a topic key, the system doesn't automatically send it to everyone. Instead, it follows this evaluation flow:

1. **Trigger**: You trigger a workflow to a `topicKey` and include a data payload.
2. **Match**: Novu retrieves all subscribers associated with that topic.
3. **Evaluate**: The system checks the conditions and preferences of each subscription against the payload.
4. **Deliver**: Only subscribers whose conditions match the payload receive the notification.

This filtering happens for every event on a topic, which allows you to support many use cases, including advanced preferences, segmentation, and multi-tenant experiences.

<Callout type="info">Workflow and global settings control delivery and take precedence. If a subscriber has disabled email notifications globally, then they won't receive email notifications for a subscription, even if the subscription condition is met.</Callout>

## Core concepts

To implement Subscriptions effectively, you should understand these components:

* **Topic**: A topic groups notifications of a similar type. Refer to the [Topics documentation](/platform/concepts/topics) for details on how to create and manage them.
* **Subscribers**: A subscriber represents the user or entity that receives notifications. Subscribers can join or leave topics and define preferences that control delivery. Refer to the [Subscribers documentation](/platform/concepts/subscribers) for details on how to create and manage subscribers.

### Subscription rules

Each subscription can include one or more conditions. Conditions determine whether an event should trigger a notification for that subscriber. You can define available conditions in your UI, and subscribers choose which ones apply to them.

### Multiple subscriptions per topic

Novu supports a 1-to-N relationship for subscriptions. This means, one subscriber can have multiple subscriptions to the same topic with different conditions. Novu evaluates each subscription independently.

For example, in a trading app, a subscriber can have three separate alerts set up for the same `price-alerts` topic:

* Notify me when BTC is above $80k.
* Notify me when BTC is below $40k.
* Notify me when ETH is above $4k.

Novu stores these configurations per subscriber, per topic, and per workflow.

## Subscription components

Novu provides a set of pre-built React components that you can use together or independently to build subscription experiences.

![Subscription components](/images/subscription-preferences/subscription.png)

### `<Subscription />`

The <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component serves as the root provider and the default UI.

It requires the `topicKey` prop and optionally an `identifier` prop, and you must wrap it with the Novu provider as the source of session context.

```tsx
import { NovuProvider, Subscription } from '@novu/react';

export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
        topicKey="product-updates"
        identifier="user-123"
      />
    </NovuProvider>
  )
}
```

### `<SubscriptionButton />`

The `<SubscriptionButton />` component renders only the subscribe or unsubscribe action. This is useful when you want to place a subscription control inline.

Use this component within the <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component.

```tsx
import { NovuProvider, Subscription, SubscriptionButton } from '@novu/react';

export function Novu() {
  return (
    <NovuProvider 
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
      >
        <Subscription
          topicKey="product-updates"
          identifier="user-123"
        >
          <SubscriptionButton />
        </Subscription>
    </NovuProvider>
  )
}
```

### `<SubscriptionPreferences />`

The `<SubscriptionPreferences />` component renders the list of preferences associated with a subscription. Preferences typically map to workflows or workflow groups within a topic.

Use this component when you want to control where and how preferences appear in your UI. Use it within a <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> context.

```tsx
import {NovuProvider, Subscription, SubscriptionPreferences } from '@novu/react';

export function Novu() {
    return (
      <NovuProvider 
        subscriber="SUBSCRIBER_ID"
        applicationIdentifier="APPLICATION_IDENTIFIER"
        >
        <Subscription
          topicKey="product-updates"
          identifier="user-123"
        >
          <SubscriptionPreferences />
        </Subscription>
      </NovuProvider>
    )
}
```

## How Subscriptions relate to the Inbox

If you use the <Method href="/platform/inbox">{`<Inbox />`}</Method>, then subscriptions determine which notifications appear in a subscriber's feed. When a subscriber joins a topic, the <Method href="/platform/inbox">{`<Inbox />`}</Method> shows notifications from that topic according to the subscriber's selected conditions. If the subscriber mutes the topic or sets rules that don't match an event, then the Inbox doesn't show those messages to that subscriber.

Subscriptions work with or without the <Method href="/platform/inbox">{`<Inbox />`}</Method>, and have a standalone <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component.


# <Subscription /> Quickstart Guide (/platform/subscription/quickstart)

Learn how to integrate and render the Subscription component in your React app to manage user preferences.

import { Step, Steps } from '@/components/steps';
import {
  Code,
  Blocks
} from 'lucide-react';

<Callout>Subscription is avialable from v3.12.0 for the `@novu/nextjs`, `@novu/react` and `@novu/js` packages.</Callout>

This quickstart shows how to render the subscription UI in your app. The subscription UI lets users subscribe to topics, define conditions, and manage how they receive notifications.

<Callout>To learn how to render custom UI for the Subscription preferences, refer to the [Headless hooks documentation](/platform/subscription/headless-hooks).</Callout>

The <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component is designed to work within an existing Novu environment and uses the same provider and session context as the Inbox component.

<Steps>
  <Step>
    ### Create a topic

    Subscriptions are managed at the topic level. You can create a topic manually in the Novu Dashboard or via the API.

    However, you don't have to create it beforehand. If the topic key you provide to the component does not exist, Novu will automatically create it for you.

    Topics can represent any category of notifications. To learn more, see the [Topics documentation](/platform/concepts/topics).
  </Step>

  <Step>
    ### Install `@novu/nextjs`

    Ensure you have the latest version of the `@novu/nextjs` package installed in your project.

    ```bash
    npm install @novu/nextjs
    ```
  </Step>

  <Step>
    ### Initialize the Novu client

    Wrap your app or the specific section where the subscription component would live with the `<NovuProvider>`. Configure the provider with your `applicationIdentifier` and the current user's `subscriberId`.

    ```tsx
    import { NovuProvider } from '@novu/nextjs';

    const NOVU_CONFIG = {
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    };

    function App() {
      return (
        <NovuProvider {...NOVU_CONFIG}>
          {/* Application content */}
        </NovuProvider>
      );
    }
    ```
  </Step>

  <Step>
    ### Add the component

    Place the <Method href="/platform/subscription/quickstart">{`<Subscription />`}</Method> component inside the provider. You must pass the `topicKey`.

    The `identifier` prop is optional, you only need to provide it if you intend to manage multiple distinct subscriptions for the same topic.

    ```tsx
    import { NovuProvider, Subscription } from '@novu/nextjs';

    const NOVU_CONFIG = {
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    };

    function App() {
      return (
        <NovuProvider {...NOVU_CONFIG}>
          <Subscription
            topicKey="project-123"
            identifier="project-updates"
          />
        </NovuProvider>
      );
    }
    ```
  </Step>
</Steps>

## Next steps

<Cards cols={2}>
  <Card title="Customize the UI" icon={<Blocks />} href="/platform/subscription/customize-and-configure">
    Customize and configure the Subscription component appearance and behavior.
  </Card>

  <Card title="Overview" icon={<Code />} href="/platform/subscription/overview">
    Learn how Subscriptions work and explore the available components.
  </Card>
</Cards>


# How to configure Workflow in Novu (/platform/workflow/configure-workflow)

Configure workflow metadata, delivery preferences, and payload schema in the workflow editor.

After creating a workflow, you are redirected to the workflow editor, where you configure workflow-level settings. You can also open any existing workflow from the Workflows page to access the editor.

In the **Configure workflow** section, you can update workflow metadata, control delivery behavior, and define the workflow payload schema.

![Configure workflow](/images/workflows/configure-workflow/configure-workflow.png)

## Workflow status

A workflow is active by default after creation. Disabling a workflow pauses execution and prevents triggers from running.

Workflows can exist in one of three states:

* **Active**: This means the workflow can be triggered.
* **Inactive**: This means the workflow is paused. It cannot be triggered, but you can still edit its structure or steps.
  ![Active workflow](/images/workflows/configure-workflow/active-workflow.gif)
* **Action required**: This means the workflow contains one or more errors, such as missing required fields or unconnected channels. It can still be triggered.

## Tags

Tags are labels or categories that help you organize and manage workflows. By grouping workflows under specific tags, you better control how they're filtered, displayed, and managed.

Tags help keep things tidy and manageable for both you and your team and you can add up to 16 tags per workflow.

Tags can be used to:

* Conditionally display notifications in the <Method href="/platform/inbox/advanced-customization/conditional-display">{`<Inbox />`}</Method> or filter workflows in <Method href="/platform/subscription/customize-and-configure#custom-preferences">{`<Subscription />`}</Method>.
* Filter and search for workflows in the dashboard.
* [Retrieve](/api-reference/workflows/retrieve-a-workflow) or [list workflows](/api-reference/workflows/list-all-workflows) via the Novu API.

### Add a workflow tag

1. In the workflow editor, find the Tags field.
2. Type tag name, If tag already exists, it will be suggested.
3. If tag does not exist, you can create it by pressing Enter.

### Remove a workflow tag

* Click the X icon next to the tag name to remove tag from the workflow.

![Add tags](/images/workflows/configure-workflow/add-tags.gif)

## Channel preferences

Workflow channel preferences let you set default channel preferences for subscribers. For all new subscribers, the channel preferences will be set to the default preferences set for the workflow. Read more about [channel preferences](/platform/concepts/preferences).

![Channel preferences](/images/workflows/configure-workflow/channel-preferences.png)

### Critical workflows

Novu allows you to mark a workflow as critical, this means that the notification sent from that workflow must always be delivered to the subscribers regardless of their personal preferences and they cannot change their preferences for this workflow.

This is useful for high-priority notifications that are related to security, financial, or access-related information, where missing a message could have some consequences.

### Notification severity

Notification severity lets you classify workflows by importance, helping subscribers quickly identify urgent notifications. Each workflow can be assigned one of four severity levels:

* **High**: Critical notifications that require immediate attention
* **Medium**: Important notifications that are not critical
* **Low**: General or informational notifications
* **None**: The default level for all new and existing workflows

You can set the severity for a workflow in the Novu dashboard by selecting a value from the **Notification severity** list.

![Notification Severity](/images/workflows/configure-workflow/notification-severity.png)

Severity levels affect how notifications appear in the Novu <Method href="/platform/inbox">{`<Inbox />`}</Method>. By default, severity controls visual cues such as color, icons, and the bell indicator, helping users prioritize messages at a glance:

* **High**: Red hue
* **Medium**: Orange hue
* **Low**: No color
* **None**: Default styling

These default styles are [customizable](/platform/inbox/configuration/styling#style-notifications-by-severity).

## Payload schema

The Payload schema defines, manages, and validates the structure of data sent to a workflow. By defining a schema, you ensure that payload object, while triggering the workflow, is predictable, type-safe, and consistent across environments.

<Callout>Novu’s payload schema is based on the [JSON Schema](https://json-schema.org/) standard.</Callout>

The schema acts as a contract between your systems and Novu, defining which variables exist, how they are structured, and what validation rules apply. This gives your team a shared, explicit source of truth for workflow data.

You can reference payload schema fields in the template editor, action step configuration, and step conditions to insert dynamic content and build data-driven logic. Payload schemas are especially useful for complex workflows that rely on reusable components, dynamic payloads, or strict validation requirements

**Benefits of defining a payload schema**

With a defined schema in place, you can:

* Prevent unexpected runtime errors caused by invalid or missing data.
* Build reliable conditional logic using type-aware operators.
* Generate accurate previews powered by intelligent mock data.
* Enable autocomplete suggestions when referencing payload variables.

### Schema properties

Each schema property includes the following fields:

* **Property name**: Must start with a letter or underscore, and contain only letters, numbers, underscores, or hyphens.
* **Property type**: You can either select a string, integer, number, boolean, enum, array, object, or null.
* **Required**: You can mark a property as required. Required properties must be included in the payload when triggering the workflow using `novu.trigger()` method.
* **Schema configuration**: Additional validation and type-specific settings.
* **Delete**: Remove the property from the schema.

### Define workflow schema

Each property you define becomes part of the payload schema, and helps Novu suggest accurate variables when configuring channel steps or digest actions.
You can define the expected payload schema in three ways:

#### Manually

Manually define each property by specifying its name, type, and validation rules from the **Manage workflow schema** section.

![Manage payload schema manually](/images/workflows/configure-workflow/workflow-payload.gif)

#### Import from JSON

If you already have a sample payload, you can import it as a JSON object from the **Manage workflow schema** section. Novu automatically infers property names, types, and nested structures.

![Import from JSON](/images/workflows/configure-workflow/import-payload.gif)

#### Create an inline variable

While adding notification content in the template editors, you can reference a variable that doesn’t exist in the schema (for example, `payload.title`). Novu will prompt you to create the variable inline and add it to your schema with a default type of `String`.

After creating the variable, you can edit it from the **Manage payload schema** directly in the template editor.

![Create inline variable](/images/workflows/configure-workflow/inline-variable.gif)

<Callout>To learn more about how notification content are added to the template editors, refer to the [Add notification content](/platform/workflow/add-notification-content/channels-template-editors) documentation</Callout>

### Schema configuration

When defining a schema property, the available configuration fields vary depending on the selected property type.

#### General fields (for all types)

* Property name
* Property type
* Required property checkbox
* Default value (Fallback value if none is provided).
* Min length and max length

#### Type-specific configuration

Additional options appear depending on the selected type:

* **String**:
  * **Format**: None, date-time, date, time, duration, email, hostname, ipv4, ipv6, uuid, uri-reference, uri-template, json-pointer, relative-json-pointer, regex
  * **Pattern**: Regex-based validation
* **Enum**: Add choices, which are a list of predefined, allowed values. This restricts the field to only those values.
* **Array**: Select the Array item type, which defines the data type of each array element.
* **Object**: Add nested properties, each with their own type, required status, and validation options.

### Enforce schema validation

Schema validation is enabled per workflow. When enabled, Novu validates incoming payloads against the schema when the workflow is triggered.

This means:

* Missing required properties will cause the request to fail.
* Data types must match exactly. For example, a string cannot be passed where a number is expected.
* Invalid values are rejected before the workflow executes.

Validation occurs at the HTTP trigger level and prevents invalid data being used in the workflow execution.


# How to create a Workflow in Novu (/platform/workflow/create-a-workflow)

Create a workflow and define its identifier, metadata, and initial configuration.

A workflow defines how Novu delivers notifications for a specific event. It contains the steps, templates, and rules that control how messages are sent across channels.

You can create workflows in the Novu dashboard, using the [Novu API](/api-reference/workflows/create-a-workflow) or define them in code using the [Novu Framework](/framework/introduction#create-a-workflow). This guide focuses on creating workflows in the Novu dashboard.

<Callout type="info">Workflows can only be created and managed in the development environment. Once created, workflows can be synced to other environments. To learn more, refer to [Environments](/platform/developer/environments#publishable-assets).</Callout>

## Create a workflow

You can create a Novu workflow in the following ways:

* **Create from scratch**: Build a custom workflow tailored to your exact needs.
* **Create from template**: Start with pre-built workflows for common use cases.

### Create a workflow from scratch

1. Go to the <a href="https://dashboard.novu.co" target="_blank" rel="noopener noreferrer">Novu Dashboard</a>.
2. Navigate to **Workflows**.
3. Click **Create workflow**.\
   ![Create a workflow](/images/workflows/create-a-workflow/create-a-workflow.png)
4. Fill in the [workflow details](#workflow-details):
   * **Name** (Required): The display name shown in the dashboard. You can change this later in the workflow editor.
   * **Identifier** (Required): The `workflowId` is immutable. It must be in a valid slug format (letters, numbers, hyphens, dots and underscores only) and must be unique within one environment.
     <Callout>The `workflowId` is required when triggering a workflow and when using [trigger overrides](/platform/integrations/trigger-overrides). It is also used to conditionally display notifications in the <Method href="/platform/inbox">{`<Inbox />`}</Method>.</Callout>
   * **Tags** (Optional): Organize and categorize workflows. Tags can be added later in the workflow editor.
     <Callout>To learn more about Tags, refer to [workflow tags](/platform/workflow/configure-workflow#tags).</Callout>
   * **Description** (Optional): Document the workflow’s purpose and behavior for your team. Description can be added later in the workflow editor.
     ![Create workflow](/images/workflows/create-a-workflow/create-workflow.png)
5. **Enable translations** (Optional): Support multiple locales for this workflow. This can be enabled after workflow creation in the workflow editor.
   <Callout>To learn more about translations, refer to [Translations](/platform/workflow/advanced-features/translations).</Callout>
6. Click **Create workflow**.

After creating the workflow, you’re redirected to the Workflow Editor, where you can configure the workflow and add steps.

### Create a workflow from a template

Templates are pre-built workflows for common notification scenarios. They include pre-configured steps, sample content, and pre-filled workflow details that you can customize.

To create a workflow from a template:

1. Go to the <a href="https://dashboard.novu.co" target="_blank" rel="noopener noreferrer">Novu Dashboard</a>.
2. Navigate to **Workflows**.
3. From the **Workflows** page, you can access templates in two ways:
   * Click the icon on the **Create workflow** button and select **From template**.
     ![Create from template](/images/workflows/create-a-workflow/create-from-template.png)
   * Click **Explore templates**.
     ![Create from explore](/images/workflows/create-a-workflow/create-from-explore.png)
4. Select a template.
5. Click **Create workflow**.

## Manage workflows

Once created, you can manage workflows from the Workflows page:

### Update a workflow

After creating a workflow, you can modify its configuration at any time from the workflow editor. This allows you to evolve notification logic without creating a new workflow.

Click on any workflow to open the workflow editor, where you can:

* Update name and description (identifier cannot be changed)
* Add or remove the workflow tags.
* Change [workflow status](/platform/workflow/configure-workflow#workflow-status).
* Configure [channel preferences](/platform/workflow/configure-workflow#channel-preferences) and [payload schema](/platform/workflow/configure-workflow#payload-schema).
* Add, remove, or reorder [steps](/platform/workflow/add-and-configure-steps#add-a-step-to-a-workflow).

### Duplicate a workflow

Duplicating a workflow lets you reuse an existing configuration as a starting point for a new workflow. This is useful when workflows share similar logic but differ in trigger identifiers, content, or steps.

1. Find the workflow in **Workflows** page.
2. Click the three-dot menu (•••).
3. Select **Duplicate workflow**.
4. Provide a new name and identifier.
   ![Duplicate a workflow](/images/workflows/create-a-workflow/duplicate-workflow.png)
5. Click **Duplicate Workflow**.
   ![Duplicate workflow](/images/workflows/create-a-workflow/duplicate-a-workflow.png)

### Delete a workflow

<Callout type="warn">Deleting a workflow is permanent and cannot be undone. Any existing triggers referencing the deleted workflow will fail with a `workflow not found` error. Execution history is preserved in the [Novu Activity Feed](/platform/workflow/monitor-and-debug-workflow).</Callout>

1. Find the workflow in **Workflows** page.
2. Click the three-dot menu (•••).
3. Select **Delete**.
4. Confirm deletion.


# Novu Workflows Overview (/platform/workflow)

Learn how to create, configure, and work with notification workflows in Novu.

Novu Workflows orchestrate how notifications move from application events to messages delivered across one or more channels. A workflow combines delivery logic, message content, and execution rules into a single notification pipeline.

Use workflows to control when notifications are sent, who receives them, what content is delivered, and how delivery behaves across channels.

<Callout type="info">If you’re new to workflows, see the [Workflow core concept](/platform/concepts/workflows) for an in-depth overview of what workflows are and how they fit into Novu’s notification system.</Callout>

Novu Workflows help you:

* Ship notifications faster without hardcoding logic in your application.
* Centralize notification logic instead of scattering it across services and codebases.
* Control delivery behavior with conditions, delays, batching, and throttling.
* Personalize notifications at scale using event data, context, and templates.
* Observe and debug notification execution with built-in monitoring and logs.

## Features

* **Multi-channel**: Email, in-app, SMS, push, and chat channels.
* **Action steps**: Delays, digests, throttle notifications, and HTTP requests.
* **Step conditions**: Define conditional logic for each workflow step.
* **Template editors**: Channel-specific editors with variables and LiquidJS logic.
* **Reusable layouts and components**: Email layouts and shared templates.
* **Context and shared data**: Attach metadata and reusable objects across workflows.
* **Translations**: Localize notification content across languages.
* **Observability**: Activity feed and request logs for debugging and auditing.

## Workflow lifecycle

A workflow typically follows this lifecycle:

1. Create a workflow for an application event.
2. Add and configure steps to define channels and execution logic.
3. Author content for each channel.
4. Trigger the workflow from your application using events and payloads.
5. Monitor and iterate using activity logs and delivery metrics.

This section walks through each stage in detail.

## Getting started

Follow these guides to start building your first workflow:

<Cards>
  <Card title="Create a workflow" href="/platform/workflow/create-a-workflow">
    Create a workflow and define its identifier and metadata.
  </Card>

  <Card title="Configure workflows" href="/platform/workflow/configure-workflow">
    Manage workflow metadata, channel preferences, payload schema, and activation state.
  </Card>

  <Card title="Add and configure steps" href="/platform/workflow/add-and-configure-steps">
    Add channel and action steps and define execution logic.
  </Card>

  <Card title="Trigger workflows" href="/platform/workflow/trigger-workflow">
    Trigger workflows from your application and send event data.
  </Card>
</Cards>

## Use cases

* **User lifecycle notifications**: Signup, onboarding, account changes, password resets.
* **Transactional alerts**: Payments, security events, system updates.
* **Product messaging**: Feature announcements, marketing notifications, in-app prompts.
* **Operational workflows**: Internal alerts, DevOps notifications, system monitoring.
* **Multi-tenant messaging**: Tenant-aware notifications using context and topics.


# Monitor and Debug Workflows (/platform/workflow/monitor-and-debug-workflow)

Learn how to monitor workflow executions and debug issues from the Novu Activity Feed.

The Novu Activity Feed tracks the full execution lifecycle after a workflow is triggered. It provides real-time visibility into how workflows run, helping you understand what happened and why.

From the Activity Feed, you can inspect each workflow run and API request to see how each subscriber notification was processed.

![Workflow runs list](/images/workflows/activity-feed/workflow-runs-list.png)

<Callout>Each environment has its own Activity Feed, ensuring execution data is isolated and easy to reason about.</Callout>

## Inspect workflow runs

The Workflow Runs tab shows the details of every workflow triggered to each subscriber. Each run represents a single execution instance and reflects how the workflow behaved for that subscriber.

You can filter workflow runs using parameters such as time period, workflow identifier, and channel. Selecting a workflow run opens the run details view, which gives you access to execution outcomes of each step in the workflow and investigate delivery issues.

![workflow run](/images/workflows/activity-feed/workflow-run.png)

The workflow run details include:

| Field                   | Description                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Workflow identifier** | The unique identifier of the workflow that was executed.                                                           |
| **Transaction ID**      | A unique ID associated with the trigger event. Use this to correlate workflow runs with trigger requests and logs. |
| **Topic key**           | The topic key used to trigger the workflow, if the workflow was triggered to a topic.                              |
| **Subscriber ID**       | The identifier of the subscriber for whom this workflow run was executed.                                          |
| **Triggered at**        | The timestamp indicating when the workflow execution started.                                                      |
| **Status**              | The current state of the workflow run. Possible statuses include Completed, Pending, and Failed.                   |
| **Severity**            | The severity level associated with the workflow execution, if defined.                                             |
| **Critical**            | Indicates whether the workflow was marked as critical.                                                             |
| **Context data**        | Context values passed when triggering the workflow.                                                                |
| **Trigger payload**     | The payload data sent with the trigger event and used to personalize notification content.                         |

Each workflow run also includes execution details that show how Novu processed each step for a single subscriber. The timeline is ordered chronologically and reflects the internal state transitions of each step as the workflow runs.

Execution details are step-specific and vary depending on:

* The type of step
* Whether the step succeeded, was skipped, or failed
* Provider behavior and delivery outcomes

## Inspect trigger requests

The Requests tab in the Activity Feed shows detailed information about every request made to the Event API. Selecting a request opens a detailed view of how Novu processed it, the API response, and execution traces.

![Request tab](/images/workflows/activity-feed/request-tab.png)

You can filter requests using parameters such as time period, transaction ID, statuses or API endpoint. When you open a request, Novu displays details about the API call:

| Field              | Description                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**       | The API endpoint that received the request, for example, `POST /v1/events/trigger` and a unique identifier for the API request. |
| **Received at**    | Timestamp indicating when Novu received the request.                                                                            |
| **Transaction ID** | The transaction associated with the trigger. Use this to correlate the request with workflow runs.                              |
| **Source**         | Indicates where the request originated, either the **Dashboard** or the **API**.                                                |
| **Request body**   | The payload sent in the API call, including the workflow identifier, subscriber or topic targeting, and any additional data.    |
| **Response body**  | Novu’s response to the request, confirming whether it was acknowledged and processed successfully.                              |

Each request also includes API trace events that show how Novu handled the trigger internally.

Common trace entries include:

* Workflow execution started
* Request subscriber processing completed


# How to trigger Workflow in Novu (/platform/workflow/trigger-workflow)

Learn how workflows are triggered in Novu using the Event API, including triggering workflows for individual subscribers, attaching context data, and broadcasting notifications to topics.

Triggering a workflow starts the execution of a notification pipeline in Novu. A workflow is triggered when an event is sent to Novu.

When a workflow is triggered, Novu resolves the target subscribers, evaluates workflow logic, and executes each configured step to deliver notifications across the selected channels. Trigger requests can include payload data, context, or target a topic, allowing you to control both who receives the notification and what data is available during execution.

<Callout>You can test a workflow directly from the workflow editor in the Novu dashboard before triggering it from your application. This allows you to validate step configuration and notification content for a specific subscriber.</Callout>

## Trigger Event API

Workflows in Novu are triggered by sending events to the Event API. An event represents an action in your system, for example, an order created or a comment added and is mapped to a workflow using the workflow’s trigger identifier.

When you trigger an event, you specify:

* The workflow to execute.
* The subscriber (or subscribers) the notification is intended for.
* The payload data used to personalize notification content.

At a minimum, triggering a workflow requires the workflow trigger identifier and a subscriber identifier.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api";

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

    await novu.trigger({
      workflowId: "workflow_identifier",
      to: [{ subscriberId: "string" }],
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST 'https://api.novu.co/v1/events/trigger' /
    -H 'Content-Type: application/json' /
    -H 'Accept: application/json' /
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' /
    -d '{
        "name": "workflow_identifier",
        "to": {
            "subscriberId": "string"
        }
    }'
    ```
  </Tab>
</Tabs>

<Callout>For full request options and response details, see the [Trigger Event API](/api-reference/events/trigger-event) reference.</Callout>

Once the event is received, Novu executes the workflow, evaluates step conditions, resolves variables, and delivers notifications across the configured channels.

From here, you can extend event triggering by attaching context data or targeting multiple subscribers using topics.

## Trigger a workflow with context

You can attach context data when triggering a workflow using the Event API. Context can be referenced from existing contexts created in the Novu dashboard by providing the context type and identifier or defined inline at trigger time. Any context passed with the event is available to all downstream steps and channel templates during workflow execution.

Context data is passed using the `context` object in the trigger request.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api";

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

    await novu.trigger({
      workflowId: "workflow_identifier",
      to: [{ subscriberId: "string" }],
      context: {
        context_type: "context_identifier",
        region: "us-east-1",
        app: "dashboard"
      }
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST "https://api.novu.co/v1/events/trigger" \
      -H "Authorization: ApiKey <NOVU_SECRET_KEY>" \
      -H "Content-Type: application/json" \
      -H 'Accept: application/json' /
      -d '{
        "name": "workflow_identifier",
        "to": [{ "subscriberId": "string" }],
        "context": {
          "context_type": "context_identifier",
          "region": "us-east-1",
          "app": "dashboard"
        }
      }'
    ```
  </Tab>
</Tabs>

<Callout>To learn how contexts work and how to manage them, see the [Context documentation](/platform/workflow/advanced-features/contexts/contexts-in-workflows).</Callout>

## Trigger a workflow to a topic

Once you’ve created topics and added subscribers, you can trigger workflows to those subscribers in bulk. Triggering a workflow to a topic is Novu’s primary mechanism for broadcasting notifications to large audiences with a single API call.

When you trigger a workflow using a topic key, Novu performs a fan-out: it resolves all subscribers in the topic and executes the workflow independently for each subscriber.

<Callout>To learn how to create and manage Topics, see the [Topics API reference](/api-reference/topics/topic-schema).</Callout>

### Trigger to a single topic

The most common use case is sending a notification to all subscribers within a single topic. This is suitable for announcements, incident updates, or targeted broadcasts.

To trigger a workflow to a topic, set the `to` field with `type: "Topic"` and provide the corresponding `topicKey`.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      workflowId: "workflow_identifier",
      to: { type: "Topic", topicKey: "topic_key" },
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": {
            "type": "Topic",
            "topicKey": "topic_key"
        }
    }'
    ```
  </Tab>
</Tabs>

### Trigger to multiple topics

You can broadcast a notification to multiple topics by passing an array to the `to` field. This is useful when your audience spans multiple groups, such as notifying both paying-customers and beta-testers.

Novu automatically de-duplicates subscribers. If a subscriber belongs to more than one of the specified topics, they will receive the notification only once.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      workflowId: "workflow_identifier",
      to: [
        { type: "Topic", topicKey: "topic_key_1" }, 
        { type: "Topic", topicKey: "topic_key_2" }
      ]
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": [
          {
              "type": "Topic",
              "topicKey": "topic_key_1"
          },
          {
              "type": "Topic",
              "topicKey": "topic_key_2"
          }
        ]
    }'
    ```
  </Tab>
</Tabs>

### Exclude a subscriber from a topic trigger

When a workflow is triggered to a topic, all subscribers in that topic are included by default. You can exclude specific subscribers from receiving the notification for that trigger by using the `exclude` field.

This exclusion applies only to the current trigger request and does not modify the topic membership.

<Tabs items={["Node.js", "cURL"]}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api"

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    await novu.trigger({
      workflowId: "workflow_identifier",
      to: [{ type: "Topic", topicKey: "topic_key", exclude: ["subscriber-id"] }],
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
        "name": "workflow_identifier",
        "to": [
          {
              "type": "Topic",
              "topicKey": "topic_key",
              "exclude": ["subscriber-id"]
          }
        ]
    }
    ```
  </Tab>
</Tabs>


# Novu Framework TypeScript Chat Step (/framework/typescript/steps/chat)

Learn how to use the chat step to send messages to chat platforms like Slack, Discord, and Microsoft Teams

The `chat` step allows you to send messages to various chat platforms like Slack, Discord, and Microsoft Teams.

## Example Usage

```tsx
await step.chat('chat', async () => {
  return {
    body: 'A new post has been created',
  };
});
```

## Chat Step Output

| Property | Type   | Required | Description                                |
| -------- | ------ | -------- | ------------------------------------------ |
| body     | string | Yes      | The message to be sent to the chat channel |

## Chat Step Result

The `chat` step does not return any result object.


# Novu Framework TypeScript Custom Action Step (/framework/typescript/steps/custom)

Learn how to use the custom step to execute arbitrary code in your workflow

The `custom` step allows you to execute arbitrary code within your workflow and persist the results for use in subsequent steps. This is useful for integrating with external services, performing complex calculations, or implementing custom business logic.

## Example Usage

```tsx
const result = await step.custom(
  'fetch-user-data',
  async () => {
    const response = await fetch('https://api.example.com/users/123');
    const userData = await response.json();

    return {
      name: userData.name,
      email: userData.email,
      preferences: userData.preferences,
    };
  },
  {
    outputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string' },
        preferences: { type: 'object' },
      },
      required: ['name', 'email'],
    },
  }
);

// Use the result in a subsequent step
await step.email('welcome-email', async () => {
  return {
    subject: `Welcome ${result.name}!`,
    body: `We'll send updates to ${result.email}`,
  };
});
```

## Custom Step Options

| Property     | Type       | Required | Description                                             |
| ------------ | ---------- | -------- | ------------------------------------------------------- |
| outputSchema | JSONSchema | No       | JSON Schema definition for validating the step's output |

<Callout type="info">
  The output schema is used to validate the step's return value and provide TypeScript type
  inference. If not provided, the return type will be `unknown`.
</Callout>

## Custom Step Result

The custom step returns whatever value your code returns, validated against the outputSchema if provided. This result can be used in subsequent steps within the same workflow.


# Delay Step Reference (/framework/typescript/steps/delay)

Learn how to use the delay step to pause workflow execution for a specified duration

The `delay` step allows you to pause the execution of your workflow for a specified duration. This is useful for implementing features like follow-up notifications, reminder sequences, or cooldown periods.

## Example Usage

```tsx
// Wait for 24 hours
await step.delay('reminder-delay', async () => {
  return {
    amount: 24,
    unit: 'hours',
  };
});

// Send a follow-up email
await step.email('follow-up', async () => {
  return {
    subject: 'How are you liking our product?',
    body: 'We noticed you signed up yesterday. How has your experience been so far?',
  };
});
```

## Delay Step Output

| Property | Type                                                               | Required | Description                          |
| -------- | ------------------------------------------------------------------ | -------- | ------------------------------------ |
| amount   | number                                                             | Yes      | The number of time units to delay    |
| unit     | 'seconds' \| 'minutes' \| 'hours' \| 'days' \| 'weeks' \| 'months' | Yes      | The time unit for the delay duration |

## Delay Step Result

| Property | Type   | Description                              |
| -------- | ------ | ---------------------------------------- |
| duration | number | The total delay duration in milliseconds |

<Callout type="info">
  The delay step can be skipped conditionally using the `skip` option, allowing you to implement
  dynamic delay logic based on your workflow's needs.
</Callout>

## Conditional Delay Example

```tsx
await step.delay(
  'premium-user-delay',
  async () => {
    return {
      amount: 24,
      unit: 'hours',
    };
  },
  {
    // Skip the delay for premium users
    skip: async () => user.isPremium,
  }
);
```


# Digest Step Reference (/framework/typescript/steps/digest)

Learn how to use the digest step to aggregate multiple events into a single notification

The `digest` step allows you to collect multiple events over a specified time period and combine them into a single notification. This is useful for reducing notification fatigue and providing better context to your users.

## Example Usage

```tsx
const { events } = await step.digest('daily-summary', async () => {
  return {
    amount: 1,
    unit: 'days',
  };
});

await step.email('digest-email', async () => {
  return {
    subject: `Daily Summary (${events.length} updates)`,
    body: `You have ${events.length} new updates today`,
  };
});
```

## Digest Step Output

| Property  | Type                                                               | Required | Description                                    |
| --------- | ------------------------------------------------------------------ | -------- | ---------------------------------------------- |
| amount    | number                                                             | Yes      | The number of time units to collect events for |
| unit      | 'seconds' \| 'minutes' \| 'hours' \| 'days' \| 'weeks' \| 'months' | Yes      | The time unit for the digest period            |
| cron      | string                                                             | No       | The cron expression to use for the digest      |
| digestKey | string                                                             | No       | The key to use for digesting events            |

<Callout type="info">
  Use either cron or amount-unit. Using both will result in an error.
</Callout>

## Digest Step Result

| Property | Type           | Description                                        |
| -------- | -------------- | -------------------------------------------------- |
| events   | DigestEvent\[] | Array of events collected during the digest period |

## DigestEvent Type

| Property | Type   | Description                                 |
| -------- | ------ | ------------------------------------------- |
| id       | string | The unique identifier of the digested event |
| time     | Date   | The timestamp when the event was triggered  |
| payload  | object | The original payload passed to the event    |

<Callout type="info">
  The digest step result can only be used in subsequent steps within the same workflow. You cannot
  access digest information in step controls.
</Callout>

## Using Digest Events

You can use the digested events to create rich, aggregated notifications. Here's an example:

```tsx
import { ActivityDigestEmail } from './ActivityDigestEmail';

const { events } = await step.digest('activity-digest', async () => {
  return {
    amount: 1,
    unit: 'hours',
  };
});

await step.email('digest-notification', async () => {
  const activities = events.map((event) => ({
    type: event.payload.type,
    user: event.payload.userName,
    action: event.payload.action,
  }));

  return {
    subject: `Activity Summary (${events.length} updates)`,
    body: render(<ActivityDigestEmail activities={activities} />),
  };
});
```

## Cron based digest

You can use cron based digest to digest events based on a cron expression.

```tsx
const digestedEvents = await step.digest('cron-digest', async () => {
  return {
    cron: '0 0 * * *', // every day at midnight
  };
});
```

## Custom Digest Key

You can use a custom digest key to digest events based on a custom key. By default, events are digested based on the `subscriberId`. With a custom digest key, events are digested based on the combination of the `subscriberId` and the `digestKey` value.

```tsx
export const customDigestKey = workflow(
  "custom-digest-key",
  async ({ step, payload }) => {
    const { events } = await step.digest("digest-step", async () => {
      return {
        unit: "hours",
        amount: 1,
        digestKey: payload.ticket_id,
      };
    });

    console.log("events ==>", events);

    // use above events to send email / in-app notification
  },
  {
    payloadSchema: z.object({
      ticket_id: z.string(),
    }),
  }
);
```

<Callout type="warn">
  Changes to the workflow content after triggering will not affect existing digested events. The
  content is determined at the time of event digestion.
</Callout>


# Novu Framework TypeScript Email Step (/framework/typescript/steps/email)

Learn how to use the email step to send email notifications

The `email` step allows you to send email notifications to your users. This step supports HTML content and can be used with React Email for building beautiful email templates.

## Example Usage

```tsx
await step.email('welcome-email', async () => {
  return {
    subject: 'Welcome to Our Platform',
    body: "Hello and welcome! We're excited to have you on board.",
  };
});
```

## Email Step Output

| Property    | Type          | Required | Description                                         |
| ----------- | ------------- | -------- | --------------------------------------------------- |
| subject     | string        | Yes      | The subject line of the email                       |
| body        | string        | Yes      | The content of the email. Can be plain text or HTML |
| attachments | Attachment\[] | No       | Array of files to attach to the email               |
| from        | string        | No       | Override the default from address                   |
| replyTo     | string        | No       | Set a reply-to address for the email                |

## Email Step Result

The `email` step does not return any result object.


# Novu Framework TypeScript In-App Step (/framework/typescript/steps/inApp)

Learn how to use the In-App step to send notifications to your web or mobile app's inbox

The `inApp` step allows you to send a message to your user's `<Inbox />` for your web or a mobile app.

## Example Usage

```tsx
await step.inApp('inbox', async () => {
  return {
    subject: 'Welcome to Acme!',
    body: 'We are excited to have you on board.',
    avatar: 'https://acme.com/avatar.png',
    redirect: {
      url: 'https://acme.com/welcome',
      target: '_blank',
    },
    primaryAction: {
      label: 'Get Started',
      redirect: {
        url: 'https://acme.com/get-started',
        target: '_self',
      },
    },
    secondaryAction: {
      label: 'Learn More',
      redirect: {
        url: 'https://acme.com/learn-more',
        target: '_self',
      },
    },
    data: {
      customData: 'customValue',
      text: payload.text,
    },
  };
});
```

## Return Value

```tsx
const { seen, read, lastSeenDate, lastReadDate } = await step.inApp('inbox', resolver);
```

## In-App Step Output

### body

* **Type**: `string`
* **Required**: Yes
* **Description**: The body of the inbox notification. The main content of the notification.

### subject

* **Type**: `string`
* **Required**: No
* **Description**: The subject of the inbox notification. This property communicates the subject of the notification to the user.

### avatar

* **Type**: `string`
* **Required**: No
* **Description**: The avatar shown in the inbox notification. When specified, overrides the avatar of the actor initiating the notification.

### redirect

* **Type**: `object`
* **Required**: No
* **Description**: The redirect object is used to define the URL to visit when interacting with the notification. This property can be omitted in place of an `onNotificationClick` [handler](/platform/inbox/advanced-customization/notification-click-behavior#handle-notification-click-events) implemented in the `<Inbox />` component.
* **Properties**:
  * `url` (string, required): The URL to visit when clicking on the notification.
  * `target` (string): The target attribute specifies where the new window or tab will be opened. Defaults to `_blank`. Supported values: `_self, _blank, _parent, _top, _unfencedTop`.

### primaryAction

* **Type**: `object`
* **Required**: No
* **Description**: Define a primary action to be shown in the inbox notification. The primary action will appear with an accent color.
* **Properties**:
  * `label` (string, required): The label of the action.
  * `redirect` (object):
    * `url` (string, required): The URL to visit when clicking on the notification action button.
    * `target` (string): The target attribute specifies where the new window or tab will be opened. Defaults to `_blank`. Supported values: `_self, _blank, _parent, _top, _unfencedTop`.

### secondaryAction

* **Type**: `object`
* **Required**: No
* **Description**: Define a secondary action to be shown in the inbox notification. The secondary action will appear with a muted color.
* **Properties**:
  * `label` (string, required): The label of the action.
  * `redirect` (object):
    * `url` (string, required): The URL to visit when clicking on the notification action button.
    * `target` (string): The target attribute specifies where the new window or tab will be opened. Defaults to `_blank`. Supported values: `_self, _blank, _parent, _top, _unfencedTop`.

### data

* **Type**: `object`
* **Required**: No
* **Description**: Custom data to be sent with the notification. This data can be used to [customize the notification item rendered](/platform/inbox/configuration/styling#render-notification-component) in the `<Inbox />`.

## In-App Step Result

### seen

* **Type**: `boolean`
* **Required**: Yes
* **Description**: A flag indicating if the notification has been seen. This property is useful when conditionally delivering notifications in subsequent steps via the `skip` function. A notification is marked as seen when the user views the notification.

### read

* **Type**: `boolean`
* **Required**: Yes
* **Description**: A flag indicating if the notification has been read. A notification is marked as read when the user confirms the notification.

### lastSeenDate

* **Type**: `date | null`
* **Required**: Yes
* **Description**: The date the notification was last seen. This corresponds to the date the `seen` property was set to `true`, or `null` if the notification has not been seen.

### lastReadDate

* **Type**: `date | null`
* **Required**: Yes
* **Description**: The date the notification was last read. This corresponds to the date the `read` property was set to `true`, or `null` if the notification has not been read.


# Step Interface (/framework/typescript/steps)

Learn about the Novu Framework step interface and its configuration options

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## Examples

<Tabs items={['Control Schema', 'Skip', 'Disable Output Sanitization', 'Provider Overrides', 'Provider Passthrough']}>
  <Tab value="Control Schema">
    ```tsx
    await step.email('stepId', resolver, {
      controlSchema: z.object({
        subject: z.string(),
        components: z.array(z.object({
          type: z.enum(['text', 'button']),
          content: z.string(),
        })),
      }),
    });
    ```
  </Tab>

  <Tab value="Skip">
    ```tsx
    await step.email('skipped-step', async () => ({
      subject: 'Hello, world!',
      body: 'My email message',
    }), {
      skip: async (controls) => true,
    });
    ```
  </Tab>

  <Tab value="Disable Output Sanitization">
    ```tsx
    await step.inApp(
      'without-sanitization',
      async () => ({
        body: 'My in-app message',
        data: {
          link: '/pipeline/123?active=true&env=prod',
        },
      }),
      {
        // Prevent the `&` character in `data.link` from
        // being converted to `&amp;`
        disableOutputSanitization: true,
      }
    );
    ```
  </Tab>

  <Tab value="Provider Overrides">
    ```tsx
    await step.email('provider-override', resolver, {
      providers: {
        slack: ({ controls, outputs }) => {
          return {
            text: 'A new post has been created',
            blocks: [{
              type: 'section',
              text: {
                type: 'mrkdwn',
                text: 'A new post has been created',
              },
            }],
          };
        }
      }
    });
    ```
  </Tab>

  <Tab value="Provider Passthrough">
    ```tsx
    await step.email('provider-passthrough', resolver, {
      providers: {
        sendgrid: ({ controls, outputs }) => {
          return {
            _passthrough: {
              body: {
                ip_pool_name: 'my-ip-pool',
              },
              headers: {
                'Authorization': 'Bearer my-api-key',
              },
              query: {
                'queryParam': 'queryValue',
              },
            }
          };
        }
      }
    });
    ```
  </Tab>
</Tabs>

## Channel Steps Interface

All channels follow the same shared interface:

### stepId

* **Type**: `string`
* **Required**: Yes
* **Description**: This is the unique identifier for the step in the workflow context. It is used to reference and display the step in the dashboard interface.

### resolver

* **Type**: `Promise`
* **Required**: Yes
* **Description**: This is an async function that returns the content of the step which called `Outputs`. Each channel has its own output schema.

### options

* **Type**: `StepOptions`
* **Description**: Additional step configuration.

## Options Object

This is an optional configuration object that defines: [Controls Schema](/framework/controls), [Provider Overrides](#provider-overrides), skip and other configurations.

### skip

* **Type**: `(controls: InferProperties<controlSchema>) => boolean | Promise<boolean>`
* **Description**: A function that returns a boolean value to skip the step. This is helpful when you want to use previous step results or other custom logic to skip the step from executing.

### controlSchema

* **Type**: `JsonSchema | ZodSchema`
* **Description**: This defined the UI Controls exposed in the dashboard for the step. They can be nested and of any JSON Schema supported structure.

### providers

* **Type**: `ProvidersOverride`
* **Description**: This object used to access and override the underlying deliver providers SDKs. This is useful when you want to customize the content of the notification with properties that are unique to the provider.

### disableOutputSanitization

* **Type**: `boolean`
* **Default**: `false`
* **Description**: A flag to disable output sanitization for the step. This is useful when you want to return unescaped HTML content to the provider or the `<Inbox/>` component.

## Providers Overrides Object

This object used to access and override the underlying deliver providers SDKs. This is useful when you want to customize the content of the notification with properties that are unique to the provider.

An example of this is the `slack` provider, which allows you to customize the content of the notification with Slack `blocks` to create a rich notification experience.

```typescript
type ProvidersOverride = {
  [key: ProviderEnum]: ProviderCallback;
};

type ProviderCallback = (
  params: ProviderOverridesParams
) => ProviderOverrideOutput | Promise<ProviderOverrideOutput>;

type ProviderOverridesParams = {
  controls: StepControls;
  output: StepOutput;
};

interface ProviderOverrideOutput {
  // A map of the properties used by the Provider.
  // These properties are strongly typed and validated
  // against the underlying provider SDK.
  [key in KnownProviderKey]: KnownProviderValue;
  // The passthrough object is used to pass through
  // the original request to the provider.
  // These properties are not validated.
  _passthrough?: {
    body: Record<string, unknown>;
    headers: Record<string, unknown>;
    query: Record<string, unknown>;
  };
}
```

The `_passthrough` object and the known provider values are deeply merged prior to sending the request to the provider, with the `_passthrough` object taking precedence.


# Novu Framework TypeScript Push Step (/framework/typescript/steps/push)

Learn how to use the push step to send notifications to mobile and web apps

The `push` step allows you to send notifications to mobile and web applications through various push notification providers.

## Example Usage

```tsx
await step.push('new-message', async () => {
  return {
    title: 'New Message',
    body: 'You have received a new message from John',
    data: {
      messageId: '123',
      senderId: '456',
    },
  };
});
```

## Push Step Output

| Property | Type   | Required | Description                                                  |
| -------- | ------ | -------- | ------------------------------------------------------------ |
| title    | string | Yes      | The notification title that appears in the push notification |
| body     | string | Yes      | The main content of the push notification                    |
| data     | object | No       | Additional data to be sent with the notification             |
| image    | string | No       | URL of an image to display in the notification               |
| icon     | string | No       | URL of an icon to display in the notification                |

## Push Step Result

The `push` step does not return any result object.

## Provider Configuration

To send push notifications, you need to configure the appropriate push provider credentials. See our [Push Provider Documentation](/platform/integrations/push) for detailed setup instructions.


# Novu Framework TypeScript SMS Step (/framework/typescript/steps/sms)

Learn how to use the SMS step to send text messages to users

The `sms` step allows you to send text messages to your users' mobile devices through various SMS providers.

## Example Usage

```tsx
await step.sms('verification', async () => {
  return {
    body: 'Your verification code is: 123456',
  };
});
```

## SMS Step Output

| Property | Type   | Required | Description                         |
| -------- | ------ | -------- | ----------------------------------- |
| body     | string | Yes      | The text message content to be sent |

## SMS Step Result

The `sms` step does not return any result object.


# Webhooks event types (/platform/developer/webhooks/event-types)

Learn more about the types of events that Novu sends webhook events for.

Novu supports the following webhook event types:

* **Message events**: Events about message delivery status changes.
* **Preference event**: Event about subscriber preference changes.
* **Workflow events**: Events about workflow creation, updates, and deletions.

Each event includes detailed information about the affected resource and the changes that occurred.

## Message events

* `message.archived`: This webhook is triggered when a subscriber archives a message. The payload contains the details of the event.
* `message.delivered`: This webhook is triggered when a message delivery provider acknowledged the message delivery to the end receiving client. The payload contains the details of the event.
* `message.failed`: This webhook is triggered when Novu tries to send the message to the delivery provider and it got failed. The payload contains the details of the event.
* `message.read`: This webhook is triggered when a message has been read by the subscriber. The payload contains the details of the event.
* `message.seen`: This webhook is triggered when a subscriber opens a message. The payload contains the details of the event.
* `message.sent`: This webhook is triggered when Novu sends the message to the delivery provider. The payload contains the details of the event.
* `message.snoozed`: This webhook is triggered when a message is snoozed by the subscriber. The payload contains the details of the event.
* `message.unarchived`: This webhook is triggered when an archived message is unarchived. The payload contains the details of the event.
* `message.unread`: This webhook is triggered when a message is unread or marked as unread by the subscriber. The payload contains the details of the event.
* `message.unsnoozed`: This webhook is triggered when a message is unsnoozed by a subscriber. The payload contains the details of the event.

## Preference event

* `preference.updated`: This webhook is triggered when a subscriber preference is updated. The payload contains the details of the event.

## Workflow events

* `workflow.created`: This webhook is triggered when a workflow is created. The payload contains the details of the event.
* `workflow.deleted`: This webhook is triggered when a workflow is deleted. The payload contains the details of the event.
* `workflow.published`: This webhook is triggered when a `workflow` event occurs, that is when a workflow is synced from dev to prod environment. The payload contains the details of the event.
* `workflow.updated`: This webhook is triggered when a workflow is updated. The payload contains the details of the event.


# Novu Webhooks Overview (/platform/developer/webhooks)

Configure webhook endpoints to receive real-time event notifications from Novu for workflow updates and message delivery.

Webhooks makes it possible for your external systems to receive real-time notifications when specific events occur within your Novu account. They are POST requests sent to a pre-determined endpoint that you configure.

<Callout>This webhook feature is only have in the <a href="https://novu.co/pricing" target="_blank" rel="noopener noreferrer">Team and Enterprise plans</a>.</Callout>

## How it works

You provide Novu with a URL (endpoint), and we send a JSON payload to that URL whenever an event happens, such as a workflow update or message delivery.

For example, to receive updates at `https://api.yourservice.com/novu/webhook/`, you must configure this as your endpoint. Your server then acknowledges receipt by returning a 2xx status code (200-299).

## How to add a webhook endpoint

To start listening to messages, you must register your endpoint in the Novu dashboard.

1. Go to the **[Webhooks](https://dashboard.novu.co/webhooks)** page in the Novu dashboard.
2. Select the **Endpoints** tab.
3. Click **Add Endpoint**.
4. Select a webhook integration from the list.
   ![Webhook integrations list](/images/developer-tools/webhook-integrations.png)
5. In the **Endpoint URL** field, enter the HTTPS URL where you want to receive the payload. You can use tools like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to generate a temporary URL for testing.
6. In the **Description** field, enter a description to identify this webhook.
7. Next, select the specific event types you want this endpoint to subscribe to.
   ![Add webhook](/images/developer-tools/add-webhook.png)
8. (Optional) Configure [advanced settings](/platform/developer/webhooks#advanced-configuration) for rate limits, transformations, and custom headers.
9. Click **Create**.

<Callout>For frameworks that enable CSRF protection disable them and also verify the signature and timestamp when processing them.</Callout>

### Advanced configuration

When adding or editing an endpoint, you can utilize the advanced configuration option to fine-tune how Novu communicates with your server.

* **Rate limiting (Throttling)**: You can configure rate limits to effectively throttle the webhooks, ensuring Novu only sends a specific number of requests per second.
* **Custom headers**: Custom headers can only be configured after the endpoint has been created.
* **Transformations**: Novu uses Svix transformations feature, it let's you modify a webhook's payload and redirect it to a different URL. <a href="https://docs.svix.com/transformations" target="_blank" rel="noopener noreferrer">Visit Svix documentation</a> to learn more.

### Testing endpoints

After you've added an endpoint, you can test it to be sure it's working. To do this:

1. Click on the endpoint you want to test.
2. Click the **Testing** tab.
3. Select an event type you want to test with.
   ![Testing endpoints](/images/developer-tools/testing-endpoints.png)
4. Click **Send Example**.

After sending an example event, you can view the message payload, all of the message attempts, and whether it succeeded or failed.

![After testing](/images/developer-tools/after-testing.png)

## Verifying your webhooks signatures

You must verify that the requests hitting your endpoint are actually from Novu and not a malicious actor.

Novu uses <a href="https://www.svix.com/" target="_blank" rel="noopener noreferrer">Svix</a> to sign webhooks. Svix offers a set of libraries for verifying signatures.

```tsx
import { Webhook } from "svix";
 
const secret = "YOUR_WEBHOOK_SECRET_KEY";
 
// These were all sent from the server
const headers = {
  "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "webhook-timestamp": "1614265330",
  "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';
 
const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const verifiedPayload = wh.verify(payload, headers);
```

Check out the <a href="https://docs.svix.com/receiving/verifying-payloads/how" target="_blank" rel="noopener noreferrer">Svix webhook verification documentation</a>, for more instructions and examples of how to verify signatures.

## Recovery and resending failed messages

When your service experiences downtime or your endpoint is misconfigured, you can replay failed messages once you are back online.

### Delivery attempts

When an event cannot be delivered, Novu retries using exponential backoff. Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

You can find all the historical delivery attempts for each webhook endpoint in the webhook activity tab of that endpoint.
![Delivery attempts](/images/developer-tools/delivery-attempts.png)

When your endpoint is unavailable, Novu keeps retrying according to the retry schedule. When all attempts fail for 5 days consecutively, the endpoint will be disabled and you have to manually re-enable it.

### Resend a single failed event

To resend an individual event:

1. Click the **Logs** tab and find the failed message you want to replay.
2. Under the **Webhook Attempts** section, Click the (**...**) icon
   ![Resend single event](/images/developer-tools/resend-event.png)
3. Click **Resend** to attempt delivery again.

### Recover all failed messages

This operation causes all failed messages to a particular endpoint to be resent. To do this:

1. Click on the endpoint from the **Endpoints** tab.
2. Click the (**...**) icon.
   ![Recover all failed messages](/images/developer-tools/recover.png)
3. Click **Recover failed messages**.
4. On the menu, select a time window to recover all failed messages from that period. For example, you can recover all fialed messages in the last 8 hours.
   ![Recover all failed messages menu](/images/developer-tools/recover-menu.png)

### Replay missing messages

This operation causes all messages that were never attempted for a particular endpoint to be resent. To do this:

1. Click on the endpoint from the **Endpoints** tab.
2. Click the (**...**) icon.
3. Click **Replay missing messages**.
4. On the menu, select a time window to replay all failed messages from that period. For example, you can replay all missing messages from the last 8 hours that were never attempted.
   ![Recover all failed messages menu](/images/developer-tools/replay-menu.png)

## Managing webhooks endpoints

### Enable or disable an endpoint

Endpoints can be manually enabled or disabled at any time. Novu also automatically disables an endpoint when all deliveries fail for 5 consecutive days.

To enable or disable an endpoint:

1. Go to the webhook page of the Novu dashboard.
2. Find the endpoint you want to enable or disable from the list.
3. Click the (...) icon.
   ![Disable or enable endpoints](/images/developer-tools/disable-endpoint.png)
4. Click **Disable Endpoint** or **Enable Endpoint**.

### Delete an endpoint

Deleting an endpoint immediately stops all future delivery attempts and removes the configuration from your account. This action is permanent.

To delete an endpoint:

1. Go to the webhook page of the Novu dashboard.
2. Find the endpoint you want to enable or disable from the list.
3. Click the (**...**) icon.
4. Click **Delete**.

## Troubleshooting

There are some common reasons why your webhook endpoint is failing:

### Not using the raw payload body

Using different implementations to convert JSON payloads into strings can produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature.

Verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification.

### Sending the wrong response codes

When Novu receives a response with a 2xx status code, it is interpreted as a successful delivery even regardless of the response payload. Make sure to use the right response status codes so Novu knows when messages are supposed to succeed or fail.

### Responses timing out

Novu considers all messages that fails to send a response within 15 seconds as a failed message.

For cases where your endpoint is processing complicated workflows, you can have your endpoint receive the message and add it to a queue to be processed asynchronously to avoid getting timed out.

## Frequently asked questions

### How do I secure my webhook endpoint?

To secure your webhook endpoint, you should:

1. Verify the webhook signature using the Svix library
2. Use HTTPS for your endpoint URL
3. Implement rate limiting to prevent abuse
4. Keep your webhook secret secure and rotate it periodically

### How can I test webhooks locally?

To test webhooks locally, you can use a service like ngrok or localtunnel to expose your local server to the internet. Alternatively, you can use webhook testing services like Webhook.site or RequestBin to inspect webhook payloads.


# Novu Webhooks Guide (/platform/developer/webhooks/webhooks)

Learn how Novu webhooks work, including event types, payload schemas, signature verification, and endpoint configuration.

## The Intro

Webhooks are how services notify each other of events.

At their core they are just a POST request to a pre-determined endpoint.
The endpoint can be whatever you want, and you can just add them from the UI.
You normally use one endpoint per service, and that endpoint listens to all of the event types.

For example, if you receive webhooks from Novu, you can structure your URL like: `https://www.example.com/novu/webhook/`.

The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s).

It's also important to disable CSRF protection for this endpoint if the framework you use enables them by default.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them.

You can learn more about it in the signature verification section.

## Events and event types

The core value of webhooks is to notify users when events happen, so it's extremely important to understand what events are available and their payload schemas.

Novu webhooks allow you to receive notifications when specific events occur in your Novu account. These events include workflow updates, subscriber changes, and message delivery status updates.

### Supported event types

Novu supports the following webhook event types:

* **Workflow Events**: Events about workflow creation, updates, and deletions,
* **Message Events**: Events about message delivery status changes
* **Preference Events**: Events about subscriber preference changes

Each event includes detailed information about the affected resource and the changes that occurred.

#### Workflow Events

* **workflow\.created**: Triggered when a workflow is created
* **workflow\.updated**: Triggered when a workflow is updated
* **workflow\.deleted**: Triggered when a workflow is deleted
* **workflow\.published**: Triggered when a workflow is synced from dev to prod environment

#### Message Events

* **messages.archived**: Triggered when a message is archived.
* **messages.unarchived**: Triggered when a message is unarchived.
* **messages.read**: Triggered when a message is read.
* **messages.unread**: Triggered when a message is unread.
* **messages.seen**: Triggered when a message is seen.
* **messages.snoozed**: Triggered when a message is snoozed.
* **messages.unsnoozed**: Triggered when a message is unsnoozed.
* **messages.sent**: Triggered when Novu sends the message to the delivery provider.
* **messages.delivered**: Triggered when a message delivery provider acknowledged the message delivery to the end receiving client.
* **messages.failed**: Triggered when Novu tried to send the message to the delivery provider and it got failed.

#### Preference Events

* **preference.updated**: Triggered when subscriber preference is updated.

## How to add an endpoint

To start listening to messages, you will need to configure your endpoints.

1. Go to the [Webhooks](https://dashboard.novu.co/webhooks) page in the Novu dashboard.
2. Click **Add Endpoint**.
3. Enter the URL of your endpoint.
4. Add description for this webhook endpoint.
5. Select the event types you want to listen to.
6. Optional: add advanced configuration for your endpoint.
7. Click **Create**.

If your endpoint isn't quite ready to start receiving events, you can use a service like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to have a unique URL generated for you.

## How to test endpoints

Once you've added an endpoint, you'll want to make sure it's working.

The "Testing" tab lets you send test events to your endpoint.

After sending an example event, you can view the message payload, all of the message attempts, and whether it succeeded or failed.

## Verifying signatures

Webhook signatures let you verify that webhook messages are actually sent by Novu and not a malicious actor.

For a more detailed explanation, check out this article on [why you should verify webhooks](https://docs.svix.com/receiving/verifying-payloads/why).

Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple. Here is an example using Javascript:

```javascript
import { Webhook } from "svix";

const secret = "YOUR_WEBHOOK_SECRET_KEY";

// These were all sent from the server
const headers = {
  "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "webhook-timestamp": "1614265330",
  "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const verifiedPayload = wh.verify(payload, headers);
```

For more instructions and examples of how to verify signatures, check out the [webhook verification documentation](https://docs.svix.com/receiving/verifying-payloads/how).

## Retry schedule

### Retries

We attempt to deliver each webhook message based on a retry schedule with exponential backoff.

#### The schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)

If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

### Manual retries

You can also use the application portal to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.

## Troubleshooting & Failure Recovery

### Common reasons why your webhook endpoint is failing

There are some common reasons why your webhook endpoint is failing:

* **Not using the raw payload body**

This is the most common issue. When generating the signed content, we use the raw string body of the message payload.

If you convert JSON payloads into strings using methods like stringify, different implementations may produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature. It's crucial to verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification.

* **Missing the secret key**

From time to time we see people simply using the wrong secret key. Remember that keys are unique to endpoints.

* **Sending the wrong response codes**

When we receive a response with a 2xx status code, we interpret that as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so we know when messages are supposed to succeed vs fail.

* **Responses timing out**

We will consider any message that fails to send a response within 15 seconds a failed message. If your endpoint is also processing complicated workflows, it may timeout and result in failed messages.

We suggest having your endpoint simply receive the message and add it to a queue to be processed asynchronously so you can respond promptly and avoid getting timed out.

### Re-enable a disabled endpoint

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. To re-enable a disabled endpoint, go to the webhook dashboard, find the endpoint from the list and select "Enable Endpoint".

### Recovering/Resending failed messages

If your service has downtime or if your endpoint was misconfigured, you probably want to recover any messages that failed during the downtime.

If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts.

From there, click "resend" to have the same message send to your endpoint again.

If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click "Options > Recover Failed Messages".

From there, you can choose a time window to recover from.

For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page.

From there, you can click "Replay..." and choose to "Replay all failed messages since this time."

## FAQs

### How do I secure my webhook endpoint?

To secure your webhook endpoint, you should:

1. Verify the webhook signature using the Svix library
2. Use HTTPS for your endpoint URL
3. Implement rate limiting to prevent abuse
4. Keep your webhook secret secure and rotate it periodically

### What happens if my endpoint is unavailable?

If your endpoint is unavailable, Novu will retry sending the webhook according to the retry schedule. If all attempts fail for 5 days, the endpoint will be disabled and you'll need to manually re-enable it.

### Can I filter webhooks by event type?

Yes, when configuring your webhook endpoint, you can select specific event types to receive. This allows you to filter out events that aren't relevant to your use case.

### How can I test webhooks locally?

To test webhooks locally, you can use a service like ngrok or localtunnel to expose your local server to the internet. Alternatively, you can use webhook testing services like Webhook.site or RequestBin to inspect webhook payloads.


# Conditionally display notifications (/platform/inbox/advanced-customization/conditional-display)

Learn how to apply conditional display logic to notifications.

The Inbox component supports conditional display of notifications using the `renderNotification` prop. This function receives the full `notification` object and returns a custom React element.

You can use worklow data such as tags, identifiers, data object or notfication severity to control how notifications are desplayed in the notification UI. This lets you create create dynamic, personalized notification UI for your subscribers.

## Display notifications based on workflow tags

You can conditionally display customized notification based on [workflow tags](/platform/concepts/workflows#workflow-tags). These tags are defined in your workflow and are accessible via `notification.tags` property.

```tsx
import { Inbox } from '@novu/react';

export default function CustomInbox() {
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => {
        // filter based on tags
        if (notification.tags?.includes('custom')) {
          return (
            <div>
              <h3>Custom Notification Subject</h3>
              <p>Custom Notification Body</p>
            </div>
          );
        }
        // default
        return (
          <div>
            <h3>{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        );
      }}
    />
  );
}
```

## Display notifications based on workflow identifier or name

Each workflow has a [name and a unique identifier](/platform/concepts/workflows#workflow-identifier), accessible through `notification.workflow.name` and `notification.workflow.identifier`, respectively. Either property can be used to conditionally render notifications.

```tsx
import { Inbox } from '@novu/react';
export default function CutomInbox() {
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => {
        // filter based on workflow identifier
        if (notification.workflow?.identifier === 'demo') {
          return (
            <div style={{ backgroundColor: 'blue' }}>
              <h3>{notification.subject}</h3>
              <p>{notification.body}</p>
            </div>
          );
        }
        // filter based on workflow name
        if (notification.workflow?.name === 'Custom') {
          return (
            <div style={{ backgroundColor: 'blue' }}>
              <h3>{notification.subject}</h3>
              <p>{notification.body}</p>
            </div>
          );
        }
        // default
        return (
          <div>
            <h3>{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        );
      }}
    />
  );
}
```

## Display notifications based on data object

You can also use values from the notification [data object](/platform/inbox/configuration/data-object) to render notifications conditionally. These values are accessible via `notification.data` and typically contain custom payload fields.

```tsx
import { Inbox } from '@novu/react';
export default function CutomInbox() {
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => {
       // filter based on data object key
       if (notification.data?.priority) {
        return (
          <div style={{ backgroundColor: 'red' }}>
            <h3>{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        );
      }
        // default
        return (
          <div>
            <h3>{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        );
      }}
    />
  );
}
```

## Display notifications based on notfication severity

You can access the severity field on each notification object. This enables conditional rendering in custom UIs.

```tsx
import { Inbox, SeverityLevelEnum } from '@novu/react';
export default function CutomInbox() {
 
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => {
        // render based on severity value
        if (notification.severity === SeverityLevelEnum.HIGH) {
          return (
            <div style={{ backgroundColor: 'red' }}>
              <h3>{notification.subject}</h3>
              <p>{notification.body}</p>
            </div>
          );
        }
        
        return (
           <div>
             <h3>{notification.subject}</h3>
             <p>{notification.body}</p>
           </div>
        );
      }}
    />
  );
}
```


# Customize Bell Icon (/platform/inbox/advanced-customization/customize-bell)

Learn how to fully customize the inbox component bell icon using your own components or third-party libraries.

The Novu Inbox includes a default bell icon that triggers the notification popover when clicked. You can use this bell as a standalone component or customize it to match your application's design system.

## Bell component

The Bell component displays Novu's default Inbox bell icon. It's designed to be used as a standalone trigger when you want to build your own custom notification center UI, such as a custom popover or a full-page view.

By using Bell component, you separate the trigger (the icon) from the content (the notification list), giving you full control over the layout and behavior of your application's notification center.

```tsx
import { Inbox, Bell } from '@novu/react';
 
function BellComponent() {
  return (
      <Inbox
        applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
        subscriber="YOUR_SUBSCRIBER_ID"
      >
        <Bell/>
      </Inbox>
  );
}
export default BellComponent;
```

<Callout>See the [Custom Popover documentation](/platform/inbox/advanced-customization/customize-popover) for how to use the Bell component with third party library like Radix UI to trigger a custom popover that contains the notification list.</Callout>

## Replace the default Bell Icon

Replace the default bell icon that comes with the Inbox component with your own custom React component or a third-party UI library component to match your application's design. You can do this using the `renderBell` prop.

![Custom bell](/images/inbox/custom-bell.gif)

<Tabs items={['Custom bell', 'Custom bell showing unread count', 'Custom bell with severity']}>
  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';

    function CustomBell() {
      return (
          <Inbox
            applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
            subscriber="YOUR_SUBSCRIBER_ID"
            renderBell={() => {
              return (
                <div className="bg-blue-300 p-4 inline-flex">
                  New notifications
                </div>
              );
            }}
          />
      );
    }
    export default CustomBell;
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';

    function CustomBell() {
      return (
        <Inbox 
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          renderBell={(unreadCount) => {
              return (
                <div className="bg-blue-300 p-4 inline-flex">
                New {unreadCount.total} notifications
                </div>
              );
            }}
        />
      );
    }
    export default CustomBell;
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox, SeverityLevelEnum } from '@novu/react';

    function CustomBell() {
      return (
        <Inbox 
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          renderBell={(unreadCount) => {
              return (
                <div className="bg-blue-300 p-4 inline-flex">
                  High severity $
                  {unreadCount.severity[SeverityLevelEnum.HIGH]}{' '}
                  notifications
                </div>
              );
            }}
        />
      );
    }
    export default CustomBell;
    ```
  </Tab>
</Tabs>


# Customize Notification Items (/platform/inbox/advanced-customization/customize-notification-items)

Learn how to use render props in the Inbox component to customize the subject, body, avatar, default and custom actions, or the entire notification item.

Novu exposes render props to customize parts of the default Inbox notification item—subject, body, avatar, default/custom actions, or the entire notification.

![Notification items](/images/inbox/notification-item.png)

Each render prop receives the full notification object, giving you access to all the data needed to build a fully custom UI.

## Customize notification subject

Use the `renderSubject` prop to provide a custom component for the notification's subject line while keeping the rest of the notification style intact.

![Customize notification subject](/images/inbox/custom-notification-subject.png)

```tsx
import { Inbox } from '@novu/react';
 
function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderSubject={(notification) => (
        <strong>{notification.subject.toUpperCase()}</strong>
      )}
    />
  );
}

export default NovuInbox;
```

## Customize notification body

Use `renderBody` if you want to keep the default Inbox UI and only change how the body is rendered. This is useful when you want to customize content formatting or include additional fields from the data object.

![Customize notification body](/images/inbox/custom-notification-body.png)

```tsx
import { Inbox } from '@novu/react';
 
function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderBody={(notification) => (
        <div>
          <p>🔔 New alert: {notification.body}</p>
        </div>
      )}
    />
  );
}

export default NovuInbox;
```

## Customize notification avatar

Use the `renderAvatar` prop to replace the default notification avatar with your own custom component. This allows you to display user images, icons, or any other visual element that fits your application's design.

![Customize the notification avatar](/images/inbox/customize-notification-avatar.png)

```tsx
import { Inbox } from '@novu/react';
 
function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderAvatar={(notification) => (
        <div className="w-8 h-8 rounded-full bg-gray-200 text-gray-700 flex items-center justify-center text-sm font-bold">
          VY
        </div>
      )}
    />
  );
}

export default NovuInbox;
```

## Customize notification actions

Novu provides render props to customize actions:

### Default actions

Use the `renderDefaultActions` prop to override the default action buttons for notifications, such as "Archive," "Mark as Read," and "Snooze."

![Customize the default actions](/images/inbox/customize-default-actions.png)

```tsx
import { Inbox } from '@novu/react';
import { Archive, Check } from 'lucide-react';
 
function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderDefaultActions={(notification) => {
        <div className="flex gap-2">
          <button
            className="p-1 text-green-600 hover:text-green-800"
            title="Mark as read"
          >
            <Check className="w-4 h-4" />
          </button>
          <button
            className="p-1 text-gray-500 hover:text-gray-700"
            title="Archive"
          >
            <Archive className="w-4 h-4" />
          </button>
        </div>
      }}
    />
  );
}

export default NovuInbox;
```

### Custom actions

Use the `renderCustomActions` prop to override the primary and secondary actions buttons with your own action button. This is useful for creating unique design and interactions specific to your application.

![Customize the custom actions](/images/inbox/customize-custom-actions.png)

```tsx
import { Inbox } from '@novu/react';
 
function NovuInbox() {

  const primaryButtonStyle = {
    border: 'none',
    padding: '5px 10px',
    borderRadius: '6px',
    cursor: 'pointer',
    fontSize: '12px',
    background: '#FB4CA3',
    color: 'white',
    boxShadow: '0 1px 2px rgba(0,0,0,0.1)',
  };

  const secondaryButtonStyle = {
    border: '1px solid #E0E0E0',
    padding: '5px 10px',
    borderRadius: '6px',
    cursor: 'pointer',
    fontSize: '12px',
    background: '#00B698',
    color: '#ffffff',
  };

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderCustomActions={(notification) => {
        return (
          <div style={{ display: 'flex', gap: '10px', marginTop: '12px' }}>
            {notification.secondaryAction && (
              <button
                style={secondaryButtonStyle}
              >
                Sign in
              </button>
            )}
            {notification.primaryAction && (
              <button 
                style={primaryButtonStyle}
              >
                {notification.primaryAction.label}
              </button>
            )}
          </div>
        );
      }}
    />
  );
}

export default NovuInbox;
```

## Customize the entire notification item

Use the `renderNotification` prop to customize the entire notification item in the Inbox UI, including the container, layout, and the content of the subject and body of each notification.

<Callout type="warn"> While `renderNotification` gives you full control over the notification UI, it is **not recommended** for most use cases. Using it means you will have to **re-create the Inbox component built-in actions** like mark as read, archive snooze, and other interaction tooltips yourself.</Callout>

![Customize entire notification item](/images/inbox/custom-notification.png)

```tsx
import { Inbox } from '@novu/react';
 
function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => (
        <div style={{ padding: '10px', border: '1px solid #ccc', marginBottom: '10px' }}>
          <h3>{notification.subject}</h3>
          <p>{notification.body}</p>
        </div>
      )}
    />
  );
}

export default NovuInbox;
```


# Customize Popover (/platform/inbox/advanced-customization/customize-popover)

Learn how to display the Inbox content outside the default popover and integrate it into your own custom popover or page layout.

The Inbox component provides a built-in popover triggered by its bell icon. In situations where you want more control over how and where notifications appear, you can display the notification feed directly or mount it inside your own custom popover, modal, or panel.

## Display the standalone notification feed

You can render the notification feed directly into any part of your application, such as a dashboard panel or a dedicated notifications page. This is useful for situations where you don't need a popover trigger at all. Novu provides two components for this.

Both components support the same customization props as the Inbox component, except for configuration options (like `applicationIdentifier`, `subscriber`, and `renderBell`).

### Notifications component

The Notifications component renders the core notification experience, which includes the Inbox header (with title and dropdown), the scrollable list of notifications, and the footer.

![notfications component](/images/inbox/notifications-component.png)

```tsx
import { Inbox, Notifications } from '@novu/react';

function NotificationFeed() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
    >
      <Notifications />
    </Inbox>
  );
}

export default NotificationFeed;
```

### InboxContent component

The InboxContent component renders everything the Notifications component does, but with one key addition: the Preferences page. This allows users to manage their notification settings directly from the component.

![notfications component](/images/inbox/inboxcontent-component.png)

```tsx
import { Inbox, InboxContent } from '@novu/react';

function NotificationFeed() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
    >
      <InboxContent />
    </Inbox>
  );
}

export default NotificationFeed;
```

## Building a custom popover

Use the Notifications or InboxContent components inside your own popover to keep all of Novu’s notification functionality while integrating with any external UI library. Trigger the popover with the Bell component or your own custom trigger.

<Tabs items={['Using Notifications', 'Using InboxContent', 'With shadcn/ui Drawer']}>
  <Tab title="Using Notifications">
    ```tsx
    import { Inbox, Notifications, Bell } from '@novu/react';
    import { Popover, PopoverTrigger } from '@radix-ui/react-popover';
    import { PopoverContent } from '@radix-ui/react-popover';

    function CustomPopoverPage() {

      return (
          <Inbox
            applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
            subscriber="YOUR_SUBSCRIBER_ID"
          >
            <Popover>
              <PopoverTrigger>
                <Bell />
              </PopoverTrigger>
              <PopoverContent className="h-[600px] w-[400px] p-0">
                <Notifications />
              </PopoverContent>
            </Popover>
          </Inbox>
      );
    }
    export default CustomPopoverPage;
    ```
  </Tab>

  <Tab title="Using InboxContent">
    ```tsx
    import { Inbox, InboxContent, Bell } from '@novu/react';
    import { Popover, PopoverTrigger } from '@radix-ui/react-popover';
    import { PopoverContent } from '@radix-ui/react-popover';

    function CustomPopoverPage() {

      return (
          <Inbox
            applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
            subscriber="YOUR_SUBSCRIBER_ID"
          >
            <Popover>
              <PopoverTrigger>
                <Bell />
              </PopoverTrigger>
              <PopoverContent className="h-[600px] w-[400px] p-0">
                <InboxContent />
              </PopoverContent>
            </Popover>
          </Inbox>
      );
    }
    export default CustomPopoverPage;
    ```
  </Tab>

  <Tab title="With shadcn/ui Drawer">
    ```tsx
    "use client";

    import {
      Drawer,
      DrawerContent,
      DrawerHeader,
      DrawerTitle,
      DrawerTrigger,
    } from "@/components/ui/drawer";
    import { Inbox, InboxContent } from "@novu/react";

    export default function NovuInbox() {
      return (
        <div className="min-h-screen p-8">
          <Inbox
            applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
            subscriber="YOUR_SUBSCRIBER_ID"
          >
            <Drawer direction="left">
              <DrawerTrigger
                className="rounded-full border border-solid border-black/[.08] dark:border-white/[.145] transition-colors flex items-center justify-center hover:bg-[#f2f2f2] darkhoverbg-[#1a1a1a] hover:border-transparent font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5"
              >
                Open Drawer
              </DrawerTrigger>
              <DrawerContent className="w-[300px]">
                <DrawerHeader>
                  <DrawerTitle>Novu Inbox</DrawerTitle>
                </DrawerHeader>
                <InboxContent />
              </DrawerContent>
            </Drawer>
          </Inbox>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>


# Use HTML in Notification Content (/platform/inbox/advanced-customization/html-in-notifications)

Learn how to enable and display raw HTML in the notification subject and body for rich formatting.

By default, Novu sanitizes the `subject` and `body` of all in-app step notifications to ensure that they are safe to display. This process prevents security risks by removing suspicious HTML tags (like `<script>`) and escaping HTML entities (like `&`, `<`, `>`).

However, you can disable this feature to display richly formatted content with links, bold text, and more. The Inbox component supports this by letting you inject HTML using `dangerouslySetInnerHTML` into your notification content, providing control over layout, formatting, and design.

<Callout type="warn">Disabling content sanitization can expose your application to Cross-Site Scripting (XSS) attacks. You should only enable this feature if you completely trust the source of your notification data and have full control over the trigger payload.</Callout>

Enabling HTML formatting is a two-step process: you must first disable sanitization in your Novu workflow and then use the appropriate render prop in your application to display the HTML.

## Step 1: Disable content sanitization in your workflow

In your Novu workflow:

1. navigate to the **In-App editor**.
2. In the editor, find and turn on the **Disable content sanitization** toggle.

![Disable content sanitization in the Novu in-app step editor](/images/inbox/disable-content-sanitization.png)

This setting instructs the Novu API to send the raw, unescaped HTML content for both the subject and body to your application.

## Step 2: Display the HTML in your app

Once sanitization is disabled, you must use a `render` prop in your application to correctly interpret and display the raw HTML. Use React's `dangerouslySetInnerHTML` property for this purpose.

### For the notification body

To display HTML in the notification's body, use the `renderBody` prop.

```tsx
import { Inbox } from '@novu/react';

function CustomInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId="YOUR_SUBSCRIBER_ID"
      renderBody={(notification) => (
        <div dangerouslySetInnerHTML={{ __html: notification.body }} />
      )}
    />
  );
}

export default CustomInbox;
```

#### Example usage

If your workflow's in-app message body contains the following content with HTML tags and variables:

```html html tags with dynamic values
{{subscriber.firstName}}, A <b>Good news!</b> We've just launched the <i>advanced
analytics dashboard</i> you asked for. Check it out <a href="[https://example.com](https://example.com)"
target="_blank">here</a>.
```

When you trigger this notification, the code will render this content with the HTML formatting applied, displaying bold and italic text, and a functional link.

![Display HTML in notification body](/images/inbox/display-html-in-body.png)

### For the notification subject

Similarly, to display HTML in the notification's subject, use the `renderSubject` prop.

```tsx
import { Inbox } from '@novu/react';

function CustomInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId="YOUR_SUBSCRIBER_ID"
      renderSubject={(notification) => (
        <span dangerouslySetInnerHTML={{ __html: notification.subject }} />
      )}
    />
  );
}

export default CustomInbox;
```

### For the notification subject and body

If you need to display HTML in both the subject and body, use the `renderNotification` prop.

```tsx
import { Inbox } from '@novu/react';

function CustomInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => (
        <div style={{ borderBottom: '1px solid #eee', padding: '16px' }}>
          <h3 dangerouslySetInnerHTML={{ __html: notification.subject }} />
          <div dangerouslySetInnerHTML={{ __html: notification.body }} />
        </div>
      )}
    />
  );
}

export default CustomInbox;
```


# Notification Click Behavior (/platform/inbox/advanced-customization/notification-click-behavior)

Learn how to configure routing and interaction behavior for notifications using routerPush and click handlers.

The Inbox component provides props that can be used to manage navigation and event handling, giving you full control over how notifications behave when users interact with them.

## Enable navigation from notifications

The Inbox component uses the `routerPush` prop to make your notifications navigable. When you define a `redirect.url` in your workflow definitions, Novu automatically passes this URL to the `routerPush` function you provide.

<Tabs items={['Next.js', 'React', 'Remix', 'Gatsby']}>
  <Tab>
    ```tsx
    import { Inbox } from '@novu/nextjs';
    import { useRouter } from 'next/router';

    export function NovuInbox() {
      const router = useRouter();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriberId="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => router.push(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { useNavigate } from 'react-router-dom';

    export function NovuInbox() {
      const navigate = useNavigate();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriberId="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { useNavigate } from '@remix-run/react';

    export function NovuInbox() {
      const navigate = useNavigate();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriberId="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { navigate } from 'gatsby';

    export function NovuInbox() {
      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriberId="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>
</Tabs>

To make navigation work, you need to specify the `routerPush` behavior based on your routing library

## Event Handling

Beyond navigation, you can handle various notification events to create custom behaviors like opening modals, triggering actions, or updating application state.

### Handle notification click events

You can intercept a notification click event and define a custom behavior using the `onNotificationClick` prop. This is particularly useful when you want to open modals, drawers, or perform custom actions instead of navigating to a page.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      onNotificationClick={(notification) => {
        // your logic to handle notification click
      }}
    />
  );
}
```

### Handle action button clicks

Some notifications include primary and secondary action buttons. You can handle these clicks using the `onPrimaryActionClick` and `onSecondaryActionClick` props. These handlers give you access to the notification object and allow you to implement custom logic for each action type.

```tsx
import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      onPrimaryActionClick={(notification) => {
        // your logic to handle primary action click
      }}
      onSecondaryActionClick={(notification) => {
        // your logic to handle secondary action click
      }}
    />
  );
}
```


# Localizing the Inbox component (/platform/inbox/advanced-features/localization)

Learn how to customize the Inbox UI for different languages using the localization prop.

Localize the UI text of the Inbox component to align with your product’s voice or support multiple languages. This helps create a more consistent, accessible experience for subscribers across different regions.

<Callout>Localization only updates the UI text in the Inbox. It doesn’t translate the content of your notifications. To send messages in different languages, use the [Translations](/platform/workflow/advanced-features/translations).</Callout>

## Using the localization prop

Override the default text in the Inbox component UI by passing a `localization` prop. This prop accepts an object of key-value pairs, where each key maps to a specific UI element and each value is your custom string.

If you omit any keys, then the component reverts to the default `en-US` values.

![Overriding the default text in the Inbox component UI using localization prop](/images/inbox/localization.png)

```tsx
import { Inbox } from '@novu/react';

function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId="YOUR_SUBSCRIBER_ID"
      localization={{
        'inbox.filters.dropdownOptions.unread': 'Unread only',
        'notification.actions.archive.tooltip': 'Move to archive',
        'preferences.title': 'My Preferences',
        locale: 'en-US',
      }}
    />
  );
}

export default NovuInbox;
```

<Callout>Localization is also fully supported in @novu/react-native. </Callout>

## Available localization keys

Here is a list of [all the keys available for localization](https://github.com/novuhq/novu/blob/next/packages/js/src/ui/config/defaultLocalization.ts#L1), grouped by their respective sections in the Inbox UI.

### Filters

| Key                                      | Default Value   | Description                            |
| ---------------------------------------- | --------------- | -------------------------------------- |
| `inbox.filters.dropdownOptions.unread`   | `Unread only`   | Text for the "unread" filter option.   |
| `inbox.filters.dropdownOptions.default`  | `Unread & read` | Text for the default filter option.    |
| `inbox.filters.dropdownOptions.archived` | `Archived`      | Text for the "archived" filter option. |
| `inbox.filters.dropdownOptions.snoozed`  | `Snoozed`       | Text for the "snoozed" filter option.  |
| `inbox.filters.labels.unread`            | `Unread`        | Label for the unread tab.              |
| `inbox.filters.labels.default`           | `Inbox`         | Label for the main inbox tab.          |
| `inbox.filters.labels.archived`          | `Archived`      | Label for the archived tab.            |
| `inbox.filters.labels.snoozed`           | `Snoozed`       | Label for the snoozed tab.             |

### Notifications

| Key                                 | Default Value                                                                                             | Description                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `notifications.emptyNotice`         | `Quiet for now. Check back later.`                                                                        | Message displayed when the notification list is empty.                  |
| `notifications.actions.readAll`     | `Mark all as read`                                                                                        | Text for the action to mark all notifications as read.                  |
| `notifications.actions.archiveAll`  | `Archive all`                                                                                             | Text for the action to archive all notifications.                       |
| `notifications.actions.archiveRead` | `Archive read`                                                                                            | Text for the action to archive all read notifications.                  |
| `notifications.newNotifications`    | ``({ notificationCount }: { notificationCount: number }) => `${notificationCount} new notification(s)` `` | A function that returns the string for the new notifications indicator. |
| `notification.snoozedUntil`         | `Snoozed until`                                                                                           | Text displayed before the unsnooze time on a snoozed notification.      |

### Notification actions (tooltips)

| Key                                      | Default Value    | Description                              |
| ---------------------------------------- | ---------------- | ---------------------------------------- |
| `notification.actions.read.tooltip`      | `Mark as read`   | Tooltip for the "mark as read" action.   |
| `notification.actions.unread.tooltip`    | `Mark as unread` | Tooltip for the "mark as unread" action. |
| `notification.actions.archive.tooltip`   | `Archive`        | Tooltip for the "archive" action.        |
| `notification.actions.unarchive.tooltip` | `Unarchive`      | Tooltip for the "unarchive" action.      |
| `notification.actions.snooze.tooltip`    | `Snooze`         | Tooltip for the "snooze" action.         |
| `notification.actions.unsnooze.tooltip`  | `Unsnooze`       | Tooltip for the "unsnooze" action.       |

### Snooze menu

| Key                                       | Default Value                                                                                     | Description                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `snooze.options.anHourFromNow`            | `An hour from now`                                                                                | Text for the "snooze for one hour" option.                                |
| `snooze.options.inOneDay`                 | `Tomorrow`                                                                                        | Text for the "snooze for one day" option.                                 |
| `snooze.options.inOneWeek`                | `Next week`                                                                                       | Text for the "snooze for one week" option.                                |
| `snooze.options.customTime`               | `Custom time...`                                                                                  | Text for the option to open the custom date picker.                       |
| `snooze.datePicker.timePickerLabel`       | `Time`                                                                                            | Label for the time input in the date picker.                              |
| `snooze.datePicker.apply`                 | `Apply`                                                                                           | Text for the "Apply" button in the date picker.                           |
| `snooze.datePicker.cancel`                | `Cancel`                                                                                          | Text for the "Cancel" button in the date picker.                          |
| `snooze.datePicker.pastDateTooltip`       | `Selected time must be at least 3 minutes in the future`                                          | Tooltip shown when a past time is selected.                               |
| `snooze.datePicker.noDateSelectedTooltip` | `Please select a date`                                                                            | Tooltip shown when applying without selecting a date.                     |
| `snooze.datePicker.exceedingLimitTooltip` | ``({days}) => `Selected time cannot exceed ${days === 1 ? '24 hours' : `${days} days`} from now`` | Tooltip shown when the selected date exceeds the allowed snooze duration. |

### Preferences

| Key                                     | Default Value                                                                     | Description                                                           |
| --------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `preferences.title`                     | `Preferences`                                                                     | The main title of the preferences screen.                             |
| `preferences.emptyNotice`               | `No notification specific preferences yet.`                                       | Message shown when no workflow preferences are available.             |
| `preferences.global`                    | `Global Preferences`                                                              | Title for the global preferences section.                             |
| `preferences.group.info`                | `Applies to all notifications under this group.`                                  | Informational text for grouped preferences.                           |
| `preferences.workflow.disabled.notice`  | `Contact admin to enable subscription management for this critical notification.` | Notice shown for workflows where subscription management is disabled. |
| `preferences.workflow.disabled.tooltip` | `Contact admin to edit`                                                           | Tooltip shown for a disabled workflow preference.                     |

To view the latest and most complete key list, check the defaultLocalization.ts file.

## Localizing workflow names in preferences

To display localized names for specific workflows in the Preferences UI, use the dynamic object within the localization prop.

Each key in dynamic should match a workflow ID, and its value should be the localized workflow name.

![Localizing workflow names in preferences](/images/inbox/localizing-workflow-names.png)

```tsx
import { Inbox } from '@novu/react';

function NovuInbox() {
  return (
      <Inbox
        applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
        subscriberId="YOUR_SUBSCRIBER_ID"
        localization={{
          dynamic: {
            // use the workflowId as a key to localize the workflow name
            'new-comment-on-post': 'Post comments',
            'new-follower-digest': 'New Follower Updates',
          }
        }}
      />
  )
}
export default NovuInbox;

```


# Inbox Multi-tenancy Configuration (/platform/inbox/advanced-features/multi-tenancy)

Learn how to use context to implement multi-tenant notifications to support different organizations or workspaces within your application.

Multi-tenancy in Novu lets you isolate notifications for different organizations, environments, or workspaces within the same Novu project. Instead of creating separate subscribers or workflows for each tenant, you can use [Contexts](/platform/workflow/advanced-features/contexts) to define and manage tenant boundaries.

<Callout>This guide assumes you already understand what Contexts are. If not, start with the [Contexts](/platform/workflow/advanced-features/contexts) documentation.</Callout>

## How multi-tenancy works in Novu

Multi-tenancy in Novu is built on top of Contexts, which act as lightweight tags that group notifications by logical boundaries such as tenants, workspaces, or environments.

When a notification is triggered with a tenant context, Novu automatically associates all notifications and preferences with that tenant. The same tenant context passed to the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> filters notifications for that specific organization, ensuring users only see messages relevant to their workspace.

## How to implement multi-tenancy in Novu

Implementing a multi-tenant system involves a few key steps:

### Define a tenant context

A Tenant Context is a JSON object that identifies a specific tenant and can store any related data you need, such as company name, logo, or plan type.

You can create a tenant context using the Novu dashboard, API or from the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method>. if it doesn’t already exist, Novu automatically creates it.

Here are ways you can pass context:

```jsx
// Simple tenant ID

context: {
  tenant: 'acme-corp' 
}

// Rich tenant object

context: {
  tenant: {
    id: 'acme-corp',
    data: {
      name: 'Acme Corporation',
      logo: 'https://cdn.acme.com/logo.png'
    }
  }
}
```

You can also manage all tenant contexts centrally from the Novu dashboard or API.

<Callout>To learn more about creating, updating, and deleting contexts, see the [Manage Contexts](/platform/workflow/advanced-features/contexts) guide.</Callout>

### Applying tenant context in workflows

Once you’ve defined your tenant context, you can use it when triggering workflows. During workflow trigger, Novu first checks if that context already exists.

If not, Novu automatically creates it — but if it does exist, Novu reuses the existing record instead of updating it, to prevent accidental overwrites.

```tsx
import { novu } from './client';

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'user-123',
  },
  payload: {
    amount: '$250',
    plan: 'Pro',
  },
  context: {
    tenant: {
      id: 'acme-corp',
      data: {
        name: 'Acme Corporation',
        plan: 'enterprise',
      },
    },
  },
});
```

In this example:

* The tenant context identifies the organization (“Acme Corporation”).
* Notifications triggered with this tenant context will be isolated to that tenant’s workspace.
* The same tenant ID must be passed to the Inbox to display these notifications.

<Callout>Learn more about applying Context in workflows in [Contexts in Workflows](/platform/workflow/advanced-features/contexts/contexts-in-workflows) documentation.</Callout>

### Filter the Inbox by tenant

Once your workflows are sending tenant-scoped notifications, you can filter the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> so that each subscriber only sees notifications relevant to their tenant.

This is done by passing the same tenant context used in your workflow triggers to the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method>.

```tsx
import { Inbox } from '@novu/react';

<Inbox
  applicationIdentifier="APPLICATION_IDENTIFIER"
  subscriber="SUBSCRIBER_ID"
  context={{
    tenant: {
      id: 'acme-corp',
      data: {
        name: 'Acme Corporation',
        plan: 'enterprise',
      },
    },
  }}
/>

```

In this setup:

* The <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> filters notifications based on an exact context match.
* Only notifications triggered with tenant: `{ id: 'acme-corp' }` will appear in the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method>.
* Notifications from other tenants are automatically excluded.

<Callout>If the tenant context doesn’t already exist in Novu, the Inbox will automatically find or create it. Learn more in [Inbox with Context](/platform/inbox/configuration/inbox-with-context).</Callout>

### Customize notification content based on tenant

With contexts, you can use tenant-level data to dynamically personalize notification content, branding, and workflow logic, all from a single workflow definition.

This eliminates the need to duplicate workflows or templates for each tenant while still keeping the experience distinct and relevant.

#### Using tenant data in templates

Once a tenant context is created, its data becomes accessible in all template editors (email, in-app, SMS, and push) through the `{{context}}` helper.

#### Dynamic logic per tenant

You can also use tenant context data to control conditional logic inside your workflows. For example, you may want to send certain updates only to enterprise tenants.

<Callout>To learn more about customizing notification content with context, refer to the [Contexts in Workflows](/platform/workflow/advanced-features/contexts/contexts-in-workflows) documentation.</Callout>


# Inbox Data Object (/platform/inbox/configuration/data-object)

Learn how to use the data object to extend in-app notifications with custom metadata.

The *data object* is a customizable key-value store available in the in-app step. You can use it to extend each Inbox component notification by embedding custom data. The data can then be used to personalize how messages appear in the Inbox component.

## Define the data object

You define the data object inside an in-app step in your workflow on the Novu dashboard.
Each entry is a key-value pair, referred to as a property. You can define up to 10 properties per in-app step. Each property can be:

* **Static**: Fixed values such as "status": "merged" or "icon": "heart".
  or
* **Dynamic**: Values derived from subscriber or payload data, such as `{{subscriber.firstName}}` or `{{payload.issueId}}`.

![Data object](/images/inbox/data-object.png)

<Callout>The data object supports only scalar values, such as strings, numbers, booleans, or null. String values are limited to 256 characters. There is a limit of 10 data object properties per in-app step.</Callout>

## Use the data object in the \<Inbox />

The data object is available on the frontend as `notification.data`. You can use it inside the `renderNotification` function to customize how each notification is displayed.

```tsx
import { Inbox } from '@novu/react';

function NovuDataObject() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => (
       <div>
        <p>{notification.data?.firstName}</p>            
        <p>{notification.data?.emoji}</p>
      </div>
     )}
    />
  );
}

export default NovuDataObject;
```

<Callout type="warn">The data object is included in the client response. Avoid storing sensitive information, such as API keys or passwords, in `notification.data`. Workflow trigger payload may contain sensitive information, so avoid using the complete payload in the data object. Use only required and insensitive payload data in the data object.</Callout>

### Add type safety (optional)

For TypeScript users, define a NotificationData interface to ensure type safety when accessing `notification.data`.

```tsx
declare global {
  interface NotificationData {
    reactionType?: string;
    entityId?: string;
    userName?: string;
  }
}
```

This allows TypeScript to infer the structure of `notification.data`, reducing errors when accessing properties.

## Use data object keys as filters for tabs

You can use data object keys as filter for tabs. For more information, refer to [Tabs](/platform/inbox/configuration/tabs#filter-tabs-by-data-attributes).

```tsx
import { Inbox } from '@novu/react';

export default function InboxWithFilters() {

  const tabs = [
    {
      label: 'High Priority',
      filter: {
        data: { priority: 'high' },
      },
    },
    {
      label: 'User Activity',
      filter: {
        data: { type: 'login' },
      },
    },
  ];

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}
```


# Customize Icons in the Inbox (/platform/inbox/configuration/icons)

Learn how to override the default icons in the Inbox UI using the appearance prop.

You can customize or replace all the default icons in the Inbox UI with custom icons from your preferred library, such as [react-icons](https://react-icons.github.io/react-icons/) or [Material Icons](https://mui.com/material-ui/material-icons/), to match your visual style using the icons' key in the `appearance` prop.

For each icon that you want to customize, provide a function that returns your custom icon as a React component.

```tsx
import { Inbox } from '@novu/react';
import { RiSettings3Fill, RiArrowDownLine, RiNotification3Fill} from 'react-icons/ri';

const appearance = {
    icons: {
      cogs: () => <RiSettings3Fill />,
      arrowDown: () => <RiArrowDownLine />,
      bell: () => <RiNotification3Fill />,
    },
  };

export function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}
```

## List of customizable icons

Use these keys in the `appearance.icons` property to customize specific icons in the Inbox component:

| Icon key             | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `arrowDown`          | Down arrow used in drop-downs and expandable sections |
| `arrowDropDown`      | Drop-down arrow in menus and selectors                |
| `arrowLeft`          | Left arrow used in pagination and navigation          |
| `arrowRight`         | Right arrow used in pagination and navigation         |
| `bell`               | Notification bell icon in the header                  |
| `chat`               | Chat channel icon in notification preferences         |
| `check`              | Checkmark icon used for selected items                |
| `clock`              | Date/time display for notifications                   |
| `cogs`               | Settings/preferences icon in the header               |
| `dots`               | More options menu (three dots) in notification items  |
| `email`              | Email channel icon in notification preferences        |
| `inApp`              | In-app channel icon in notification preferences       |
| `markAsArchived`     | Icon for archiving notifications                      |
| `markAsArchivedRead` | Icon for marking notifications as archived and read   |
| `markAsRead`         | Icon for marking notifications as read                |
| `markAsUnread`       | Icon for marking notifications as unread              |
| `markAsUnarchived`   | Icon for unarchiving notifications                    |
| `push`               | Push notification channel icon in preferences         |
| `sms`                | SMS channel icon in notification preferences          |
| `trash`              | Delete/remove icon for notifications                  |
| `unread`             | Indicator for unread notifications                    |
| `unsnooze`           | Icon for unsnoozed notifications                      |

<Callout type="info">
  You can inspect the Inbox component using your browser’s developer tools to discover icon keys. Icon elements have class names that start with `nv-` and include a 🖼️ emoji for easier identification. The part following `nv-` is the icon key. For example, an element with the class `nv-cogs` has the icon key `cogs`.
</Callout>


# Use Contexts for Inbox Personalization (/platform/inbox/configuration/inbox-with-context)

Learn how to use contexts in the Inbox component to filter and personalize notifications for your subscribers.

*Contexts* let you scope each `<Inbox />` instance to a specific environment, tenant, or app within your product. When combined with workflow-level contexts, they ensure that each `<Inbox />` displays only the notifications relevant to that specific context.

<Callout type="info">If you’re new to contexts, start from the [Contexts](/platform/workflow/advanced-features/contexts) section to understand how contexts are created, managed in Novu and how they used in workflows.</Callout>

## How context works in `<Inbox/>`

The <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> uses exact-match context filtering to determine which notifications to display. This means the context provided to the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> must match all the key-value pairs of the context used when the workflow was triggered.

This creates predictable isolation and ensures notifications are scoped to the context provided. If the contexts do not match exactly, the notification will not be delivered to that Inbox session.

* If workflow is triggered with a context but Inbox is initialized without a context, the notification will not be delivered to that Inbox session.
* If workflow is triggered without a context but Inbox is initialized with a context, the notification will not be delivered to that Inbox session.
* If workflow is triggered with a context but Inbox is initialized with a different context, the notification will not be delivered to that Inbox session.

| Workflow Context                           | Inbox Context            | Displayed? |
| ------------------------------------------ | ------------------------ | ---------- |
| `{ "tenant": "acme" }`                     | `{ "tenant": "acme" }`   | Yes        |
| `{}`                                       | `{}`                     | Yes        |
| `{}`                                       | `{ "tenant": "acme" }`   | No         |
| `{ "tenant": "acme" }`                     | `{ "tenant": "globex" }` | No         |
| `{ "tenant": "acme" }`                     | `{}`                     | No         |
| `{ "tenant": "acme" }, { "app": "first" }` | `{ "tenant": "acme" }`   | No         |

### Creating context via `<Inbox/>`

If a new context is passed from the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> that doesn’t already exist, Novu will automatically find or create it. This means you don’t have to manually set up contexts before using them, they are created just in time.

However, if a context already exists, its data won’t be updated automatically. This prevents unintentional overwrites of stored context data.

This is particularly useful for:

* **Dynamic tenants or organizations**: When users join or switch organizations.
* **Feature-specific dashboards**: Where each section of your app has its own notification scope.

You can view all automatically created contexts under the Contexts section of your Novu dashboard.

## Applying context to the Inbox

You can filter the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> notifications to a specific context, by passing a context prop to the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> component.

This prop's value defines the filter for that session, and it will only request and show notifications that match this context.

```tsx
import { Inbox } from '@novu/react';

<Inbox
  applicationIdentifier="APPLICATION_IDENTIFIER"
  subscriber="SUBSCRIBER_ID"
  context={{
    tenant: {
      "id": "acme-corp",
      "data": {
        "name": "Acme Corporation",
        "plan": "enterprise",
      }
    },
  }}
/>
```

When a workflow with these exact context is triggered, as seen below

![Context in trigger](/images/inbox/context-trigger.png)

Then, the notifications will be delivered to the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method>.

![Inbox with context](/images/inbox/context.png)

<Callout>To learn how to use context with the Novu SDKs, visit the <Method href="/platform/sdks/javascript">{`Context`}</Method> documentation.</Callout>

## How to secure your context

Because the context prop is set on the client-side, a malicious user could potentially tamper with it to view notifications from a different tenant.

To prevent this, you must fetch the context details and contextHash from your server and pass them to the Inbox component.

<Callout type="info">We need to use `canonicalize` here, cause context is a dynamic object. `canonicalize` is used to serialize the JSON in a way that the order of keys or whitespaces etc doesn’t matter. The library should be based on [RFC-8259](https://datatracker.ietf.org/doc/html/rfc8259).</Callout>

```ts title="utils/context-hash.ts"
import { createHmac } from 'crypto';
import { canonicalize } from '@tufjs/canonical-json';

const context = {
  tenant: {
    id: "acme-corp",
    data: {
      name: "Acme Corporation",
      plan: "enterprise",
    },
  },
};

const contextHash = createHmac('sha256', "NOVU_SECRET_KEY")
  .update(canonicalize(context))
  .digest('hex');
```

```tsx title="components/InboxWithContextHash.tsx"
import { Inbox } from '@novu/react';

const { user } = currentUser();
const subscriberHash = user?.novuSubscriberHash;
const contextHash = user?.novuContextHash;


const context = {
  tenant: {
    id: "acme-corp",
    data: {
      name: "Acme Corporation",
      plan: "enterprise",
    },
  },
};

<Inbox
  applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
  subscriber="YOUR_SUBSCRIBER_ID"
  subscriberHash={subscriberHash}
  context={context}
  contextHash={contextHash}
/>
```

<Callout>Learn how to secure your <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> with HMAC encryption, refer to the [Prepare for Production](/platform/inbox/prepare-for-production) documentation.</Callout>


# Inbox Preferences Configuration (/platform/inbox/configuration/preferences)

Learn how to configure and customize subscriber preferences in your application using the Novu Inbox component.

The Preferences interface in the Inbox component lets subscribers customize how they receive notifications. By default, Novu renders a preferences icon inside the Inbox component, giving users access to global and workflow-specific settings directly from the UI.

<Callout type="info">
  A workflow marked as "critical" on the Novu dashboard cannot be disabled by the user and will not appear in their preferences UI. You can override this behavior by setting the `criticality` field in the `preferencesFilter` prop.
</Callout>

![Global preferences](/images/inbox/preferences.gif)

<Callout>You can also hide any workflow from appearing in the subscriber preferences UI using the appearance prop. To learn more, refer to the documentation on [styling the Inbox UI elements](/platform/inbox/configuration/styling#style-the-inbox-ui-elements).</Callout>

## Global preferences

Global preferences apply across all workflows. For example, a subscriber can turn off an email or SMS channels globally, ensuring that they don’t receive notifications through that channel from any workflow.

![Global preferences](/images/inbox/global-preferences.png)

Global preferences override individual workflow preferences. If a channel is turned off (disabled) globally, notifications for that channel will not be sent even if it is enabled for a specific workflow.

### Hide global preferences UI

Global preferences are always shown in the preferences list and cannot be removed, but you can hide it from the UI if necessary by using appearance prop.

```tsx
import { Inbox } from '@novu/react';

function InboxWithGlobalPreferencesHidden() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{
        elements: {
          workflowContainer: "[&:first-child]:!hidden",
        },
      }}
    />
  );
}

export default InboxWithGlobalPreferencesHidden;
```

## Workflow-specific preferences

Each workflow has its own set of channel preferences in the Inbox UI, where your subscribers can control how they receive notifications for that specific workflow. For example, a subscriber might prefer to receive email notifications for an account updates workflow but in-app notifications for security alerts.

<Callout>
  The name given to a workflow in the Novu dashboard is the name your subscribers will see in their preferences UI.
</Callout>

![Workflow specific preferences](/images/inbox/workflow-specific-preferences.png)

For each workflow, the Inbox UI only displays the channels step used in a given workflow.

<Callout type="info">Learn how to configure channel steps in a workflow in the [Create a Workflow guide](/platform/workflow/create-a-workflow).</Callout>

### Filter preferences

Use the `preferencesFilter` prop on the Inbox component to control which workflows are shown in the subscriber preferences list. You can filter workflows based on their assigned tags or their criticality level (critical or non-critical).

#### Filter by tags

This filtering works by matching the tags you provide in the prop with the tags assigned to the workflows. Only workflows with matching tags will be visible to the subscriber in their preferences UI.

```tsx
import { Inbox } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesFilter={{ tags: ['general', 'admin', 'security'] }} />
  );
}

export default InboxPreferences;
```

#### Filter by workflow criticality

You can also filter which workflows are displayed based on whether they are marked as "critical". By default, only non-critical workflows are shown. You can change this behavior using the `criticality` key with `WorkflowCriticalityEnum`.

Possible values are:

* `WorkflowCriticalityEnum.NON_CRITICAL`: (Default) Only shows non-critical workflows.
* `WorkflowCriticalityEnum.CRITICAL`: Only shows critical workflows.
* `WorkflowCriticalityEnum.ALL`: Shows all workflows, including critical ones.

For instance, to display all workflows, you would do the following:

```tsx
import { Inbox, WorkflowCriticalityEnum } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesFilter={{criticality: WorkflowCriticalityEnum.ALL}}
    />
  );
}

export default InboxPreferences;
```

#### Combining tags and criticality

You can combine tags and criticality filters to create more specific views. For example, the code below will display all workflows (both critical and non-critical) that have the 'general', 'admin', or 'security' tags.

```tsx
import { Inbox, WorkflowCriticalityEnum } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesFilter={{ tags: ['general', 'admin', 'security'], criticality: WorkflowCriticalityEnum.ALL }} />
  );
}

export default InboxPreferences;
```

### Group preferences

Use the `preferenceGroups` prop on the Inbox component to organize workflows into meaningful sections in the subscriber preferences UI.

![Grouping preferences](/images/inbox/group-preferences.png)

Each group requires:

* **name**: The display name for the group
* **filter**: The filter logic (object or function) to determine which workflows belong in the group

There are different ways to group preferences, you can use either of them individually or combine different methods.

<Callout type="info">Grouping preference is supported in client-side SDKs starting from version 3.4.0.</Callout>

#### Group by tags

Use an object with a `tags` key to group workflows that share specific tags.

```tsx
import { Inbox } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'General',
          filter: { tags: ['account'] },
        },
      ]}
    />
  );
}

export default InboxPreferences;

```

#### Group by tags and workflow IDs

Combine `tags` and `workflowIds` for more targeted grouping.

```tsx
import { Inbox } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'Marketing',
          filter: { tags: ['marketing'], workflowIds: ['workflow-ids'] },
        },
      ]}
    />
  );
}

export default InboxPreferences;

```

#### Group all workflows

You can group all workflows under a single, descriptive heading like "All Notifications" or "General" to improve organization.

```tsx
import { Inbox } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'All Workflows',
          filter: ({ preferences }) => preferences
        },
      ]}
    />
  );
}

export default InboxPreferences;

```

#### Group using custom logic

You can define your own logic to group preferences by passing a function to the `filter` key. This function receives an object containing a `preferences` array, where each item represents a workflow preference, including both subscriber settings and workflow metadata.

Each item in the `preferences` array includes a `workflow` object with properties like `name`, `slug`, and `identifier`. You can use these fields to implement your grouping logic.

```tsx
import { Inbox } from '@novu/react';

function InboxPreferences() {

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'Alerts',
          filter: ({ preferences }) =>
            preferences.filter(({ workflow }) =>
              workflow?.name?.toLowerCase().includes('alerts')
            ),
        },
      ]}
    />
  );
}

export default InboxPreferences;
```

### Sort preferences

Use the `preferencesSort` prop on the Inbox component to customize the order in which workflows are displayed in the subscriber preferences list. This prop accepts a custom comparison function, similar to JavaScript's `Array.sort()` method.

The comparison function receives two preference objects (`a`, `b`) as arguments and should return:

* A negative number if `a` should come before `b`.
* A positive number if `b` should come before `a`.
* Zero if the order of `a` and `b` doesn't matter.

Each preference object contains a `workflow` property with metadata you can use for sorting, such as `name`, `tags`, `slug`, and `identifier`.

#### Sort alphabetically

You can sort workflows alphabetically by name in the preferences UI

```tsx
import { Inbox } from '@novu/react';

function InboxWithAlphabeticalSort() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesSort={(a, b) => {
        const aName = a.workflow?.name?.toLowerCase() || '';
        const bName = b.workflow?.name?.toLowerCase() || '';
        return aName.localeCompare(bName);
      }}
    />
  );
}

export default InboxWithAlphabeticalSort;
```

#### Sort by priority tag

You can implement more complex logic to meet your specific needs. This example prioritizes workflows tagged with "priority", placing them at the top of the list. All other workflows are then sorted alphabetically by name.

```tsx
import { Inbox } from '@novu/react';

function InboxWithSortedPreferences() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesSort={(a, b) => {
        const aName = a.workflow?.name?.toLowerCase() || '';
        const bName = b.workflow?.name?.toLowerCase() || '';
        const aHasPriorityTag = a.workflow?.tags?.includes('priority') || false;
        const bHasPriorityTag = b.workflow?.tags?.includes('priority') || false;
        
        // Priority workflows come first
        if (aHasPriorityTag && !bHasPriorityTag) return -1;
        if (!aHasPriorityTag && bHasPriorityTag) return 1;
        
        // Then sort alphabetically by name
        return aName.localeCompare(bName);
      }}
    />
  );
}

export default InboxWithSortedPreferences;
```

#### Sorting within groups

You can use `preferencesSort` together with `preferenceGroups`. In this case, sorting is applied within each group; this lets you both organize workflows into sections and control their order inside those sections.

For example, after grouping workflows by their functions, you can then sort the workflows alphabetically within each of those groups.

```tsx
import { Inbox } from '@novu/react';

function InboxWithGroupedAndSortedPreferences() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'Account Notifications',
          filter: { tags: ['account'] },
        },
        {
          name: 'Marketing Updates',
          filter: { tags: ['marketing'] },
        },
      ]}
      preferencesSort={(a, b) => {
        const aName = a.workflow?.name?.toLowerCase() || '';
        const bName = b.workflow?.name?.toLowerCase() || '';
        return aName.localeCompare(bName);
      }}
    />
  );
}

export default InboxWithGroupedAndSortedPreferences;
```

## Conditionally display preferences

This approach can also be used to show or hide elements. The example below hides the global preferences settings by checking the `preference.level` property.

```tsx
import { Inbox, PreferenceLevel } from '@novu/react';

export default function Novu() {

  const appearance = {
    elements: {
      workflowContainer: ({ preference }) => {
        if (preference.level === PreferenceLevel.GLOBAL) {
          return 'hidden';
        }
        return '';
      },
    },
  };

  return (
  <Inbox
    applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
    subscriber="YOUR_SUBSCRIBER_ID"
    appearance={appearance}
  />
);
}
```

## Use Preferences outside the Inbox UI

You don’t have to display the Preferences UI inside the default Inbox component. Novu provides two main ways to build a custom preference experience for your subscribers.

### Using the `<Preferences />` component

Use the Preferences component to display the preferences UI anywhere in your application, such as in a dedicated settings page without showing the full Inbox component. This gives you more control over the layout and placement of the preferences experience in your application.

![Preferences component](/images/inbox/preferences-component.png)

```tsx
import { Inbox, Preferences } from '@novu/react';

function InboxPreferences() {
  return (
    <Inbox 
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID">
      <Preferences />
    </Inbox>
  );
}

export default InboxPreferences
```

### Using the `usePreferences` hook

The `usePreferences` hook gives you access to all preferences data for the current subscriber. It returns the full preferences list, loading and error states, filtering options, and a refetch function. This provides the data you need to build a completely custom preferences UI.

<Callout>Refer to the [React](/platform/sdks/react/hooks/use-preferences) and [React Native SDKs](/platform/sdks/react-native/hooks/use-preferences) documentation for full usage details and code examples.</Callout>


# Styling the Inbox component (/platform/inbox/configuration/styling)

Learn how to style the pre built Inbox component

import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

The Novu Inbox component is designed to be fully themeable and adaptable to your application’s visual language. All theming options are exposed through the `appearance` prop, which allows you to apply custom styles at different levels of control from predefined themes to component-level overrides.

The appearance prop supports the following keys:

* `baseTheme`: Apply a predefined theme (for example, light or dark).
* `variables`: Define global styling properties (for example, colors, fonts).
* `elements`: Style individual UI components.
* `icons`: Replace default icons with custom ones.

<Callout>Check out the [Inbox Playground](https://inbox.novu.co) to see how the Inbox looks with common design presets. It showcases pre-styled variants like Notion and Reddit. helpful for seeing what’s possible before you start customizing.</Callout>

### Understand style injection

When rendered, the Inbox component automatically injects its styles into the `<head>` of the HTML document. If the component is rendered inside a shadow DOM, styles are scoped and injected into the shadow root instead.

This ensures that:

* Styles remain encapsulated and do not leak into global stylesheets
* No additional setup is required to manage scoped styling

## Apply base theme

You can apply a predefined visual style to the entire Inbox UI by passing the `baseTheme` object inside the `appearance` prop. This is a quick way to implement a dark mode or any base look and feel without redefining every variable.

### Dark mode

Novu currently provides a built-in dark theme, which you can import from `@novu/react/themes`.

```tsx
import { Inbox } from '@novu/react';
import { dark } from '@novu/react/themes';

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{ baseTheme: dark }}
    />
  );
}

export default Novu;
```

## Define global variables

You can override the default styles in the Inbox component by passing a `variables` object inside the `appearance` prop. This is an efficient way to apply broad visual changes with minimal configuration.

![Define global variables](/images/inbox/variables.png)

```tsx
import { Inbox } from '@novu/react';

const appearance = {
  variables: {
    colorBackground: '#f0f0f0',
    borderRadius: '8px',
  },
};

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}

export default Novu;
```

<Callout>When both `baseTheme` and `variables` are provided, variables always take precedence over the base theme.</Callout>

### List of available variables

<TypeTable
  type={{
  colorBackground: {
    type: 'string',
    description: 'The background color of the inbox component.',
  },
  colorForeground: {
    type: 'string',
    description: 'The primary text color used in the inbox.',
  },
  colorPrimary: {
    type: 'string',
    description: 'The main accent color for interactive elements.',
  },
  colorPrimaryForeground: {
    type: 'string',
    description: 'The text color used on primary-colored elements.',
  },
  colorSecondary: {
    type: 'string',
    description: 'A secondary color for less prominent elements.',
  },
  colorSecondaryForeground: {
    type: 'string',
    description: 'The text color used on secondary-colored elements.',
  },
  colorCounter: {
    type: 'string',
    description: 'The background color of notification counters.',
  },
  colorCounterForeground: {
    type: 'string',
    description: 'The text color used in notification counters.',
  },
  colorNeutral: {
    type: 'string',
    description: 'A neutral color used for borders or backgrounds.',
  },
  colorShadow: {
    type: 'string',
    description: 'The color of shadows applied to elements.',
  },
  fontSize: {
    type: 'string',
    description: 'The base font size for text in the inbox.',
  },
  borderRadius: {
    type: 'string',
    description: 'The border radius applied to various elements.',
  },
}}
/>

## Style the Inbox UI elements

You can define styles for individual UI components within the Inbox UI by passing the `elements` object inside the appearance prop. Each key corresponds to a specific component, and the value can be either a style object or a set of CSS classes.

![Finding element selectors](/images/inbox/styling_02@2x.png)

Here's a list of some available elements that can be styled using the elements object in your appearance configuration:

| Element                      | Key in `appearance.elements`          |
| ---------------------------- | ------------------------------------- |
| Primary action button        | `notificationPrimaryAction__button`   |
| Secondary action button      | `notificationSecondaryAction__button` |
| Notification container       | `notification`                        |
| Subject text                 | `notificationSubject`                 |
| Body text                    | `notificationBody`                    |
| Notification icon/image      | `notificationImage`                   |
| Preferences button           | `preferences__button`                 |
| Date display                 | `notificationDate`                    |
| Archive button               | `notificationArchive__button`         |
| Snooze button                | `notificationSnooze__button`          |
| Unread/read indicator button | `notificationUnread__button`          |
| Notification list container  | `notificationList`                    |
| Schedule container           | `scheduleContainer`                   |
| Schedule header              | `scheduleHeader`                      |
| Schedule body                | `scheduleBody`                        |
| Schedule table               | `scheduleTable`                       |
| Day schedule copy title      | `dayScheduleCopyTitle`                |
| Day schedule copy menu       | `dayScheduleCopy__dropdownContent`    |
| Time select drop-down list   | `timeSelect__dropdownTrigger`         |
| Time select list             | `timeSelect__dropdownContent`         |

<Callout type="info" title="How to find other elements?">
  Any selector that appears before the 🔔 emoji in the Devtools, can be targeted via the elements property in the appearance prop (stripping the `nv-` prefix). You can also use TS autocomplete to find the available elements.
</Callout>

### Using style object

You can pass inline styles to individual elements using the `elements` object in the `appearance` prop. Each element accepts a style object.

```tsx
import { Inbox } from '@novu/react';

const appearance = {
  elements: {
    notificationSubject: {
      color: '#ff0000',
    },
  },
};

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}

export default Novu;
```

### Using Tailwind CSS

You can pass [Tailwind CSS](https://tailwindcss.com/docs/installation/tailwind-cli) classes to specific elements using the elements object within the appearance prop.

```tsx
import { Inbox } from '@novu/react';
 
const appearance = {
  elements: {
    bellIcon: 'p-4 bg-white rounded-full',
    notification: 'bg-white rounded-lg shadow-sm hover:shadow-md hover:bg-gray-50',
  },
};
 
function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}

export default Novu;
```

### Using CSS modules

You can style the Inbox components using [CSS Modules](https://github.com/css-modules/css-modules). First, define the styles in a `.module.css` file:

```css title="styles.module.css"
.bellIcon {
  padding: 1rem;
  background-color: white;
  border-radius: 50%;
}
 
.bellIcon:hover {
  background-color: #f9fafb;
}
 
.notification {
  background-color: white;
  border-radius: 0.5rem;
  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
}
 
.notification:hover {
  background-color: #f9fafb;
}
```

Then, import the CSS module into your component and apply the classes using the `elements` object in the `appearance` prop:

```tsx
import { Inbox } from '@novu/react';
import styles from './styles.module.css';
 
const appearance = {
  elements: {
    bellIcon: styles.bellIcon,
    notification: styles.notification,
  },
};
 
function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}

export default Novu;
```

## Apply styles dynamically using contextual callbacks

You can customize specific parts of the Inbox UI by providing callback functions for certain keys. This function receives contextual information such as unread counts, notification data, or preference details and let you apply styles dynamically based on runtime values from your application.

<Accordions type="single">
  <Accordion title="List of elemets that can be customize using the callback function">
    | Key                                           | Context signature                                                                                                 |
    | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
    | **Bell**                                      |                                                                                                                   |
    | `bellDot`                                     | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `bellIcon`                                    | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `bellContainer`                               | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityHigh__bellContainer`                 | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityMedium__bellContainer`               | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityLow__bellContainer`                  | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `bellSeverityGlow`                            | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityGlowHigh__bellSeverityGlow`          | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityGlowMedium__bellSeverityGlow`        | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | `severityGlowLow__bellSeverityGlow`           | `(context: { unreadCount: { total: number; severity: Record<string, number> } }) => string`                       |
    | **Preferences list (shared)**                 |                                                                                                                   |
    | `preferencesContainer`                        | `(context: { preferences?: Preference[]; groups: Array<{ name: string; preferences: Preference[] }> }) => string` |
    | **Preference**                                |                                                                                                                   |
    | `workflowContainer`                           | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowLabelContainer`                      | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowLabelHeader`                         | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowLabelHeaderContainer`                | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowLabelIcon`                           | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowLabel`                               | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowArrow__icon`                         | `(context: { preference: Preference }) => string`                                                                 |
    | `workflowContainerRight__icon`                | `(context: { preference: Preference }) => string`                                                                 |
    | **Channel**                                   |                                                                                                                   |
    | `channelsContainer`                           | `(context: { preference: Preference }) => string`                                                                 |
    | `channelName`                                 | `(context: { preference: Preference }) => string`                                                                 |
    | **Channel Row (shared)**                      |                                                                                                                   |
    | `channelContainer`                            | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | `channelLabelContainer`                       | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | `channelIconContainer`                        | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | `channelLabel`                                | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | `channelSwitchContainer`                      | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | `channel__icon`                               | `(context: { preference?: Preference; preferenceGroup?: { name: string; preferences: Preference[] } }) => string` |
    | **Preferences Group**                         |                                                                                                                   |
    | `preferencesGroupContainer`                   | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupHeader`                      | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupLabelContainer`              | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupLabelIcon`                   | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupLabel`                       | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupActionsContainer`            | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupActionsContainerRight__icon` | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupBody`                        | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupChannels`                    | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupInfo`                        | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupInfoIcon`                    | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | `preferencesGroupWorkflows`                   | `(context: { preferenceGroup: { name: string; preferences: Preference[] } }) => string`                           |
    | **Notification list**                         |                                                                                                                   |
    | `notificationList`                            | `(context: { notifications: Notification[] }) => string`                                                          |
    | `notificationListContainer`                   | `(context: { notifications: Notification[] }) => string`                                                          |
    | **Notification**                              |                                                                                                                   |
    | `notification`                                | `(context: { notification: Notification }) => string`                                                             |
    | `severityHigh__notification`                  | `(context: { notification: Notification }) => string`                                                             |
    | `severityMedium__notification`                | `(context: { notification: Notification }) => string`                                                             |
    | `severityLow__notification`                   | `(context: { notification: Notification }) => string`                                                             |
    | `notificationBar`                             | `(context: { notification: Notification }) => string`                                                             |
    | `severityHigh__notificationBar`               | `(context: { notification: Notification }) => string`                                                             |
    | `severityMedium__notificationBar`             | `(context: { notification: Notification }) => string`                                                             |
    | `severityLow__notificationBar`                | `(context: { notification: Notification }) => string`                                                             |
    | `notificationImageLoadingFallback`            | `(context: { notification: Notification }) => string`                                                             |
    | `notificationImage`                           | `(context: { notification: Notification }) => string`                                                             |
    | `notificationContent`                         | `(context: { notification: Notification }) => string`                                                             |
    | `notificationTextContainer`                   | `(context: { notification: Notification }) => string`                                                             |
    | `notificationSubject`                         | `(context: { notification: Notification }) => string`                                                             |
    | `notificationBody`                            | `(context: { notification: Notification }) => string`                                                             |
    | `notificationDefaultActions`                  | `(context: { notification: Notification }) => string`                                                             |
    | `notificationCustomActions`                   | `(context: { notification: Notification }) => string`                                                             |
    | `notificationPrimaryAction__button`           | `(context: { notification: Notification }) => string`                                                             |
    | `notificationSecondaryAction__button`         | `(context: { notification: Notification }) => string`                                                             |
    | `notificationDate`                            | `(context: { notification: Notification }) => string`                                                             |
    | `notificationDeliveredAt__badge`              | `(context: { notification: Notification }) => string`                                                             |
    | `notificationDeliveredAt__icon`               | `(context: { notification: Notification }) => string`                                                             |
    | `notificationSnoozedUntil__icon`              | `(context: { notification: Notification }) => string`                                                             |
    | `notificationDot`                             | `(context: { notification: Notification }) => string`                                                             |
    | **Schedule**                                  |                                                                                                                   |
    | `scheduleContainer`                           | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleHeader`                              | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleLabelContainer`                      | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleLabelIcon`                           | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleLabel`                               | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleActionsContainer`                    | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleActionsContainerRight`               | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleBody`                                | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleDescription`                         | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleTable`                               | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleTableHeader`                         | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleHeaderColumn`                        | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleTableBody`                           | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleBodyRow`                             | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleBodyColumn`                          | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleInfoContainer`                       | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleInfoIcon`                            | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `scheduleInfo`                                | `(context: { schedule?: Schedule }) => string`                                                                    |
    | **Day Schedule Copy**                         |                                                                                                                   |
    | `dayScheduleCopyTitle`                        | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `dayScheduleCopyIcon`                         | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `dayScheduleCopySelectAll`                    | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `dayScheduleCopyDay`                          | `(context: { schedule?: Schedule }) => string`                                                                    |
    | `dayScheduleCopyFooterContainer`              | `(context: { schedule?: Schedule }) => string`                                                                    |
  </Accordion>
</Accordions>

Here are some examples:

### Style the bell icon based on unread count

You can change the bell icon color gradient based on the total number of unread notifications. The callback receives an `unreadCount` object, which is then used in the conditional logic.

```tsx
import { Inbox } from '@novu/react';

export default function Novu() {

  const appearance = {
    elements: {
      bellIcon: ({ unreadCount }) => {
        if (unreadCount.total > 1) {
          return '[--bell-gradient-start:var(--color-red-500)] [--bell-gradient-end:var(--color-red-500)]';
        }
        return unreadCount.total > 10
          ? '[--bell-gradient-start:var(--color-yellow-500)] [--bell-gradient-end:var(--color-yellow-500)]'
          : '[--bell-gradient-start:var(--color-gray-500)] [--bell-gradient-end:var(--color-gray-500)]';
      },
    },
  };

  return (
  <Inbox
    applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
    subscriber="YOUR_SUBSCRIBER_ID"
    appearance={appearance}
  />
);
}
```

### Style notifications based on payload data

You can style individual notifications based on custom data in their payload. In the example below, the notification's background color is changed if a specific field (foo) exists in the notification's data object.

```tsx
import { Inbox } from '@novu/react';

export default function Novu() {

    const appearance = {
    elements: {
      notification: ({ notification }) => {
        if (notification.data?.foo) {
          return 'bg-green-200';
        }

        return '';
      },
    },
  };

  return (
  <Inbox
    applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
    subscriber="YOUR_SUBSCRIBER_ID"
    appearance={appearance}
  />
);
}
```

## Style notifications by severity

Notification severity comes with default visual styles, but you can fully customize how notifications look for each severity level using the `appearance` prop.

![Notification severity in the inbox](/images/inbox/inbox-notification-severity.png)

<Callout>By default, the bell icon takes the color of the highest severity unread notification.</Callout>
Each severity level exposes selectors you can target through the `variables` and `elements` objects to apply custom styling.

### Customizing severity colors

You can override the default severity colors by setting new CSS custom properties in the `appearance.variables` object. Updating these variables automatically changes both the notification color and the bell icon color.

| Prop                  | Description               |
| --------------------- | ------------------------- |
| `colorSeverityHigh`   | Color for high severity   |
| `colorSeverityMedium` | Color for medium severity |
| `colorSeverityLow`    | Color for low severity    |

```tsx
const appearance = {
  variables: {
    colorSeverityHigh: 'green',
    colorSeverityMedium: 'blue',
    colorSeverityLow: 'yellow',
  }
};
```

### Customizing severity elements

You can apply specific styles to individual components using keys in the `appearance.elements` object. This lets you target components conditionally based on their severity state.

```tsx
const appearance = {
  elements: {
    severityHigh__notificationBar: {
      backgroundColor: 'red',
    },
  },
};
```

This table lists severity element keys:

| Elements key                           | Description                                                                |
| -------------------------------------- | -------------------------------------------------------------------------- |
| `severityHigh__bellContainer`          | Styles the bell container for high severity                                |
| `severityMedium__bellContainer`        | Styles the bell container for medium severity                              |
| `severityLow__bellContainer`           | Styles the bell container for low severity                                 |
| `bellSeverityGlow`                     | Base style for the severity glow around the bell                           |
| `severityGlowHigh__bellSeverityGlow`   | Glow style for high severity                                               |
| `severityGlowMedium__bellSeverityGlow` | Glow style for medium severity                                             |
| `severityGlowLow__bellSeverityGlow`    | Glow style for low severity                                                |
| `severityHigh__notification`           | Styles individual high severity notifications                              |
| `severityMedium__notification`         | Styles individual medium severity notifications                            |
| `severityLow__notification`            | Styles individual low severity notifications                               |
| `notificationBar`                      | Base style for the vertical notification bar on the left of a notification |
| `severityHigh__notificationBar`        | Styles the notification bar for high severity                              |
| `severityMedium__notificationBar`      | Styles the notification bar for medium severity                            |
| `severityLow__notificationBar`         | Styles the notification bar for low severity                               |

## Responsive Inbox using CSS media queries

In mobile and smaller device, use `popoverContent` element and apply custom CSS class on it. Specify CSS media queries on this class and add this class in global CSS file so that it takes effect. In below example, we have applied media queries on the `novu-popover-content` class and added it in global CSS file.

```tsx title="ResponsiveInbox.tsx"
import { Inbox } from '@novu/react';

const ResponsiveInbox = () => {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{
        elements: {
          popoverContent: "novu-popover-content",
        },
      }}
    />
  );
};

export default ResponsiveInbox;
```

```css title="global.css"
.novu-popover-content {
  max-width: 500px;
}

@media (max-width: 768px) {
  .novu-popover-content {
    max-width: 350px;
  }
}

@media (max-width: 480px) {
  .novu-popover-content {
    max-width: 250px;
  }
}

@media (max-width: 320px) {
  .novu-popover-content {
    max-width: 200px;
  }
}
```


# Inbox Tabs Configuration (/platform/inbox/configuration/tabs)

Learn what tabs are and how to filter multiple tabs in the Novu Inbox component.

In the Inbox components, you can use Tabs to organize **Inbox** notifications into separate sections, creating a cleaner, more organized experience for your subscribers. Each tab displays a subset of in-app notifications based on defined rules, making it easier to surface important notifications.

![tabs](/images/inbox/tabs.gif)

## Group notifications into tabs

Each tab is defined using the `tabs` prop of the Inbox component. Every tab object includes the following properties:

* **`label`**: A string that defines the tab’s title, displayed as the visible label in the UI
* **`filter`**: An object that defines which notifications are included in a particular tab.

### Using tags

[Tags](/platform/workflow/configure-workflow#tags) can be assigned to any workflow in the Novu workflow editor. These tags can then be used in the filter object to group notifications from one or more workflows under the same tab.

For example, assign a **promotions** tag to marketing workflows or **security** and **alert** tags to security workflows to group their notifications under dedicated tabs. To show all the notifications in a tab, pass an empty array to the tags property. If multiple tags are provided, Novu evaluates them using `OR` logic, meaning a notification is included if it contains at least one of the specified tags.

```tsx
import { Inbox } from '@novu/react';

function InboxTabs() {

  const tabs = [
    {
      label: 'All Notifications',
      filter: { tags: [] },
    },
    {
      label: 'Promotions',
      filter: { tags: ['promotions'] },
    },
    {
      label: 'Security Alerts',
      filter: { tags: ['security', 'alert'] }
    },
  ];
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}

export default InboxTabs;
```

### Using the data object

The [data object](/platform/inbox/configuration/data-object) can be included in every in-app notification in the in-app editor editor. This object holds custom key-value pairs, which you can use to filter notifications into specific tabs.

For example, use `{ priority: "high" }` to group all high-priority notifications under a dedicated "High Priority" tab.

```tsx
import { Inbox } from '@novu/react';

function InboxTabs() {

  const tabs = [
    {
      label: 'High Priority',
      filter: {
        data: { priority: 'high' },
      },
    },
  ];
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}

export default InboxTabs;
```

### Using tags and data object

You can combine tags and the data object in the same filter to create more specific tabs tailored to your use case.

```tsx
import { Inbox } from '@novu/react';

function InboxTabs() {

  const tabs = [
    {
      label: 'High Priority',
      filter: { 
        tags: ['alert'],
        data: { priority: 'high' }
      },
    },
  ];
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}

export default InboxTabs;
```

### Using notification severity

After setting [workflow notification severity in the dashboard](/platform/workflow/configure-workflow#notification-severity), you can use that severity level to create dedicated tabs in your notification inbox. This lets you filter notifications based on their importance.

To achieve this, add the severity key to the filter object for any tab in your Inbox component. The severity property can accept a single severity level or an array of levels.

```tsx
import { Inbox, SeverityLevelEnum } from '@novu/react';

export default function InboxWithFilters() {

  const tabs = [
    {
      label: 'All Notifications',
      filter: { tags: [] },
    },
    {
      label: 'Security',
      filter: {
        severity: SeverityLevelEnum.HIGH,
      },
    },
  ];
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}
```

## Show notification count for each tab

The `useCounts` hook provides a way to fetch notification counts for each tab, this include the unread, unseen, and total counts. You can use these to display notification count for each tab in the Inbox component.

<Callout>Refer to the [React](/platform/sdks/react/hooks/use-counts) and [React Native SDKs](/platform/sdks/react-native/hooks/use-counts) documentation to learn more about the `useCounts` hook.</Callout>


# Schedule Notifications (/platform/inbox/features/schedule)

Learn how subscribers can use the Schedule feature in the Inbox component to control when they receive notifications from email, SMS and push channels.

The **Schedule** feature in the <Method href="/platform/inbox">{`<Inbox />`}</Method> lets subscribers control when they want to receive notifications from email, SMS, and push channels.

By defining their hours of availability from the <Method href="/platform/inbox">{`<Inbox />`}</Method> UI, subscribers can automatically skip notifications outside of their chosen time range.

<Callout>If you don't need the Schedule feature, you can hide it from the Inbox component UI using the appearance prop. To learn more, refer to the documentation on [styling the Inbox UI elements](/platform/inbox/configuration/styling#style-the-inbox-ui-elements).</Callout>

![Schedule](/images/inbox/schedule.png)

<Callout>In-app notifications and notifications from critical workflows are never paused and will always be delivered, regardless of schedule settings.</Callout>

## How scheduling works

The schedule functionality is based on a clear set of rules controlled by the subscriber within the <Method href="/platform/inbox">{`<Inbox />`}</Method>. When a subscriber enables their schedule, they can then manage their availability for each day of the week.

### Daily availability

For any day that the main schedule is active, there will be two possible states:

* **Day is enabled**: If a day is toggled on, then the subscriber must set a time range. Notifications will only be delivered within these hours.

* **Day is disabled**: If a day is toggled off, then the subscriber will not receive any non-critical notifications for that entire day.

### Automatic timezone handling

The schedule operates in the subscriber's local timezone, detected automatically from their system settings. There is no need for manual configuration.

For example, if a subscriber in Warsaw sets their schedule from 9:00 AM to 5:00 PM, they will receive notifications during those hours in Central European Time (CET).

## Manage Schedule

The schedule UI in the preferences section is designed to be intuitive, giving subscribers several tools to quickly configure their availability.

You can access **Schedule** from the **Preferences** section of the <Method href="/platform/inbox">{`<Inbox />`}</Method> UI. By default, scheduling is turned off, and all notifications will be delivered normally.

![Manage schedule](/images/inbox/inbox-schedule.png)

### Enable the main schedule

The entire feature is controlled by a main schedule toggle. When a subscriber turns this on, they can begin configuring individual days. When it's off, all other settings will be inactive, and notifications will be delivered normally.

### Setting daily availability

For each day of the week, the subscriber can:

* Use the toggle next to the day's name to activate or deactivate it.
* If activated, use the time-selector menus to set a "from" and "to" time. The time pickers are set to 30-minute increments for ease of use.

### Edit or remove schedules

Existing availability can be adjusted at any time. Subscribers can:

* Change the start and end times for a day.
* Re-enable a previously disabled day.
* Clear a schedule entirely to return to unrestricted delivery.

### Copying times to multiple days

To make setup faster, subscribers can configure the time for one day and apply it to others in a few clicks:

1. Set the desired time range for a single day.
2. Click **Copy times to...** associated with that day.
3. In the menu that appears, select the other days of the week to apply this schedule to.
4. Click "Apply." The selected days will automatically be enabled and updated with the new time range.

![Copying times to multiple days](/images/inbox/schedule.gif)

### Automatic saving

All changes made in the schedule interface will be saved automatically in the background. The UI updates optimistically, providing a seamless experience without requiring the subscriber to click save.

## Set default schedule for Subscribers

You can provide a default schedule for your subscribers by passing the `defaultSchedule` prop to the <Method href="/platform/inbox">{`<Inbox />`}</Method>. This is useful for pre-configuring a recommended schedule that your subscribers can then customize.

This default schedule only applies if a subscriber has not yet configured their own schedule. Once they make any changes, their custom schedule takes precedence.

```tsx
import { Inbox } from '@novu/react';

function InboxWithDefaultSchedule() {
  return (
      <Inbox
        applicationIdentifier="YOUR_APP_IDENTIFIER"
        subscriberId="YOUR_SUBSCRIBER_ID"
        defaultSchedule={{
          isEnabled: true,
          weeklySchedule: {
            tuesday: {
              isEnabled: true,
              hours: [{start: '09:00 AM', end: '07:00 PM'}]
            }
          }
        }}
      />
  );
}

export default InboxWithDefaultSchedule;
```


# Snooze Notifications (/platform/inbox/features/snooze)

Allow users to temporarily hide notifications and resurface them later using built-in snooze functionality in the Inbox component.

The `<Inbox />` component includes built-in support for snoozing notifications, which can be used to temporarily dismiss notifications and have them reappear at a more convenient time.

![Snooze icon on the inbox notification](/images/inbox/snooze.png)

<Callout type="info">Snooze is supported in client-side SDKs starting from version 3.3.0 and is only available for cloud workspaces.</Callout>

## How snooze works

When a subscriber snoozes a notification:

* It is temporarily removed from the general list.
* It appears in the Snoozed tab.
  ![Snooze tab](/images/inbox/snooze-tab.png)
* It reappears in the general list after the specified time elapses.

During the snooze period, the notification cannot be marked as read, unread, or archived. All of these behaviors are handled automatically by the Inbox component.

## How to snooze a notification

All dates and times are interpreted in your subscriber's local timezone. They can snooze a notification directly from the Inbox using one of the following options:

* Preset options:
  * An hour from now
  * Tomorrow
* Custom date and time:
  * A built-in date and time picker allows users to select a specific future time.

![Snooze a notification](/images/inbox/snooze-notification.png)

The minimium snooze time must be at least 3 minutes in the future. While the maximum duration a notification can be snoozed depends on your cloud workspace plan:

* **Free**: Up to 24 hours per notification
* **Trial**: Up to 90 days during the 14-day trial, same as Pro
* **Pro / Team**: Up to 90 days
* **Enterprise**: Defaults to 90 days, extendable on request

While the Inbox component handles snoozing automatically, the [JavaScript SDK](/platform/sdks/javascript#methods) also exposes `.snooze()` and `.unsnooze()` methods on the notification object to build custom snooze functionality.

This lets you create custom UI elements or workflows that trigger snooze actions outside of the default menu.

## Managing snoozed notifications

The Inbox component includes a dedicated Snoozed tab that automatically displays notifications scheduled to reappear later. From this tab, users can review all snoozed notifications and take further actions as needed.

Users can unsnooze a notification at any time, which immediately returns it to the All tab. Once unsnoozed, the notification regains its standard behavior. It can be marked as read, unread, or archived like any other item.

| Action                             | Result                                                                                                                                                     |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manual unsnooze                    | Restores the notification exactly as it was: same tab, same read/unread state. If it was read before snoozing, it re-enters the All tab still marked read. |
| Automatic unsnooze (timer expires) | Re-delivers the notification to All as a new, unread item with an updated delivery timestamp.                                                              |

This logic is built into the component and does not require any additional configuration. Notifications automatically reappear in the All tab once their snooze duration elapses.

## Hiding snooze button

If you don't need the Snooze feature, you can hide it from the Inbox component UI using the [appearance](/platform/inbox/configuration/styling#style-the-inbox-ui-elements) prop. The example below hides the snooze button and snoozed list item in the dropdown menu.

```tsx
import { Inbox } from '@novu/react';


export const InboxWithSnoozeHidden = () => {
  return (
    <Inbox
      applicationIdentifier={"APPLICATION_IDENTIFIER"}
      subscriber={{
        subscriberId: "SUBSCRIBER_ID"
      }}
      appearance={{
        elements: {
          notificationSnooze__button: "hidden",
          inboxStatus__dropdownItem: "[&:nth-child(3)]:hidden",
        },
      }}
    />
  )
}
```


# Adding Chat Channel (/platform/integrations/chat/adding-chat)

Learn how to add the Chat channel to your application

import { Card } from 'fumadocs-ui/components/card';

import { CodeIcon } from '@/components/icons/overview';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Chat channels allow you to deliver instant, contextual messages to your subscribers via their preferred chat platform and apps.

<Steps>
  <Step title="Enable Chat Channel in Novu Dashboard">
    <Callout type="info">
      The Chat channel is not enabled by default. To use it, configure a provider like Slack, Discord,
      or others.
    </Callout>

    * Go to the Novu Dashboard and click **"Integrations"** on the left sidebar
    * Click **"Add a provider"**
    * Locate the **Chat** channel and select the provider you want to use and click **"Next"**
    * Select for which environment you want to add the Provider
    * (Optional) Add Conditions to activate the provider only under certain conditions, **useful for tenant-based providers**
    * Click **"Create"**
    * Add your Chat provider credentials:

    <Callout type="info">
      Each chat provider requires different type of credentials. There are few providers which does
      not require any credentials example: `Discord`
    </Callout>

    * Provider-specific credentials such as API key / Auth token, Client ID, Client Secret, or password
    * Save the configuration by clicking **"Update"**
  </Step>

  <Step title="Setup workflow with chat channel in Novu Dashboard">
    * Go to the Novu Dashboard and click **"Workflows"** on the left sidebar
    * Click the **"Add a Workflow"** button
    * Add a step and select **"Chat"** as the channel
    * Configure the Chat content:
      * Message body (e.g., `{{subscriber.firstName}}, your order {{orderId}} has shipped.`)
      * Dynamic placeholders for personalized content
    * Optionally, set fallback channels to ensure reliable delivery if Chat fails
  </Step>

  <Step title="Add a workflow Trigger to your backend">
    Novu's server-side SDKs make integrating Novu's REST APIs straightforward, letting you focus on implementing workflows without dealing with repetitive code.

    <Card title="Server-side SDKs" icon={<CodeIcon />} href="/platform/sdks/server" />
  </Step>

  <Step title="Test and Verify Chat Channel">
    Ensure your Chat configuration is working correctly by testing the setup.

    * Go to the Novu Dashboard, navigate to the **"Workflows"** section, and locate your configured workflow
    * Click **"Test Workflow"** and provide sample data, such as a phone number or dynamic variables
    * Verify delivery in the Novu Logs or your Chat provider's dashboard
  </Step>
</Steps>

## Sending chat message

<Steps>
  <Step title="Add Chat Provider Integration">
    Add a chat provider integration to your Novu account from the integration store. Enter credentials if required and save the integration. Follow corresponding provider documentation to get the required credentials.
  </Step>

  <Step title="Create Subscriber">
    Create a new subscriber.

    <Callout type="info">
      This step can be skipped if you already have a subscriber. You can use the `subscriberId` of an existing subscriber.
    </Callout>
  </Step>

  <Step title="Update Subscriber Credentials">
    [Update](/api-reference/subscribers/update-provider-credentials) the
    subscriber credential `webhookUrl` for this provider and integration.
  </Step>

  <Step title="Configure Workflow">
    Create a new worklow or use an existing workflow. Add chat channel and write content for the
    message.
  </Step>

  <Step title="Trigger Workflow">
    Trigger this workflow to above `subscriberId` using trigger identifier.
  </Step>

  <Step title="Verify Message">
    Check the chat provider if message is received.
  </Step>
</Steps>


# Chat Integrations (/platform/integrations/chat)

Configure and manage chat providers like Slack, Microsoft Teams, WhatsApp, and Discord with Novu's notification infrastructure.

The Chat channel delivers messages to your subscribers via their preferred chat platforms and application.

## Messaging platforms vs. Messaging applications

* **Messaging platforms**: Ideal for structured, workplace communication. Use these to notify teams or users in collaborative environments. Examples: Slack, Teams
* **Messaging apps**: Best for consumer-facing messaging. Engage users directly through personal or group chats. Examples: WhatsApp, Telegram, Discord

## How chat delivery works in Novu

Here’s the typical flow for sending a chat notification through Novu:

<Steps>
  <Step>
    ### Add a chat provider

    Start by adding a chat provider in the integration store on your Novu dashboard.\
    You can connect one or more integrations for different or even the same providers, for example, multiple Slack workspaces.

    To learn how to add a chat provider, refer to [the setup guide](/platform/integrations/chat#supported-providers) for that provider.
  </Step>

  <Step>
    ### Add the chat channel to your workflow

    Next, include a Chat step in your workflow.\
    This step defines when and how a chat message should be sent as part of your notification workflow.
  </Step>

  <Step>
    ### Define the chat content

    Within the Chat step editor, write the message body.\
    The editor supports dynamic data for personalized and contextual messages.
  </Step>

  <Step>
    ### Store subscriber credentials

    Each subscriber must have valid chat credentials, such as a `webhookUrl` or unique identifier, to receive chat notifications.\
    You can store or update these credentials using the Novu dashboard, API, or SDKs.
  </Step>

  <Step>
    ### Trigger the workflow

    Trigger the workflow using your application code. Novu automatically:

    * Resolves the subscriber.
    * Retrieves the correct credentials, for example, the `webhookUrl`.
    * Selects the appropriate provider.
    * Renders the message.
    * Delivers it to the chat platform.
  </Step>
</Steps>

## Configuring chat providers

When you add a chat provider in the Integration Store, you'll configure credentials specific to that provider.

### Provider authentication

You may need to provide credentials specific to your chat provider, such as an API key, Client ID, or Client Secret. However, some providers, like Discord, may not require any global credentials to be set in the Integration Store.

Each provider has different requirements.

<Callout type="info"> For detailed setup guides for each provider integration, refer to the supported chat providers list at the end of this page .</Callout>

## How to manages Chat credentials

The chat channel works by storing specific credentials for each subscriber. This credential is typically a `webhookUrl` that tells Novu where to send a message for that specific subscriber.

Before triggering a chat notification, you must update the subscriber with this `webhookUrl`.

### Storing subscriber credentials

Use the `subscribers.credentials.update` method to store the `webhookUrl` for a specific subscriber and provider.

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.Discord,
        credentials: {
          webhookUrl: "<WEBHOOK_URL>",
        },
        integrationIdentifier: "discord-MnGLxp8uy",
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "slack",
      "credentials": {
          "webhookUrl": "<WEBHOOK_URL>"
      },
      "integrationIdentifier": "slack-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

## Supported providers

Here are the chat providers that are currently supported by Novu. Select any provider to see its detailed setup guide.

<Cards>
  <Card title="Discord" href="/platform/integrations/chat/discord"> Learn how to use the Discord provider to send chat notifications using Novu. </Card>
  <Card title="Mattermost" href="/platform/integrations/chat/mattermost"> Learn how to use the Mattermost provider to send chat notifications using Novu.</Card>
  <Card title="Microsoft Teams" href="/platform/integrations/chat/ms-teams"> Learn how to use the Microsoft Teams provider to send chat notifications using Novu.</Card>
  <Card title="Slack" href="/platform/integrations/chat/slack"> Learn how to use the Slack provider to send chat notifications using Novu.</Card>
  <Card title="WhatsApp Business" href="/platform/integrations/chat/whats-app"> Learn how to use the WhatsApp Business provider to send chat notifications using Novu.</Card>
  <Card title="Zulip" href="/platform/integrations/chat/zulip"> Learn how to use the Zulip provider to send chat notifications using Novu.</Card>
</Cards>


# Adding Email Channel (/platform/integrations/email/adding-email)

Learn how to add the Email channel to your application

import { Card } from 'fumadocs-ui/components/card';

import { CodeIcon } from '@/components/icons/overview';

The Email channel enables you to send email notifications to users for events like password resets, onboarding, or system alerts.

<Steps>
  <Step title="Enable Email Channel in Novu Dashboard">
    <Callout type="info">
      By default, the Email channel is enabled and configured with Novu's default provider. If it is
      disabled, notifications sent to this channel will not be processed.
    </Callout>

    1. Go to the Novu Dashboard and click **"Integrations"** on the left sidebar
    2. Click **"Add a provider"**
    3. Locate the **Email** channel and select the provider you want to use and click **"Next"**
    4. Select for which environment you want to add the Provider
    5. (Optional) Add Conditions to activate the provider only under certain conditions, **useful for tenant-based providers**
    6. Click **"Create"**
    7. Add your Email provider credentials:
       * **From**: Displayed as the sender of the email (ensure compliance with local regulations)
       * **Sender Name**: The name that will be used to send the email
       * Provider-specific credentials such as API key / Auth token, Account SID, username, or password
    8. Save the configuration by clicking **"Update"**
  </Step>

  <Step title="Setup workflow with email channel in Novu Dashboard">
    1. Go to the Novu Dashboard and click **"Workflows"** on the left sidebar.
    2. Click the **"Add a Workflow"** button.
    3. Add a step and select **"Email"** as the channel.
    4. Configure the email content, such as subject, message body, and any dynamic variables.
  </Step>

  <Step title="Add a workflow trigger to your backend">
    Novu's server-side SDKs make integrating Novu's REST APIs straightforward, letting you focus on implementing workflows without dealing with repetitive code.

    <Card title="Server-side SDKs" icon={<CodeIcon />} href="/platform/sdks/server" />
  </Step>

  <Step title="Test and Verify Email Channel">
    Ensure your configuration is working by sending a test notification.

    1. Go to the Novu Dashboard, navigate to the "Workflows" section, and locate your configured workflow.
    2. Click **"Test Workflow"** and provide sample data (e.g., user ID, email address).
    3. Verify the email delivery in the Novu Logs or your email provider dashboard.
  </Step>
</Steps>


# E-mail Providers Integration (/platform/integrations/email)

Learn how to configure the Email channel

import { Step, Steps } from 'fumadocs-ui/components/steps';

Email providers are the services that deliver notifications to your subscribers’ email. You must set up each provider individually in the Novu dashboard to enable delivery through the Email channel.

Novu provides a unified integration layer that connects your workflows to these email providers. Once you’ve added your integrations, Novu handles routing and delivery automatically, sending each email through the correct provider without requiring additional setup. This allows you to manage multiple email integrations and switch providers when needed.

## Key features

* **Multi-provider support**: Integrate any major provider like SendGrid, SES, or Mailgun.
* **Failover mechanisms**: Automatically retry with a backup provider to ensure reliability.
* **Activity tracking**: Track delivery status, open rates, and more in the Novu dashboard.

## How email works in Novu

Here’s the typical flow for sending an email notification through Novu:

<Steps>
  <Step>
    ### Add an email provider

    Start by adding an email provider in the **Integration Store** on your Novu dashboard. You can connect one or more integrations for different or the same providers.

    To learn how to add an email provider, refer to the guide for the [supported providers](/platform/integrations/email#supported-providers).
  </Step>

  <Step>
    ### Add the Email channel to your workflow

    Next, include an Email step in a workflow. This step defines when and how an email should be sent as part of your notification workflow.
  </Step>

  <Step>
    ### Define the email content

    Within the Email step, you can design your message using the built-in visual editor or code editor. Novu supports dynamic data from your payload, so each message can be personalized for the subscriber.
  </Step>

  <Step>
    ### Store subscriber email addresses

    Novu automatically sends the notification to the email address stored on the subscriber's profile. This profile is update either using the Novu dashboard or API.
  </Step>

  <Step>
    ### Trigger the workflow

    [Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu. Novu automatically:

    1. Resolves the subscriber.
    2. Selects the correct provider.
    3. Renders the email template.
    4. Delivers the message through the configured email integration.
  </Step>
</Steps>

<Callout type="info">Learn how to [build email template](/platform/workflow/add-notification-content/channels-template-editors#email-template-editor) using the block editor, custom HTML, and dynamic variables.</Callout>

## Configuring email providers

When you add an email provider in the **Integration Store**, you configure settings that are common to all email providers, as well as credentials specific to that provider.

### Default sender settings

Novu asks for two default settings for any email provider you connect:

* **Sender name**: The name that appears in the recipient's "From" field.
* **From email address**: The email address the notification is sent from. For some email providers, including SendGrid, you must authenticate the **From email address** to make sure you're sending an email from an authorized address.

These are the default values used for every email sent via this integration. You can override them when triggering a workflow if needed.

### Provider authentication

You must provide credentials specific to your email provider for a successful integration.

<Callout type="info">For detailed setup guides for each integration, refer to the [Supported Providers](/platform/integrations/email#supported-providers) list at the bottom of this page.</Callout>

## Advanced email features

You can control advanced email features at runtime by passing data in your trigger call. This lets you send attachments, override default settings, or target a specific provider for a single notification.

### Sending attachments

You can send attachments by passing an `attachments` array in the `payload` of your trigger. The attachment file can be provided as a `buffer` or a `base64` encoded string.

There is a total limit of 20MB for all attachments included in an email.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/api';  

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      payload: { 
        // [!code ++:14]
        attachments: [
          {
            // buffer format
            file: fs.readFileSync(__dirname + '/data/novu.jpeg'),
            name: 'novu.jpeg',
            mime: 'image/jpeg',
          },
          {
            // base64 format
            file: 'iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC',
            name: 'blue.png',
            mime: 'image/png',
          }
        ],
      },
    });
    ```
  </Tab>

  <Tab value="cURL">
    Use [https://eu.api.novu.co/v1/events/trigger](https://eu.api.novu.co/v1/events/trigger) api endpoint for the EU region.

    ```bash
    curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <SECRET_KEY>' \
    --data-raw '{
        "name": "workflow_trigger_identifier",
        "to": [
            {
                "subscriberId": "subscriber_id",
                "email": "email_address"
            }
        ],
        "payload": {
            "attachments": [
                {
                    "file": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                    "name": "transparent.png",
                    "mime": "image/png"
                },
                {
                    "file": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                    "name": "blue.png",
                    "mime": "image/png"
                }
            ]
        }
    }'
    ```
  </Tab>
</Tabs>

### Sending email overrides

You can override the email settings for a single trigger by passing an `overrides` object. This lets you override the following fields:

* `bcc`
* `cc`
* `from` address
* `replyTo`
* `senderName`
* `text`
* `to` address

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({    
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      overrides: { // [!code ++:11]
        email: {
          to: ['to@novu.co'],
          from: 'from@novu.co',
          senderName: 'Novu Team',
          text: 'text version of email using overrides',
          replyTo: 'no-reply@novu.co',
          cc: ['1@novu.co'],
          bcc: ['2@novu.co'],
        },
      },
    });
    ```
  </Tab>
</Tabs>

<Callout type="info">Note that Novu merges the `to` field in the email overrides with the subscriber email. It does *not* replace it.</Callout>

### Targeting a specific provider

By default, Novu uses your primary email provider. However, if you want to bypass this and force a specific, active integration for a trigger, use the `integrationIdentifier`.

This is useful if you have multiple active integrations for different purposes. For example, you might have one integration for transactional emails and one for marketing emails. You can find the `integrationIdentifier` for each provider in provider page in the **Integration Store**.

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      overrides: {
        email: {
          integrationIdentifier: "brevo-abcdef" // [!code ++]
        },
      },
    });
    ```
  </Tab>
</Tabs>

### Overriding email layout

Each Novu environment can have multiple layouts. Each email step in the workflow can have a layout assigned to it. Overriding the email layout allows you to dynamically override layout settings at trigger time, providing flexible layout management per workflow/channel or per step execution.

**`layoutId` values and its behavior:**

| Value                      | Behavior                                                                |
| -------------------------- | ----------------------------------------------------------------------- |
| "layout-identifier"        | Uses layout with this identifier                                        |
| "507f1f77bcf86cd799439011" | Uses layout with this MongoDB ObjectId                                  |
| null                       | Explicitly no layout - renders email without any layout                 |
| undefined                  | Default behavior - uses step's configured layout or environment default |
| Not specified              | Same as undefined                                                       |

**Precedence rules:**

1. **Step-level override** - **Highest priority**
2. **Workflow-level/channels-level override**
3. **Step configuration** (configured in workflow editor)
4. **Environment default layout** - **Lowest priority**

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      payload: {},
      overrides: {
        // Channel-level layouts
        channels: {
    	    email: {
    		    layoutId: 'black-friday-layout',
    	    },
    	  },
        steps: {
          'welcome-email': {
            // This email step uses a specific welcome layout
            layoutId: 'welcome-v2'
          },
          'promotional-email': {
            // This email uses the channel-level layout (black-friday-layout)
            // No layoutId specified = inherits from channel level
          },
          'transactional-receipt': {
            // This email explicitly uses no layout (plain email)
            layoutId: null
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

### Sending provider specific extra fields

You can send provider specific extra fields by passing a `_passthrough` object in the `overrides` object. This lets you send extra fields to the provider SDK. Novu internally uses provider's official SDK to send the email. Each provider has its own supported extra fields. Those extra fields are not validated by Novu and are passed directly to the provider SDK. There are three type of fields that you can send: `body`, `headers`, and `query`. Below is an example of sending `tags` supported by [Resend provider](/platform/integrations/email/resend).

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      payload: {},
      overrides: {
        // [!code ++:20]
        providers: {
          resend: {
            _passthrough: {
              body: {
                tags: [
                  {
                    name: "category",
                    value: "confirm_email"
                  }
                ] 
              },
              headers: {
                "X-Custom-Header": "custom-header-value"
              },
              query: {
                "queryParam": "queryValue"
              }
            }
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

## Unsubscribe email

By default, Novu does not add any unsubscribe links to the email. Few providers add unsubscribe links to the email by default. If you are looking to add custom unsubscribe links to the email, follow below steps:

* Add `{{payload.unsubscribeEmail}}` field in the email editor.
* Build custom unsubscribe link in your application using subscriberId workflowId. Make sure this link is secured with tokens to prevent abuse.
* Use Novu [preference api](/api-reference/subscribers/update-subscriber-preferences) to update the email channel preferences for this workflow to `false`.
* Optionally, you can build a custom unsubscribe page and add the link of that page for unsubscribe email option.
* Send the value of `unsubscribeEmail` variable in the payload while triggering the workflow.
* Novu will add the unsubscribe link to the email and end user will be able to unsubscribe from the email by clicking on the link.

## Supported providers

Here are the email providers that are currently supported by Novu. Select any provider to see its detailed setup guide.

<Cards>
  <Card title="SendGrid" href="/platform/integrations/email/sendgrid"> Learn how to use the SendGrid provider to send emails using Novu.</Card>
  <Card title="Amazon SES" href="/platform/integrations/email/amazon-ses"> Learn how to use the Amazon SES provider to send emails using Novu.</Card>
  <Card title="Postmark" href="/platform/integrations/email/postmark"> Learn how to use the Postmark provider to send emails using Novu.</Card>
  <Card title="Resend" href="/platform/integrations/email/resend"> Learn how to use the Resend provider to send emails using Novu.</Card>
  <Card title="Brevo" href="/platform/integrations/email/brevo"> Learn how to use the Brevo provider to send emails using Novu.</Card>
  <Card title="Mailgun" href="/platform/integrations/email/mailgun"> Learn how to use the Mailgun provider to send emails using Novu.</Card>
  <Card title="Mailjet" href="/platform/integrations/email/mailjet"> Learn how to use the Mailjet provider to send emails using Novu.</Card>
  <Card title="Braze" href="/platform/integrations/email/braze"> Learn how to use the Braze provider to send emails using Novu.</Card>
  <Card title="Infobip" href="/platform/integrations/email/infobip"> Learn how to use the Infobip provider to send emails using Novu.</Card>
  <Card title="MailerSend" href="/platform/integrations/email/mailersend"> Learn how to use the MailerSend provider to send emails using Novu.</Card>
  <Card title="Mailtrap" href="/platform/integrations/email/mailtrap"> Learn how to use the Mailtrap provider to send emails using Novu.</Card>
  <Card title="Mandrill" href="/platform/integrations/email/mandrill"> Learn how to use the Mandrill provider to send emails using Novu.</Card>
  <Card title="Maqsam" href="/platform/integrations/email/maqsam"> Learn how to use the Maqsam provider to send emails using Novu.</Card>
  <Card title="Netcore" href="/platform/integrations/email/netcore"> Learn how to use the Netcore provider to send emails using Novu.</Card>
  <Card title="Outlook 365" href="/platform/integrations/email/outlook365"> Learn how to use the Outlook 365 provider to send emails using Novu.</Card>
  <Card title="Plunk" href="/platform/integrations/email/plunk"> Learn how to use the Plunk provider to send emails using Novu.</Card>
  <Card title="Sparkpost" href="/platform/integrations/email/sparkpost"> Learn how to use the Sparkpost provider to send emails using Novu.</Card>
  <Card title="Email Webhook" href="/platform/integrations/email/webhook"> Learn how to use the Email Webhook provider to send emails using Novu.</Card>
  <Card title="Custom SMTP" href="/platform/integrations/email/custom-smtp"> Learn how to use a Custom SMTP provider to send emails using Novu.</Card>
</Cards>


# Writing Email Template (/platform/integrations/email/writing-email-template)

Learn how to build email templates in Novu using the block editor, the code editor (custom HTML), or the API

You can create email templates in Novu using the following methods:

* **Block editor**: A visual drag-and-drop editor using prebuilt content blocks and basic variables.
* **Code editor (custom HTML)**: Full HTML and [LiquidJS](https://liquidjs.com/index.html) control for layout, logic, styling, and rendering.
* **API**: Submit raw HTML and LiquidJS templates via the API.

<Callout>When comparing string values in Liquid conditional statements, for example `{% if context.tenant.data.branding.logoUrl != 'value' %}`, always use single quotes (`'value'`). Double quotes (`"value"`) are not supported currently.</Callout>

## Blocks editor

The block editor is a `WYSIWYG` editor that allows you to create and edit email templates. It has two fields: `Subject` and `Body`.

* **Subject**: Title of the email. It supports variables and can be customized based on the subscriber properties and payload variables.
* **Body**: Main content of the email. It is made of blocks.

The block editor body is made of blocks. A block can be added by clicking on the plus (+) icon in the top-left corner of the editor or by adding a forward slash (`/`). In both cases, a menu appears with the list of supported blocks. Click on the desired block to add it to the editor. The menu option next to the plus (+) icon can be used to **duplicate** or **delete** the block.

<img src="/images/channels-and-providers/email/writing-email-template/email-blocks.gif" alt="Email blocks" />

The Email Editor supports the following blocks:

* **Text**: Regular text
* **Heading 1**: Large heading (H1)
* **Heading 2**: Medium heading (H2)
* **Heading 3**: Small heading (H3)
* **Bullet List**: Bullet list (bullet points like •)
* **Numbered List**: Numbered list (numeric digits like 1,2,3)
* **Image**: Full width image with absolute URL, image position can be customized
* **Section**: Create a section to group content together
* **Column**: Creates columns to group content together, useful for responsive design
* **Divider**: Separates the content, adds a line to highlight the separation
* **Spacer**: Spacer to add space between two blocks (available in sm, lg and xl sizes)
* **Button**: Call to action button to link to a page or URL that can be customized with text, URL, color, and size and background color.
* **Hard Break**: Adds a line break
* **Blockquote**: Adds a blockquote
* **Custom HTML code**: Insert raw HTML with variable support
* **Repeat**: Can be used for iteration on array of data
* **Show**: Can be used to conditionally show content based on a condition, use eye icon to toggle the visibility of the content

### Custom HTML block

The Custom HTML block allows you to insert raw HTML inside a block editor layout.

* Supports basic HTML structure.
* Allows injecting variables using `{{ ... }}`.
* Does not support LiquidJS control structures like `{% for %}` or `{% if %}`.

Use this block when you need inline markup control within a visual layout, but don't require full LiquidJS logic.

### Repeat block

The `Repeat` block is a synonym of the JavaScript `for` loop. Use the + icon or `/` to add it. It iterates over an array and renders a block for each item. See the video below for details.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/yC--z0mQ3Bg" title="Learn how to use Novu email editor Repeat block" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen />

In above video:

* `{{payload.order.items}}` is array of items in the order and can be used to iterate over the items

then each item in the iteration has following properties:

* `{{payload.order.items.name}}` is the name of the item
* `{{payload.order.items.price}}` is the price of the item

### Show Block

Show block can be used to conditionally show content based on a condition. Use the eye icon to toggle the visibility of the content. Few components supports eye icon. Conditions could be based on subscribr properties, payload variables.

<img src="/images/channels-and-providers/email/writing-email-template/show-block.gif" alt="Show block" />

In the image above, the **Track your order** button is displayed only if a subscriber has the `showTracking` field set to `true` in their custom data attributes. Similarly, you can use payload variables to conditionally display content.

## Code editor (custom HTML)

The code editor provides a built-in interface for writing raw HTML and embedding LiquidJS expressions directly inside the Novu dashboard. This gives you full control over layout, structure, and rendering beyond the capabilities of Novu's block editor.

The editor supports advanced use cases such as:

* Migrating existing HTML email templates
* Implementing full design systems
* Executing flow control logic directly inside email templates
* Complete layout and styling freedom without editor constraints

To use it:

1. Open an email step in your workflow.
2. Select the **Code editor** tab to switch to Custom HTML mode.
3. Start writing your template using HTML and LiquidJS syntax.

![Novu code editor](/images/channels-and-providers/email/writing-email-template/code-editor.png)

<Callout type="warn">Once you switch to the Code editor, reverting the template back to the Block editor is not supported. Some HTML constructs might not map cleanly to block definitions, so further edits must be made directly in HTML.</Callout>

## Using the API

You can also submit custom HTML email templates via the Novu API. This method supports workflows where you render templates externally and use Novu purely for delivery.

During the sending phase:

* Novu compiles your submitted HTML and LiquidJS template using the payload and subscriber context.
* The final rendered output is what gets delivered to recipients.
* LiquidJS is executed on Novu’s servers—there’s no need to pre-render the template yourself.

This approach works well if you manage your templates in your own systems and want Novu to act as the delivery engine.

## Dynamic data sources

When authoring email templates, you can bind dynamic data from the following sources:

| Data source      | Description                                                                      | Available in                       |
| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------- |
| Payload schema   | Variables defined in your workflow’s payload schema                              | Block editor, Code editor and API  |
| Subscriber data  | Subscriber profile data associated with the recipient                            | Block editor, Code editor, and API |
| Digest variables | Variables that expose the results of the digest step                             | Block editor, Code editor, and API |
| Local variables  | Variables declared within LiquidJS control structures (for loops, if statements) | Code editor and API only           |

## Editor autocomplete

Both the block and code editors provide autocomplete as you write:

* **Block editor**: Automatically completes variable expressions (`{{ ... }}`) and shows available block types when typing `/`.
* **Code editor**: Automatically completes HTML, LiquidJS expressions, and available variables inside `{{ ... }}`.

<Callout>Autocomplete suggestions are not available inside control statements like `{% if %}` or `{% for %}`.</Callout>

## Editor preview

While editing in the editors, the template preview shows how your email will render with real or mock data.

* If your workflow defines a payload schema, then Novu uses that schema to generate preview data.
* Otherwise, it falls back to using sample data from previous executions or default payloads.
* Any inline or loop-scoped variables are also evaluated during preview rendering.


# Push Notification Channel Integrations (/platform/integrations/push)

Connect push providers like FCM, APNS, and OneSignal to Novu. Manage device tokens and deliver mobile and web push notifications.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Push providers are the services that deliver notifications your subscribers' devices, which can be delivered through mobile, desktop, or web. Each provider must be set up individually in the Novu dashboard.

Novu provides a unified integration layer that connects your workflows to push providers. Once your push provider is configured, Novu automatically handles message delivery, routing each notification through the correct provider without requiring extra setup.

You can also manage multiple integrations even for the same provider in one place, giving you full flexibility and centralized control over your push notifications.

## Key features

* **Multi-provider support**: Integrate with providers like Firebase Cloud Messaging (FCM), OneSignal, or Apple Push Notification Service (APNS).
* **Unified delivery**: Streamline your push notifications with a single API for mobile and web platforms.
* **Device management**: Keep subscriber device tokens in sync using just-in-time or manual updates.

## How push works in Novu

Here is the step-by-step process for sending a push notification with Novu:

<Steps>
  <Step>
    ### Add a push provider integration

    Start by adding a push channel provider integration in the **Integration Store** on your Novu dashboard.
    You can connect one or more integrations for the same provider, each with its own credentials and environment configuration.
  </Step>

  <Step>
    ### Add the Push channel to your workflow

    Next, add a Push step to a workflow. This step defines when and how a push message should be sent as part of your notification logic.
  </Step>

  <Step>
    ### Store device tokens for your subscribers

    Each subscriber in Novu must have a valid device token specific to the push provider integration.
    These tokens are stored in the subscriber’s profile and can be added or updated using the SDK or API.
    Novu uses these tokens to route messages to the correct device when a workflow runs.
  </Step>

  <Step>
    ### Trigger the workflow

    Trigger the workflow by sending an event from your application code.
    Novu automatically resolves the subscriber, selects all active push provider integrations device tokens, and delivers the message through the configured integrations.
  </Step>
</Steps>

## Managing push device tokens

To send push notifications, each subscriber must have one or more device tokens for each push provider integration associated with their profile.

These tokens are unique identifiers that help push notification providers deliver messages to the correct devices. Each provider has its own method for obtaining device tokens, refer to your provider's guide to learn how to generate the device tokens.

<Callout>Each subscriber channel supports a maximum of **100 device tokens**. Attempts to create or update credentials beyond this limit will be rejected. Remove unused or stale tokens to stay within the limit. See [Platform Limits](/platform/developer/limits) for all system limits.</Callout>

<Callout type="info"> The code examples in this section use fcm. For other providers, replace `ChatOrPushProviderEnum.Fcm` with the correct enum for your provider, such as `ChatOrPushProviderEnum.Apns` or `ChatOrPushProviderEnum.Expo`. </Callout>

### Add push device tokens

Novu offers two ways of adding device tokens to a subscriber's profile:

* Just in time - inline with triggering the workflow
* Ahead of trigger - before triggering the workflow

#### Just in time

You can pass the device tokens in the `channels` array of the subscriber field when triggering a workflow. Novu automatically updates the subscriber's profile with these tokens before sending the message. Here is an example with FCM:

```typescript
import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
    channels: [
      {
        providerId: ChatOrPushProviderEnum.Fcm,
        credentials: {
          deviceTokens: ["token-1", "token-2"],
        }
      },
    ],
  },
  payload: {},
});
```

#### Ahead of trigger

You can add device tokens for a subscriber using the [Update provider credentials API](/api-reference/subscribers/update-provider-credentials) before triggering the workflow.

This method is useful when you manage device registration outside of your workflow triggers, for example, after a user logs in.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from "@novu/api";
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",});

    async function run() {
      const result = await novu.subscribers.credentials.update({
        providerId: ChatOrPushProviderEnum.Fcm,
        credentials: {
          deviceTokens: [
            "token1",
            "token2",
          ],
        },
      }, "subscriberId");
    }
    run();
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "fcm",
      "credentials": {
        "deviceTokens" : [
          "token1",
          "token2"
        ]
      }
    }'
    ```
  </Tab>
</Tabs>

### Add device tokens for specific integrations

Novu supports multiple active integrations per provider for the push channel. For example, you can have more than one active FCM integration at a time, one for android and one for web app.

By default, device tokens are stored for the most recently created integration. To store device tokens for a specific integration, you must use the `integrationIdentifier` field. This is the identifier for the integration, which you can find in the Novu dashboard.

![Integration identifier](/images/channels-and-providers/push/integration-identifier.png)

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from "@novu/api";
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",});

    async function run() {
      const result = await novu.subscribers.credentials.update({
        providerId: ChatOrPushProviderEnum.Fcm,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "fcm-MnGLxp8uy",
        credentials: {
          deviceTokens: [
            "token1",
            "token2",
          ],
        },
      }, "subscriberId");
    }
    run();
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "fcm",
      "credentials": {
        "deviceTokens" : [
          "token1",
          "token2"
        ]
      },
      "integrationIdentifier": "fcm-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

### Remove device tokens

To remove device token(s) from subscriber credentials, follow this process:

When a subscriber logs out of a device, remove that device token from the subscriber's credentials. This prevents another subscriber who may log in to the same device from receiving notifications meant for the previous subscriber.

<Callout>Handle token removal, such as during a user logout event on the server-side, to prevent stale or invalid tokens from causing failed deliveries.</Callout>

#### Automatic removal of stale device tokens

<Callout type="info">
  Novu automatically removes invalid, stale or expired device tokens from a subscribers' profile and then sends the failure details via `message.failed` [webhook event](/platform/developer/webhooks/event-types#message-events). This ensures that notifications are only sent to valid and active devices. This feature is currently supported for FCM and Expo providers. If you are looking for other providers to support this feature, reach out to us at [support@novu.co](mailto:support@novu.co)
</Callout>

#### Remove a specific token

To remove device tokens from subscriber credentials, follow this process:

1. Fetch the subscriber's current token list.
2. Filter out the token you want to remove.
3. Update the subscriber with the new, filtered list.

```ts
import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

const subscriberId = "subscriberId";
const providerId = ChatOrPushProviderEnum.Fcm;

// 1. Fetch current credentials
const { data: subscriber } = await novu.subscribers.get(subscriberId);
const currentTokens = subscriber.credentials[providerId]?.deviceTokens || [];

// 2. Remove the specific token
const filteredTokens = currentTokens.filter(token => token !== "token_to_remove");

// 3. Update subscriber
await novu.subscribers.credentials.update(
  {
    providerId,
    credentials: {
      deviceTokens: filteredTokens,
    },
  },
  subscriberId
);
```

#### Remove all tokens

To remove all device tokens for a provider, or for a specific integration, update the credentials with an empty array.

```tsx
import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.Fcm,
    credentials: {
      deviceTokens: [],
    },
  },
  "subscriberId"
);
```

## Supported providers

Novu supports the following providers:

<Cards>
  <Card title="Firebase Cloud Messaging (FCM)" href="/platform/integrations/push/fcm">
    Learn how to use the FCM provider to send push notifications using Novu.
  </Card>

  <Card title="Expo Push" href="/platform/integrations/push/expo-push">
    Learn how to use the Expo Push provider to send push notifications using Novu.
  </Card>

  <Card title="Apple Push Notification Service (APNS)" href="/platform/integrations/push/apns">
    Learn how to use the APNS provider to send push notifications using Novu.
  </Card>

  <Card title="OneSignal" href="/platform/integrations/push/onesignal">
    Learn how to use the OneSignal provider to send push notifications using Novu.
  </Card>

  <Card title="Push Webhook" href="/platform/integrations/push/push-webhook">
    Learn how to use the Push Webhook provider to send push notifications using Novu.
  </Card>

  <Card title="Pusher Beams" href="/platform/integrations/push/pusher-beams">
    Learn how to use the Pusher Beams provider to send push notifications using Novu.
  </Card>

  <Card title="Pushpad" href="/platform/integrations/push/pushpad">
    Learn how to use the Pushpad provider to send push notifications using Novu.
  </Card>
</Cards>


# Push Notification Activity Tracking (/platform/integrations/push/push-activity-tracking)

Learn how to manually forward push notification events from your application to Novu for unified activity tracking.

To enable activity tracking for Push channel notifications, Novu supports a manual integration approach for push notifications. Where your application captures and forwards push notification events to Novu. Once received, Novu processes and displays these events on the dashboard for a unified tracking experience.

## How it works

The process involves a four-step data flow from your subscriber's device to Novu's servers:

1. **Client application listens**: Your application listens for push notification interactions. For example, the user opens a notification.
2. **Event sent to your backend:** When an event occurs, your application sends a payload containing the event details to an endpoint on your own server.
3. **Backend forwards to Novu:** Your server receives this data and uses the Novu SDK to securely forward the event to Novu's API.
4. **Event appears in Novu:** Novu processes the event and displays it in the **Activity Feed**, alongside events from your other channels.

## Step 1: Enable push activity tracking in Novu

Enable push activity tracking in your Novu dashboard and get the necessary credentials.

1. Log in to the Novu dashboard.
2. Navigate to the **Integration Store** page, and then select your push provider.
3. Enable the **Push Activity Tracking** toggle.
   ![Enable push activity tracking toggle in the Novu integration store](/images/channels-and-providers/push/activity-tracking/enable-activity-tracking.png)
4. Once enabled, your unique **Environment ID** and **Integration ID** are displayed. Copy and save both of these; you will need them for your backend code.
5. Click **Save Changes**.

## Step 2: Listen for push events in your application

When push notifications are delivered or interacted with, your application must capture those events and forward them to your backend. The exact code implementation depends on the push provider that you use.

The goal is to capture the event and send a JSON payload to your backend. You must send these fields:

* `eventType`: A string describing the event (for example, `opened`, `clicked`).
* `eventId`: The unique identifier for the notification, which Novu includes in the push payload as `__nvMessageId`.

<Tabs items={['Expo', 'FCM', 'OneSignal']}>
  <Tab value="expo">
    ```jsx
    import * as Notifications from 'expo-notifications';
    import Constants from 'expo-constants';
    import { Platform } from 'react-native';

    // Listen for notification interactions
    Notifications.addNotificationResponseReceivedListener(async (response) => {
      const eventData = {
        eventType: "opened",
        eventId: response.notification.request.content.data?.__nvMessageId,
        timestamp: new Date().toISOString(),
        actionIdentifier: response.actionIdentifier,
        content: {
          title: response.notification.request.content.title,
          body: response.notification.request.content.body,
          data: response.notification.request.content.data,
        },
        // Optional device context
        deviceId: Constants.sessionId,
        platform: Platform.OS,
      }});

      await fetch("https://your-api.com/api/notifications/events", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(eventData),
      });
    ```
  </Tab>

  <Tab value="fcm">
    ```javascript
    import messaging from '@react-native-firebase/messaging';
    import { Platform } from 'react-native';

    const trackNotificationOpen = async (remoteMessage) => {
      const eventData = {
        eventType: "opened",
        eventId: remoteMessage?.data?.__nvMessageId,
        timestamp: new Date().toISOString(),
        content: {
          title: remoteMessage?.notification?.title,
          body: remoteMessage?.notification?.body,
        },
        deviceId: await messaging().getToken(),
        platform: Platform.OS,
      };

      try {
        await fetch("https://your-api.com/api/notifications/events", {
          method: "POST",
          headers: {
            "Content-Type": "application/json"
          },
          body: JSON.stringify(eventData),
        });
      } catch (err) {
        console.log("Failed to track notification event", err);
      }
    };

    // App opened from background
    messaging().onNotificationOpenedApp(trackNotificationOpen);

    // App opened from quit state
    messaging()
    .getInitialNotification()
    .then((remoteMessage) => {
      if (remoteMessage) {
        trackNotificationOpen(remoteMessage);
      }
    });
    ```
  </Tab>

  <Tab value="onesignal">
    ```js
    import OneSignal from 'react-native-onesignal';

    OneSignal.setNotificationOpenedHandler((openedEvent) => {
      const { notification } = openedEvent;

      const eventData = {
        eventType: "opened",
        eventId: notification.additionalData?.__nvMessageId,
        timestamp: new Date().toISOString(),
        content: {
          title: notification.title,
          body: notification.body,
        },
        deviceId: notification.notificationId,
        platform: 'ios',
      };

      fetch("https://your-api.com/api/notifications/events", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(eventData),
      });
    });
    ```
  </Tab>
</Tabs>

## Step 3: Forward events to Novu from your backend

Create an endpoint on your backend that receives the event data from your application and uses the Novu SDK to forward it to Novu.

```typescript
import { Novu } from '@novu/api';

const novuClient = new Novu({
  apiKey: process.env.NOVU_API_KEY,
});

// Your backend API endpoint that receives events from your mobile application
app.post('/api/notifications/events', async (req, res) => {
  // Forward the event data to Novu
  const response = await novuClient.activity.track({
    environmentId: process.env.NOVU_ENVIRONMENT_ID,
    integrationId: process.env.NOVU_INTEGRATION_ID,
    requestBody: req.body,
  });

  res.status(200).json({ success: true, data: response });
});
```

<Callout>Both `Integration ID` and `Environment ID` can be found in the push provider integration page after enabling Push Activity Tracking.</Callout>

Once these steps are completed, your application will send push notification engagement data to Novu. This gives you a complete, unified view of your notification performance in the Activity Feed.


# Adding SMS Channel (/platform/integrations/sms/adding-sms)

Learn how to add the SMS channel to your application

import { Card } from 'fumadocs-ui/components/card';

import { CodeIcon } from '@/components/icons/overview';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Steps>
  <Step title="Enable SMS channel in Novu Dashboard">
    <Callout type="info">
      The SMS channel is not enabled by default. To use it, configure a provider like Twilio, Nexmo, or
      others, and ensure compliance with country-specific restrictions for sender IDs (`from`).
    </Callout>

    1. Go to the Novu Dashboard and click **"Integrations"** on the left sidebar
    2. Click **"Add a provider"**
    3. Locate the **SMS** channel and select the provider you want to use and click **"Next"**
    4. Select for which environment you want to add the Provider
    5. (Optional) Add Conditions to activate the provider only under certain conditions, **useful for tenant-based providers**
    6. Click **"Create"**
    7. Add your SMS provider credentials:
       * **From**: Displayed as the sender of the SMS (ensure compliance with local regulations)
       * Provider-specific credentials such as API key / Auth token, Account SID, username, or password
    8. Save the configuration by clicking **"Update"**
  </Step>

  <Step title="Setup workflow with SMS channel in Novu Dashboard">
    1. Go to the Novu Dashboard and click **"Workflows"** on the left sidebar.
    2. Click the **"Add a Workflow"** button.
    3. Add a step and select **"SMS"** as the channel.
    4. Configure the SMS content:
       * Message body (e.g., `{{userName}}, your order {{orderId}} has shipped.`).
       * Dynamic placeholders for personalized content.
    5. Optionally, set fallback channels to ensure reliable delivery if SMS fails.
  </Step>

  <Step title="Add a workflow trigger to your backend">
    Novu's server-side SDKs make integrating Novu's REST APIs straightforward, letting you focus on implementing workflows without dealing with repetitive code.

    <Card title="Server-side SDKs" icon={<CodeIcon />} href="/platform/sdks/server" />
  </Step>

  <Step title="Test and verify SMS channel">
    Ensure your SMS configuration is working correctly by testing the setup.

    1. Go to the Novu Dashboard, navigate to the **"Workflows"** section, and locate your configured workflow.
    2. Click **"Test Workflow"** and provide sample data, such as a phone number or dynamic variables.
    3. Verify delivery in the Novu Logs or your SMS provider's dashboard.
  </Step>
</Steps>

<Callout type="info">
  Some countries have strict restriction of using verified `from` sender id (name). Kindly check
  country and provider specific requirements first.
</Callout>


# SMS Integrations (/platform/integrations/sms)

Integrate SMS providers with Novu to deliver text message notifications. Configure providers, set up workflows, and manage delivery.

The SMS channel delivers messages to your subscribers’ mobile devices through your configured SMS provider integrations.

## How SMS delivery works in Novu

Here’s the typical flow for sending an email notification through Novu:

<Steps>
  <Step>
    ### Add an email provider

    Start by adding an SMS provider in the **Integration Store** on your Novu dashboard. You can connect one or more integrations for the different or the same providers.

    To learn [how to add an SMS provider](/platform/integrations/sms#supported-providers), refer to the guide for that provider.
  </Step>

  <Step>
    ### Add the email channel to your workflow

    Next, include an [SMS step in your workflow](/platform/workflow/create-a-workflow). This step defines when and how an SMS should be sent as part of your notification workflow.
  </Step>

  <Step>
    ### Define the SMS content

    Within the Email step editor, write the message body. The editor supports dynamic data for personalized content.
  </Step>

  <Step>
    ### Store subscriber phone number

    Novu automatically sends the notification to the phone number stored on the subscriber's profile . You must ensure that this field is set for any subscriber who needs to receive emails. You can store subscribers phone number using the Novu API, or SDK.
  </Step>

  <Step>
    ### Trigger the workflow

    [Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu.
    Novu automatically:

    * Resolves the subscriber.
    * Selects the correct provider.
    * Renders the email template.
    * Delivers the message through the configured email integration.
  </Step>
</Steps>

<Callout type="info">Some countries restrict using verified `from` sender IDs (name). Kindly check the country- and provider-specific requirements first.</Callout>

## Configuring SMS providers

To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that email providers.

### Default sender settings

The **From** field, which is displayed as the sender of the SMS, is a required default setting for any email provider that you connect. You can override this field during trigger if necessary.

### Provider authentication

You must provide credentials specific to your email provider, such as:

* API key
* Auth token
* Account SID
* Username
* Password.

Each provider has different requirements.

<Callout type="info"> Refer to the [supported SMS providers](/platform/integrations/sms#supported-providers) list for detailed setup guides for each provider integration.</Callout>

## Override SMS settings

You can override the SMS settings when triggerring a notification by passing the `overrides` object. The overrides object field supports an `sms` property and `from`, `to`, and `content` field overrides. This lets you send a message to a different recipient, from a different sender, or with a different content.

```javascript
import { Novu } from '@novu/api';  

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({ 
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  overrides: { // [!code ++:7]
    sms: {
      to: '+123012345678',
      from: 'Novu Team',
      content: 'This SMS message is from overrides',
    },
  },
});
```

## Target a specific provider

By default, Novu uses your primary SMS provider. If you want to bypass this and force a specific, active integration for a trigger, then use the `integrationIdentifier`.

This is useful if you have multiple active integrations for different purposes. For example, you might have one integration for transactional SMS and one for security SMS. You can find the `integrationIdentifier` in the **Integration Store** of the Novu dashboard.

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/api';  

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });


    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      overrides: { // [!code ++:3]
        sms: { integrationIdentifier: 'infobip-abcdef', },
      },
    });

    ```
  </Tab>
</Tabs>

## Supported providers

Here are the SMS providers that are currently supported by Novu. Select any provider to see its detailed setup guide.

<Cards>
  <Card title="46elks" href="/platform/integrations/sms/46elks"> Learn how to use the 46elks provider to send SMS notifications using Novu.</Card>
  <Card title="Africa's Talking" href="/platform/integrations/sms/africas-talking"> Learn how to use the Africa's Talking provider to send SMS notifications using Novu.</Card>
  <Card title="AWS SNS" href="/platform/integrations/sms/aws-sns"> Learn how to use the AWS SNS provider to send SMS notifications using Novu.</Card>
  <Card title="Azure SMS" href="/platform/integrations/sms/azure"> Learn how to use the Azure SMS provider to send SMS notifications using Novu.</Card>
  <Card title="BulkSMS" href="/platform/integrations/sms/bulk-sms"> Learn how to use the BulkSMS provider to send SMS notifications using Novu.</Card>
  <Card title="Clickatell" href="/platform/integrations/sms/clickatell"> Learn how to use the Clickatell provider to send SMS notifications using Novu.</Card>
  <Card title="Clicksend" href="/platform/integrations/sms/clicksend"> Learn how to use the Clicksend provider to send SMS notifications using Novu.</Card>
  <Card title="Firetext" href="/platform/integrations/sms/firetext"> Learn how to use the Firetext provider to send SMS notifications using Novu.</Card>
  <Card title="Gupshup" href="/platform/integrations/sms/gupshup"> Learn how to use the Gupshup provider to send SMS notifications using Novu.</Card>
  <Card title="Infobip - SMS" href="/platform/integrations/sms/infobip"> Learn how to use the Infobip - SMS provider to send SMS notifications using Novu.</Card>
  <Card title="Kannel" href="/platform/integrations/sms/kannel"> Learn how to use the Kannel provider to send SMS notifications using Novu.</Card>
  <Card title="Kudosity" href="/platform/integrations/sms/kudosity"> Learn how to use the Kudosity provider to send SMS notifications using Novu.</Card>
  <Card title="MessageBird" href="/platform/integrations/sms/messagebird"> Learn how to use the MessageBird provider to send SMS notifications using Novu.</Card>
  <Card title="Nexmo" href="/platform/integrations/sms/nexmo"> Learn how to use the Nexmo provider to send SMS notifications using Novu.</Card>
  <Card title="Plivo" href="/platform/integrations/sms/plivo"> Learn how to use the Plivo provider to send SMS notifications using Novu.</Card>
  <Card title="Sendchamp" href="/platform/integrations/sms/sendchamp"> Learn how to use the Sendchamp provider to send SMS notifications using Novu.</Card>
  <Card title="SimpleTexting" href="/platform/integrations/sms/simpletexting"> Learn how to use the SimpleTexting provider to send SMS notifications using Novu.</Card>
  <Card title="SMS Central" href="/platform/integrations/sms/sms-central"> Learn how to use the SMS Central provider to send SMS notifications using Novu.</Card>
  <Card title="SMS77" href="/platform/integrations/sms/sms77"> Learn how to use the SMS77 provider to send SMS notifications using Novu.</Card>
  <Card title="SNS" href="/platform/integrations/sms/sns"> Learn how to use the SNS provider to send SMS notifications using Novu.</Card>
  <Card title="Telnyx" href="/platform/integrations/sms/telnyx"> Learn how to use the Telnyx provider to send SMS notifications using Novu.</Card>
  <Card title="Termii" href="/platform/integrations/sms/termii"> Learn how to use the Termii provider to send SMS notifications using Novu.</Card>
  <Card title="Twilio" href="/platform/integrations/sms/twilio"> Learn how to use the Twilio provider to send SMS notifications using Novu.</Card>
</Cards>


# API reference for the @novu/js package (/platform/sdks/javascript)

Complete API reference for the Novu JavaScript package

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## Novu

The Novu client provides methods to interact with notifications, preferences, and real-time events.

### Constructor Options

<TypeTable
  name="NovuOptions"
  type={{
"backendUrl": {
  "description": "",
  "type": "string"
},
"applicationIdentifier": {
  "description": "",
  "type": "string | undefined"
},
"subscriberHash": {
  "description": "",
  "type": "string"
},
"contextHash": {
  "description": "",
  "type": "string"
},
"apiUrl": {
  "description": "",
  "type": "string"
},
"socketUrl": {
  "description": "",
  "type": "string"
},
"socketOptions": {
  "description": "Custom socket configuration options. These options will be merged with the default socket configuration.\nUse `socketType` to explicitly select the socket implementation: `'cloud'` for PartySocket or `'self-hosted'` for socket.io.\nFor socket.io-client connections, supports all socket.io-client options (e.g., `path`, `reconnectionDelay`, `timeout`, etc.).\nFor PartySocket connections, options are applied to the WebSocket instance.",
  "type": "NovuSocketOptions"
},
"useCache": {
  "description": "",
  "type": "boolean"
},
"defaultSchedule": {
  "description": "",
  "type": "DefaultSchedule"
},
"context": {
  "description": "",
  "type": "Partial<Record<string, ContextValue>>"
},
"subscriberId": {
  "description": "",
  "type": "string"
},
"subscriber": {
  "description": "",
  "type": "string | Subscriber"
}
}}
/>

### Usage

<Tabs items={['US', 'EU', 'Using Context', 'HMAC Encryption']}>
  <Tab value="US">
    ```typescript
    import { Novu } from "@novu/js";

    const novu = new Novu({
      subscriberId: "SUBSCRIBER_ID",
      applicationIdentifier: "APPLICATION_IDENTIFIER",
    });
    ```
  </Tab>

  <Tab value="EU">
    ```typescript
    import { Novu } from "@novu/js";

    const novu = new Novu({
      subscriberId: "SUBSCRIBER_ID",
      applicationIdentifier: "APPLICATION_IDENTIFIER",
      apiUrl: "https://eu.api.novu.co",
      socketUrl: "wss://eu.socket.novu.co",
    });
    ```
  </Tab>

  <Tab value="Using Context">
    <Callout type="info"> Learn how Context is used to filter Inbox notifications in the [Inbox with Context](/platform/inbox/customization-and-configuration/inbox-with-context) guide. </Callout>

    ```tsx
    import { Novu } from '@novu/js';

    const novu = new Novu({
      applicationIdentifier: 'YOUR_APP_ID',
      subscriberId: 'user-123',
      context: {
        tenant: { id: 'org-123', data: { name: 'Acme Corp' } },
        team: 'team-456',
      },
    });

    // Access the current context
    console.log(novu.context);
    // → { tenant: { id: 'org-123', data: { name: 'Acme Corp' } }, team: 'team-456' }

    // Get a stable string key (used internally for caching/filtering)
    console.log(novu.contextKey);
    // → "team:team-456,tenant:org-123"

    ```
  </Tab>

  <Tab value="HMAC Encryption">
    ```typescript
    import { Novu } from "@novu/js";

    const novu = new Novu({
      subscriberId: "SUBSCRIBER_ID",
      applicationIdentifier: "APPLICATION_IDENTIFIER",
      subscriberHash: "SUBSCRIBER_HASH_HMAC_ENCRYPTION",
    });
    ```
  </Tab>
</Tabs>

## Notifications

### Methods

#### list

Fetches a list of notifications based on provided filters.

<TypeTable
  name="NotificationFilter"
  type={{
"tags": {
  "description": "",
  "type": "string[]"
},
"read": {
  "description": "",
  "type": "boolean"
},
"archived": {
  "description": "",
  "type": "boolean"
},
"snoozed": {
  "description": "",
  "type": "boolean"
},
"seen": {
  "description": "",
  "type": "boolean"
},
"data": {
  "description": "",
  "type": "Record<string, unknown>"
},
"severity": {
  "description": "",
  "type": "SeverityLevelEnum | SeverityLevelEnum[]"
},
"createdGte": {
  "description": "",
  "type": "number"
},
"createdLte": {
  "description": "",
  "type": "number"
}
}}
/>

```typescript
import { SeverityLevelEnum } from '@novu/js';
import dayjs from "dayjs";

const now = dayjs();
// convert to milliseconds
const startDate = now.subtract(60, "days").valueOf();
const endDate = now.valueOf();  

const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  seen: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  severity: SeverityLevelEnum.HIGH,
  // data attributes
  data: {
    type: 'login',
  },
  offset: 0,
  // fetch last 60 days notifications
  createdGte: startDate,
  createdLte: endDate,
});
```

The response will be of type:

<TypeTable
  name="NotificationsResponse"
  type={{
"notifications": {
  "description": "",
  "type": "Notification[]"
},
"hasMore": {
  "description": "",
  "type": "boolean"
},
"filter": {
  "description": "",
  "type": "NotificationFilter"
}
}}
/>

#### count

Fetches the count of notifications based on filters.

<TypeTable
  name="NotificationFilter"
  type={{
"tags": {
  "description": "",
  "type": "string[]"
},
"read": {
  "description": "",
  "type": "boolean"
},
"archived": {
  "description": "",
  "type": "boolean"
},
"snoozed": {
  "description": "",
  "type": "boolean"
},
"seen": {
  "description": "",
  "type": "boolean"
},
"data": {
  "description": "",
  "type": "Record<string, unknown>"
},
"severity": {
  "description": "",
  "type": "SeverityLevelEnum | SeverityLevelEnum[]"
},
"createdGte": {
  "description": "",
  "type": "number"
},
"createdLte": {
  "description": "",
  "type": "number"
}
}}
/>

<Tabs items={['Single Filter', 'Multiple Filters']}>
  <Tab value="Single Filter">
    ```typescript
    // Single filter
    const count = await novu.notifications.count({
      read: false,
      seen: false,
      archived: false,
      severity: SeverityLevelEnum.HIGH,
       // data attributes
      data: {
        type: 'login',
      },
    });
    ```
  </Tab>

  <Tab value="Multiple Filters">
    ```typescript
    // Multiple filters
    const counts = await novu.notifications.count({
      filters: [
        { read: false }, 
        { seen: false }, 
        { severity: SeverityLevelEnum.HIGH }
        { archived: true }, 
        { tags: ['tag1'] }, 
        { data: { type: 'login' } }
      ],
    });
    ```
  </Tab>
</Tabs>

#### read

Marks a notification as read.

```typescript
await novu.notifications.read({ notificationId: 'NOTIFICATION_ID' });
```

#### unread

Marks a notification as unread.

```typescript
await novu.notifications.unread({ notificationId: 'NOTIFICATION_ID' });
```

#### seen

Marks a notification as seen.

```typescript
await novu.notifications.seen({ notificationId: 'NOTIFICATION_ID' });
```

<Callout type="info">
  **Seen vs Read**: Notifications can be "seen" (automatically tracked when visible) or "read" (explicitly marked by user interaction). The Inbox component automatically marks notifications as seen when they're visible for 1+ seconds using the browser's IntersectionObserver API. This automatic tracking batches requests for performance and works seamlessly with infinite scroll and pagination, while read status requires explicit user action.

  **Why no `unseen` method?** Unlike `read`/`unread` which can be toggled, `seen` is designed as a one-way operation. Once a notification has been seen by a user, it remains seen. This reflects the natural user experience where visibility cannot be "undone". Use filtering with `seen: false` to get unseen notifications instead.
</Callout>

#### seenAll

Marks notifications as seen. You can filter them by notification IDs, tags, or data attributes.

```typescript
// Mark specific notifications as seen
await novu.notifications.seenAll({
  notificationIds: ['NOTIFICATION_ID_1', 'NOTIFICATION_ID_2']
});

// Mark notifications by tags as seen
await novu.notifications.seenAll({
  tags: ['tag1', 'tag2']
});

// Mark notifications by data as seen
await novu.notifications.seenAll({
  data: { type: 'login' }
});

// Mark all notifications as seen (no filters)
await novu.notifications.seenAll();
```

#### archive

Archives a notification.

```typescript
await novu.notifications.archive({ notificationId: 'NOTIFICATION_ID' });
```

#### unarchive

Unarchives a notification.

```typescript
await novu.notifications.unarchive({ notificationId: 'NOTIFICATION_ID' });
```

#### readAll

Marks all notifications as read. You can filter them by tags.

```typescript
await novu.notifications.readAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAll

Archives all notifications. You can filter them by tags.

```typescript
await novu.notifications.archiveAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAllRead

Archives all read notifications. You can filter them by tags.

```typescript
await novu.notifications.archiveAllRead({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### delete

Deletes a single notification permanently.

```typescript
await novu.notifications.delete({ notificationId: 'NOTIFICATION_ID' });
```

#### deleteAll

Deletes multiple notifications permanently. You can filter them by tags or data attributes.

```typescript
// Delete specific notifications by tags
await novu.notifications.deleteAll({
  tags: ['tag1', 'tag2'],
});

// Delete notifications by data attributes
await novu.notifications.deleteAll({
  data: { type: 'login' },
});

// Delete all notifications (no filters)
await novu.notifications.deleteAll();
```

#### snooze

Snoozes a notification for a specified duration. Here `snoozeUntil` is **ISO 8601** formatted string timestamp, representing the date and time the notification is un-snoozed, it should be a future date and time.

```typescript
await novu.notifications.snooze({ notificationId: 'NOTIFICATION_ID', snoozeUntil: '2025-01-01T00:00:00.000Z' });
```

#### unsnooze

Unsnoozes a notification.

```typescript
await novu.notifications.unsnooze({ notificationId: 'NOTIFICATION_ID' });
```

#### completePrimary

Marks primary action of a notification as completed.

```typescript
await novu.notifications.completePrimary({ notificationId: 'NOTIFICATION_ID' });
```

#### completeSecondary

Marks secondary action of a notification as completed.

```typescript
await novu.notifications.completeSecondary({ notificationId: 'NOTIFICATION_ID' });
```

#### revertPrimary

Reverts primary action of a notification to pending.

```typescript
await novu.notifications.revertPrimary({ notificationId: 'NOTIFICATION_ID' });
```

#### revertSecondary

Reverts secondary action of a notification to pending.

```typescript
await novu.notifications.revertSecondary({ notificationId: 'NOTIFICATION_ID' });
```

## Notification

Individual notification instances have their own methods for marking as seen, read, archived, etc. These methods are available directly on each notification object.

### Methods

* `seen()` - Marks the notification as seen
* `read()` - Marks the notification as read
* `unread()` - Marks the notification as unread
* `archive()` - Archives the notification
* `unarchive()` - Unarchives the notification
* `delete()` - Deletes the notification
* `snooze()` - Snoozes the notification
* `unsnooze()` - Unsnoozes the notification
* `completePrimary()` - Marks primary action as completed
* `completeSecondary()` - Marks secondary action as completed
* `revertPrimary()` - Reverts primary action to pending
* `revertSecondary()` - Reverts secondary action to pending

<Callout type="info">The `seen()` method is only available on individual notification instances, not on the `novu.notifications` object. Use `novu.notifications.seenAll()` for bulk operations.</Callout>

### Usage

```typescript
// Get notifications
const { data: notifications } = await novu.notifications.list();

// Mark a specific notification as seen using the instance method
await notifications[0].seen();

// Mark as read using the instance method
await notifications[0].read();

// Archive using the instance method
await notifications[0].archive();

// Snooze using the instance method
await notifications[0].snooze('2025-01-01T00:00:00.000Z');

// Unsnooze using the instance method
await notifications[0].unsnooze();

// Delete using the instance method
await notifications[0].delete();
```

## Preferences

### Methods

#### list

Fetches the subscriber's notification preferences.

```typescript
const { data: preferences } = await novu.preferences.list();
```

#### update

`update` method is available with each preference object.

```typescript
const { data: preferences } = await novu.preferences.list();

// Update a single preference

await preferences[0].update({ channels: { email: false, sms: true } });
```

The response will be of type:

<TypeTable
  name="PreferenceResponse"
  type={{
"level": {
  "description": "",
  "type": "PreferenceLevel"
},
"enabled": {
  "description": "",
  "type": "boolean"
},
"condition": {
  "description": "",
  "type": "RulesLogic"
},
"subscriptionId": {
  "description": "",
  "type": "string"
},
"channels": {
  "description": "",
  "type": "ChannelPreference"
},
"overrides": {
  "description": "",
  "type": "IPreferenceOverride[]"
},
"workflow": {
  "description": "",
  "type": "Workflow"
},
"schedule": {
  "description": "",
  "type": "{ isEnabled: boolean; weeklySchedule?: WeeklySchedule | undefined; }"
}
}}
/>

#### bulkUpdate

Updates multiple workflow's channel preferences at once.

```typescript
await novu.preferences.bulkUpdate([
  { workflowId: 'workflow_id', channels: { email: false, sms: true } },
  { workflowId: 'workflow_id_2', channels: { email: true, sms: false, in_app: true } },
]);
```

### Schedule

The `preferences.schedule` submodule lets you fetch and update a subscriber’s delivery schedule.

#### get

Fetches the subscriber’s schedule.

```tsx
const novu = new Novu(...);

const { data: { schedule } } = await novu.preferences.schedule.get();
```

#### update

Updates the subscriber’s schedule. You can update the entire weekly schedule or only specific days.

```tsx
const novu = new Novu(...);

// Update schedule via preferences
const { data: { schedule } } = await novu.preferences.schedule.update({
  weeklySchedule: {
    monday: {
      isEnabled: true,
      hours: [{ start: '09:00 AM', end: '05:00 PM' }],
    },
  },
});

// Or update directly from a Schedule instance
const { data: { schedule: updatedSchedule } } =
  await schedule.update({ isEnabled: false });
```

### Schedule Class

A `Schedule` instance is returned when fetching or updating a schedule.

<TypeTable
  name="Schedule"
  type={{
"isEnabled": {
  "description": "",
  "type": "boolean | undefined"
},
"weeklySchedule": {
  "description": "",
  "type": "WeeklySchedule | undefined"
},
"update": {
  "description": "",
  "type": "(args: UpdateScheduleArgs) => Result<Schedule, NovuError>"
}
}}
/>

## Events

The Novu client provides real-time event handling through WebSocket connections.

### Available Events

* `notifications.notification_received`: Triggered when a new notification is received.
* `notifications.unread_count_changed`: Triggered when the unread count changes.
* `notifications.unseen_count_changed`: Triggered when the unseen count changes.
* `preferences.schedule.get.pending`: Triggered when fetching a schedule starts.
* `preferences.schedule.get.resolved`: Triggered when fetching a schedule succeeds.
* `preferences.schedule.update.pending`: Triggered when updating a schedule starts.
* `preferences.schedule.update.resolved`: Triggered when updating a schedule succeeds.
* `subscriptions.list.pending`: Triggered when loading subscriptions starts.
* `subscriptions.list.resolved`: Triggered when subscriptions are loaded.
* `subscriptions.get.pending`: Triggered when fetching a subscription starts.
* `subscriptions.get.resolved`: Triggered when a specific subscription is fetched.
* `subscriptions.create.pending`: Triggered when creating a subscription starts.
* `subscriptions.create.resolved`: Triggered when a subscription is created.
* `subscriptions.update.pending`: Triggered when updating a subscription starts.
* `subscriptions.update.resolved`: Triggered when a subscription is updated.
* `subscriptions.delete.pending`: Triggered when deleting a subscription start.
* `subscriptions.delete.resolved`: Triggered when a subscription is deleted.

### Usage

```typescript

novu.on('session.initialize.resolved', ({ data }: { data: Session }) => {
  console.log(data.unreadCount.total);
  console.log(data.unreadCount.severity[SeverityLevelEnum.HIGH]);
});

novu.on('notifications.notification_received', (data) => {
  console.log('New notification:', data);
});

novu.on('notifications.unread_count_changed', (data) => {
  console.log('Unread count:', data);
});

novu.on('notifications.unseen_count_changed', (data) => {
  console.log('Unseen count:', data);
});

novu.on('preferences.schedule.update.resolved', ({ data }) => {
  console.log('Schedule updated:', data.schedule);
});

novu.on('subscriptions.create.resolved', ({ data: subscription }) => {
  console.log('New subscription created:', subscription.identifier);
});

novu.on('subscriptions.list.resolved', ({ data: subscriptions }) => {
  console.log('Loaded subscriptions:', subscriptions.length);
});

```

## Subscriptions

The Subscriptions module lets you manage a subscriber’s subscriptions to topics. A subscription represents a subscriber’s opt-in to a topic and defines which workflows within that topic they receive notifications from.

It supports creating conditional subscriptions where users only receive notifications if specific criteria (payload filters) are met.

Manage subscriptions at two levels:

* Module-level methods on `novu.subscriptions`
* Instance-level methods on a `TopicSubscription` object

### Methods

#### List

Fetches all subscriptions for a specific topic.

<TypeTable
  name="ListSubscriptionsArgs"
  type={{
"topicKey": {
  "description": "",
  "type": "string"
}
}}
/>

```tsx
const { data: subscriptions } = await novu.subscriptions.list({
  topicKey: 'product-updates'
});
```

The response items are `TopicSubscription` instances.

#### get

Fetch a single subscription by topic and identifier.

<TypeTable
  name="GetSubscriptionArgs"
  type={{
"topicKey": {
  "description": "",
  "type": "string"
},
"identifier": {
  "description": "",
  "type": "string"
},
"workflowIds": {
  "description": "",
  "type": "string[]"
},
"tags": {
  "description": "",
  "type": "string[]"
}
}}
/>

```tsx
const { data: subscription } = await novu.subscriptions.get({
  topicKey: 'product-updates',
  identifier: 'user-product-alert'
});
```

#### create

Create a new subscription to a topic. You can pass a list of preferences to filter specific workflows or tags.

<TypeTable
  name="CreateSubscriptionArgs"
  type={{
"topicKey": {
  "description": "",
  "type": "string"
},
"topicName": {
  "description": "",
  "type": "string"
},
"identifier": {
  "description": "",
  "type": "string"
},
"name": {
  "description": "",
  "type": "string"
},
"preferences": {
  "description": "",
  "type": "PreferenceFilter[]"
}
}}
/>

```tsx
const { data: subscription } = await novu.subscriptions.create({
  topicKey: 'product-updates',
  identifier: 'user-product-alert',
  preferences: [
    {
      // Simple workflow toggle
      workflowId: 'issue-created',
      enabled: true
    },
    {
      // Conditional filter
      workflowId: 'price-alert',
      condition: {
        field: 'price',
        operation: 'below',
        value: 100
      }
    }
  ]
});
```

#### update

Updates an existing subscription.

<TypeTable
  name="UpdateSubscriptionArgs"
  type={{
"name": {
  "description": "",
  "type": "string"
},
"preferences": {
  "description": "",
  "type": "PreferenceFilter[]"
}
}}
/>

```tsx
const { data: subscription } = await novu.subscriptions.update({
  topicKey: 'product-updates',
  subscriptionId: 'subscription-id-123',
  preferences: [...]
});
```

#### delete

Delete a subscription by topic and subscription ID.

```tsx
await novu.subscriptions.delete({
  topicKey: 'product-updates',
  subscriptionId: 'product-updates-subscription',
});
```

### TopicSubscription

A `TopicSubscription` instance represents a single subscription and provides methods for updating or deleting it, as well as managing its preferences.

<TypeTable
  name="TopicSubscription"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"identifier": {
  "description": "",
  "type": "string"
},
"topicKey": {
  "description": "",
  "type": "string"
},
"preferences": {
  "description": "",
  "type": "SubscriptionPreference[]"
},
"update": {
  "description": "",
  "type": "{ (args: BaseUpdateSubscriptionArgs): Result<TopicSubscription, NovuError>; (args: InstanceUpdateSubscriptionArgs): Result<...>; }"
},
"updatePreference": {
  "description": "",
  "type": "{ (args: BaseSubscriptionPreferenceArgs): Result<SubscriptionPreference, NovuError>; (args: InstanceSubscriptionPreferenceArgs): Result<...>; }"
},
"bulkUpdatePreferences": {
  "description": "",
  "type": "{ (args: BaseSubscriptionPreferenceArgs[]): Result<SubscriptionPreference[], NovuError>; (args: InstanceSubscriptionPreferenceArgs[]): Result<...>; }"
},
"delete": {
  "description": "",
  "type": "() => Result<void, NovuError>"
}
}}
/>

#### Update a subscription

Update subscription metadata or replace its preferences list. Use this method when updating the subscription as a whole.
For granular preference updates, use preference-level methods instead.

```tsx
const { data: subscription } =
  await novu.subscriptions.get({
    topicKey: 'product-updates',
    identifier: 'product-updates-subscription',
  });

await subscription.update({
  preferences: [
    {
      workflowId: 'workflow-identifier',
      enabled: true,
    },
  ],
});
```

#### Update SubscriptionPreference

Each subscription contains a list of `SubscriptionPreference` objects that you can update individually.

<TypeTable
  name="SubscriptionPreference"
  type={{
"subscriptionId": {
  "description": "",
  "type": "string"
},
"workflow": {
  "description": "",
  "type": "Workflow"
},
"enabled": {
  "description": "",
  "type": "boolean"
},
"condition": {
  "description": "",
  "type": "RulesLogic"
},
"update": {
  "description": "",
  "type": "(args: { value: RulesLogic; }) => Result<SubscriptionPreference, NovuError>"
}
}}
/>

```tsx
subscription.preferences.map((preference) => {
  const onChange = (value: boolean) => {
    preference.update({ value });
  };

  return <Checkbox onChange={onChange} />;
});
```

#### Delete a subscription (instance method)

```
await subscription.delete();
```

## Types

### Notification

<TypeTable
  name="Notification"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"transactionId": {
  "description": "",
  "type": "string"
},
"subject": {
  "description": "",
  "type": "string"
},
"body": {
  "description": "",
  "type": "string"
},
"to": {
  "description": "",
  "type": "Subscriber"
},
"isRead": {
  "description": "",
  "type": "boolean"
},
"isSeen": {
  "description": "",
  "type": "boolean"
},
"isArchived": {
  "description": "",
  "type": "boolean"
},
"isSnoozed": {
  "description": "",
  "type": "boolean"
},
"snoozedUntil": {
  "description": "",
  "type": "string | null"
},
"deliveredAt": {
  "description": "",
  "type": "string[]"
},
"createdAt": {
  "description": "",
  "type": "string"
},
"readAt": {
  "description": "",
  "type": "string | null"
},
"firstSeenAt": {
  "description": "",
  "type": "string | null"
},
"archivedAt": {
  "description": "",
  "type": "string | null"
},
"avatar": {
  "description": "",
  "type": "string"
},
"primaryAction": {
  "description": "",
  "type": "Action"
},
"secondaryAction": {
  "description": "",
  "type": "Action"
},
"channelType": {
  "description": "",
  "type": "ChannelType"
},
"tags": {
  "description": "",
  "type": "string[] | undefined"
},
"redirect": {
  "description": "",
  "type": "Redirect | undefined"
},
"data": {
  "description": "",
  "type": "NotificationData"
},
"workflow": {
  "description": "",
  "type": "Workflow"
},
"severity": {
  "description": "",
  "type": "SeverityLevelEnum"
},
"read": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unread": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"seen": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"archive": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unarchive": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"delete": {
  "description": "",
  "type": "() => Result<void, NovuError>"
},
"snooze": {
  "description": "",
  "type": "(snoozeUntil: string) => Result<Notification, NovuError>"
},
"unsnooze": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"completePrimary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"completeSecondary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"revertPrimary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"revertSecondary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"on": {
  "description": "",
  "type": "<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => () => void"
},
"off": {
  "description": "",
  "type": "<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => void"
}
}}
/>

### Subscriber

<TypeTable
  name="Subscriber"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"subscriberId": {
  "description": "",
  "type": "string"
},
"firstName": {
  "description": "",
  "type": "string"
},
"lastName": {
  "description": "",
  "type": "string"
},
"email": {
  "description": "",
  "type": "string"
},
"phone": {
  "description": "",
  "type": "string"
},
"avatar": {
  "description": "",
  "type": "string"
},
"locale": {
  "description": "",
  "type": "string"
},
"data": {
  "description": "",
  "type": "Record<string, unknown>"
},
"timezone": {
  "description": "",
  "type": "string"
}
}}
/>


# Novu React SDK Changelog (/platform/sdks/react/changelog)

Changelog for the @novu/react package

import { ChangelogDisplay } from '@/components/changelog-display';

<ChangelogDisplay />


# API reference for the @novu/react package (/platform/sdks/react)

API reference for @novu/react components including Inbox, Bell, Notifications, and Subscription.

## Components

The @novu/react package provides React components for building notification UIs.

## Inbox

The main component for displaying notifications.

### Props

<TypeTable
  name="InboxProps"
  type={{
"appearance": {
  "description": "",
  "type": "ReactInboxAppearance"
},
"subscriberHash": {
  "description": "",
  "type": "string"
},
"contextHash": {
  "description": "",
  "type": "string"
},
"backendUrl": {
  "description": "",
  "type": "string"
},
"socketUrl": {
  "description": "",
  "type": "string"
},
"socketOptions": {
  "description": "",
  "type": "NovuSocketOptions"
},
"localization": {
  "description": "",
  "type": "InboxLocalization"
},
"tabs": {
  "description": "",
  "type": "Tab[]"
},
"preferencesFilter": {
  "description": "",
  "type": "PreferencesFilter"
},
"preferenceGroups": {
  "description": "",
  "type": "PreferenceGroups"
},
"preferencesSort": {
  "description": "",
  "type": "PreferencesSort"
},
"defaultSchedule": {
  "description": "",
  "type": "DefaultSchedule"
},
"routerPush": {
  "description": "",
  "type": "RouterPush"
},
"context": {
  "description": "",
  "type": "Partial<Record<string, ContextValue>>"
},
"subscriberId": {
  "description": "",
  "type": "string"
},
"subscriber": {
  "description": "",
  "type": "string | Subscriber"
},
"applicationIdentifier": {
  "description": "",
  "type": "string"
}
}}
/>

### Usage

```tsx
import { Inbox } from "@novu/react";

function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="APPLICATION_IDENTIFIER"
      subscriber={{
        subscriberId: "SUBSCRIBER_ID",
      }}
      apiUrl="https://api.novu.co"
      socketUrl="https://socket.novu.co"
      placement="right"
      placementOffset={10}
      onNotificationClick={(notification) => {
        // Handle notification click
        console.log(notification);
      }}
    />
  );
}
```

### Appearance Configuration

<TypeTable
  name="InboxAppearanceProps"
  type={{
"variables": {
  "description": "",
  "type": "Variables"
},
"animations": {
  "description": "",
  "type": "boolean"
},
"icons": {
  "description": "",
  "type": "AllIconOverrides"
},
"baseTheme": {
  "description": "",
  "type": "AllTheme | AllTheme[]"
}
}}
/>

#### Variables

<TypeTable
  name="InboxAppearanceVariables"
  type={{
"colorBackground": {
  "description": "",
  "type": "string"
},
"colorForeground": {
  "description": "",
  "type": "string"
},
"colorPrimary": {
  "description": "",
  "type": "string"
},
"colorPrimaryForeground": {
  "description": "",
  "type": "string"
},
"colorSecondary": {
  "description": "",
  "type": "string"
},
"colorSecondaryForeground": {
  "description": "",
  "type": "string"
},
"colorCounter": {
  "description": "",
  "type": "string"
},
"colorCounterForeground": {
  "description": "",
  "type": "string"
},
"colorNeutral": {
  "description": "",
  "type": "string"
},
"colorShadow": {
  "description": "",
  "type": "string"
},
"colorRing": {
  "description": "",
  "type": "string"
},
"fontSize": {
  "description": "",
  "type": "string"
},
"borderRadius": {
  "description": "",
  "type": "string"
},
"colorStripes": {
  "description": "",
  "type": "string"
},
"colorSeverityHigh": {
  "description": "",
  "type": "string"
},
"colorSeverityMedium": {
  "description": "",
  "type": "string"
},
"colorSeverityLow": {
  "description": "",
  "type": "string"
}
}}
/>

#### Elements

<TypeTable
  name="InboxAppearanceElements"
  type={{
"root": {
  "description": "",
  "type": "ElementStyles"
},
"button": {
  "description": "",
  "type": "ElementStyles"
},
"input": {
  "description": "",
  "type": "ElementStyles"
},
"icon": {
  "description": "",
  "type": "ElementStyles"
},
"badge": {
  "description": "",
  "type": "ElementStyles"
},
"popoverContent": {
  "description": "",
  "type": "ElementStyles"
},
"popoverTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"popoverClose": {
  "description": "",
  "type": "ElementStyles"
},
"collapsible": {
  "description": "",
  "type": "ElementStyles"
},
"tooltipContent": {
  "description": "",
  "type": "ElementStyles"
},
"tooltipTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"lockIcon": {
  "description": "",
  "type": "ElementStyles"
},
"preferences__button": {
  "description": "",
  "type": "ElementStyles"
},
"inboxHeader": {
  "description": "",
  "type": "ElementStyles"
},
"loading": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItemLabel": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItemLabelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItemLeft__icon": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItemRight__icon": {
  "description": "",
  "type": "ElementStyles"
},
"dropdownItem__icon": {
  "description": "",
  "type": "ElementStyles"
},
"datePicker": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerGrid": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerGridRow": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerGridCell": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerGridCellTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerGridHeader": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerControl": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerControlPrevTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerControlNextTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerControlPrevTrigger__icon": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerControlNextTrigger__icon": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerCalendar": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerHeaderMonth": {
  "description": "",
  "type": "ElementStyles"
},
"datePickerCalendarDay__button": {
  "description": "",
  "type": "ElementStyles"
},
"timePicker": {
  "description": "",
  "type": "ElementStyles"
},
"timePicker__hourSelect": {
  "description": "",
  "type": "ElementStyles"
},
"timePicker__minuteSelect": {
  "description": "",
  "type": "ElementStyles"
},
"timePicker__periodSelect": {
  "description": "",
  "type": "ElementStyles"
},
"timePicker__separator": {
  "description": "",
  "type": "ElementStyles"
},
"timePickerHour__input": {
  "description": "",
  "type": "ElementStyles"
},
"timePickerMinute__input": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePicker": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePicker__actions": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePickerCancel__button": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePickerApply__button": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePicker__timePickerContainer": {
  "description": "",
  "type": "ElementStyles"
},
"snoozeDatePicker__timePickerLabel": {
  "description": "",
  "type": "ElementStyles"
},
"back__button": {
  "description": "",
  "type": "ElementStyles"
},
"skeletonText": {
  "description": "",
  "type": "ElementStyles"
},
"skeletonAvatar": {
  "description": "",
  "type": "ElementStyles"
},
"skeletonSwitch": {
  "description": "",
  "type": "ElementStyles"
},
"skeletonSwitchThumb": {
  "description": "",
  "type": "ElementStyles"
},
"tabsRoot": {
  "description": "",
  "type": "ElementStyles"
},
"tabsList": {
  "description": "",
  "type": "ElementStyles"
},
"tabsContent": {
  "description": "",
  "type": "ElementStyles"
},
"tabsTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"dots": {
  "description": "",
  "type": "ElementStyles"
},
"inboxContent": {
  "description": "",
  "type": "ElementStyles"
},
"inbox__popoverTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"inbox__popoverContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListEmptyNoticeContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListEmptyNoticeOverlay": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListEmptyNoticeIcon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListEmptyNotice": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList__skeleton": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList__skeletonContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList__skeletonItem": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList__skeletonAvatar": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList__skeletonText": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListNewNotificationsNotice__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSubject__strong": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSubject__em": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBody__strong": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBody__em": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBodyContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDateActionsContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationRead__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnread__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationArchive__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnarchive__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnsnooze__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationRead__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnread__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationArchive__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnarchive__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationUnsnooze__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabs__tabsRoot": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabs__tabsList": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabs__tabsContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabs__tabsTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabsTriggerLabel": {
  "description": "",
  "type": "ElementStyles"
},
"notificationsTabsTriggerCount": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__title": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItemLabel": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItemLabelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItemLeft__icon": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItemRight__icon": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItem__icon": {
  "description": "",
  "type": "ElementStyles"
},
"inboxStatus__dropdownItemCheck__icon": {
  "description": "",
  "type": "ElementStyles"
},
"moreActionsContainer": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dropdownItemLabel": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dropdownItemLeft__icon": {
  "description": "",
  "type": "ElementStyles"
},
"moreActions__dots": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__button": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__icon": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__dropdownItemLabel": {
  "description": "",
  "type": "ElementStyles"
},
"moreTabs__dropdownItemRight__icon": {
  "description": "",
  "type": "ElementStyles"
},
"workflowContainerDisabledNotice": {
  "description": "",
  "type": "ElementStyles"
},
"workflowLabelDisabled__icon": {
  "description": "",
  "type": "ElementStyles"
},
"workflowDescription": {
  "description": "",
  "type": "ElementStyles"
},
"channelsContainerCollapsible": {
  "description": "",
  "type": "ElementStyles"
},
"channelSwitch": {
  "description": "",
  "type": "ElementStyles"
},
"channelSwitchThumb": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesHeader": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesHeader__back__button": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesHeader__back__button__icon": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesHeader__title": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesHeader__icon": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesListEmptyNoticeContainer": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesListEmptyNotice": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeleton": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonContent": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonItem": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonIcon": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonSwitch": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonSwitchThumb": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesList__skeletonText": {
  "description": "",
  "type": "ElementStyles"
},
"dayScheduleCopy__dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"dayScheduleCopy__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__time": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownItemLabel": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownItemLabelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"timeSelect__dropdownItemCheck__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__dropdownItem__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnoozeCustomTime_popoverContent": {
  "description": "",
  "type": "ElementStyles"
},
"strong": {
  "description": "",
  "type": "ElementStyles"
},
"em": {
  "description": "",
  "type": "ElementStyles"
},
"bellIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"bellContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityHigh__bellContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityMedium__bellContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityLow__bellContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"bellSeverityGlow": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityGlowHigh__bellSeverityGlow": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityGlowMedium__bellSeverityGlow": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"severityGlowLow__bellSeverityGlow": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"bellDot": {
  "description": "",
  "type": "ElementStyles | ((context: { unreadCount: { total: number; severity: Record<string, number>; }; }) => string)"
},
"preferencesContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preferences?: Preference[] | undefined; groups: { name: string; preferences: Preference[]; }[]; }) => string)"
},
"notificationListContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { notifications: Notification[]; }) => string)"
},
"notificationList": {
  "description": "",
  "type": "ElementStyles | ((context: { notifications: Notification[]; }) => string)"
},
"notification": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityHigh__notification": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityMedium__notification": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityLow__notification": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationBar": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityHigh__notificationBar": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityMedium__notificationBar": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"severityLow__notificationBar": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationContent": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationTextContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationDot": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationSubject": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationBody": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationImage": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationImageLoadingFallback": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationDate": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationDefaultActions": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationCustomActions": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationPrimaryAction__button": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationSecondaryAction__button": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"workflowContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowLabelHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowLabelHeaderContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowLabelIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowLabelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowContainerRight__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"workflowArrow__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"preferencesGroupContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupLabelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupLabelIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupActionsContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupActionsContainerRight__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupBody": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupChannels": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupInfo": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupInfoIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"preferencesGroupWorkflows": {
  "description": "",
  "type": "ElementStyles | ((context: { preferenceGroup: { name: string; preferences: Preference[]; }; }) => string)"
},
"channelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"channelIconContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"channel__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"channelsContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"channelLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"channelLabelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"channelName": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: Preference; }) => string)"
},
"channelSwitchContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { preference?: Preference | undefined; preferenceGroup?: { name: string; preferences: Preference[]; } | undefined; }) => string)"
},
"scheduleContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleLabelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleLabelScheduleIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleLabelInfoIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleActionsContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleActionsContainerRight": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleBody": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleDescription": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleTable": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleTableHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleHeaderColumn": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleTableBody": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleBodyRow": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleBodyColumn": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleInfoContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleInfoIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"scheduleInfo": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"dayScheduleCopyTitle": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"dayScheduleCopyIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"dayScheduleCopySelectAll": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"dayScheduleCopyDay": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"dayScheduleCopyFooterContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { schedule?: Schedule | undefined; }) => string)"
},
"notificationDeliveredAt__badge": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationDeliveredAt__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"notificationSnoozedUntil__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { notification: Notification; }) => string)"
},
"subscriptionContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionButton__button": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionButtonContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionButtonIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionButtonLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscription__popoverTriggerContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscription__popoverTrigger": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionTriggerIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscription__popoverContent": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesHeaderContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesInfoIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesContent": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesGroupsContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesFallback": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesFallbackTexts": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesFallbackHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferencesFallbackDescription": {
  "description": "",
  "type": "ElementStyles | ((context: { subscription?: TopicSubscription | undefined; }) => string)"
},
"subscriptionPreferenceRow": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: { label: string; preference: SubscriptionPreference; }; }) => string)"
},
"subscriptionPreferenceLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: { label: string; preference: SubscriptionPreference; }; }) => string)"
},
"subscriptionPreferenceGroupContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupHeader": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupLabelContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupLabelIcon": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupActionsContainer": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupActionsContainerRight__icon": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupBody": {
  "description": "",
  "type": "ElementStyles | ((context: { group: { label: string; group: { label: string; preference: SubscriptionPreference; }[]; }; }) => string)"
},
"subscriptionPreferenceGroupWorkflowRow": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: { label: string; preference: SubscriptionPreference; }; }) => string)"
},
"subscriptionPreferenceGroupWorkflowLabel": {
  "description": "",
  "type": "ElementStyles | ((context: { preference: { label: string; preference: SubscriptionPreference; }; }) => string)"
}
}}
/>

## Bell

A customizable notification bell component.

### Props

<TypeTable
  name="BellProps"
  type={{
"renderBell": {
  "description": "",
  "type": "BellRenderer"
}
}}
/>

### Usage

```tsx
import { Bell } from "@novu/react";
import { BellIcon } from "lucide-react";

function NotificationBell() {
  return (
    <Bell
      renderBell={(unreadCount) => (
        <div className="relative">
          <BellIcon className="h-6 w-6" />
          {unreadCount > 0 && (
            <span className="absolute -top-1 -right-1 bg-red-500 text-white rounded-full w-5 h-5 text-xs flex items-center justify-center">
              {unreadCount}
            </span>
          )}
        </div>
      )}
    />
  );
}
```

## Notifications

A component for rendering a list of notifications.

### Props

<TypeTable
  name="NotificationProps"
  type={{
"onNotificationClick": {
  "description": "",
  "type": "NotificationClickHandler"
},
"onPrimaryActionClick": {
  "description": "",
  "type": "NotificationActionClickHandler"
},
"onSecondaryActionClick": {
  "description": "",
  "type": "NotificationActionClickHandler"
},
"renderNotification": {
  "description": "",
  "type": "NotificationsRenderer"
},
"renderAvatar": {
  "description": "",
  "type": "AvatarRenderer"
},
"renderSubject": {
  "description": "",
  "type": "SubjectRenderer"
},
"renderBody": {
  "description": "",
  "type": "BodyRenderer"
},
"renderDefaultActions": {
  "description": "",
  "type": "DefaultActionsRenderer"
},
"renderCustomActions": {
  "description": "",
  "type": "CustomActionsRenderer"
}
}}
/>

### Usage

```tsx
import { Notifications } from "@novu/react";

function NotificationList() {
  return (
    <Notifications
      onNotificationClick={(notification) => {
        // Handle notification click
        console.log(notification);
      }}
      renderNotification={({ body, createdAt }) => (
        <div className="flex gap-2 p-2">
          <div className="flex-1">
            <p>{body}</p>
            <time className="text-sm text-gray-500">
              {new Date(createdAt).toLocaleDateString()}
            </time>
          </div>
        </div>
      )}
    />
  );
}
```

## InboxContent

A component for building custom notification inboxes.

### Props

<TypeTable
  name="InboxContentProps"
  type={{
"onNotificationClick": {
  "description": "",
  "type": "NotificationClickHandler"
},
"onPrimaryActionClick": {
  "description": "",
  "type": "NotificationActionClickHandler"
},
"onSecondaryActionClick": {
  "description": "",
  "type": "NotificationActionClickHandler"
},
"initialPage": {
  "description": "",
  "type": "InboxPage"
},
"hideNav": {
  "description": "",
  "type": "boolean"
},
"renderNotification": {
  "description": "",
  "type": "NotificationsRenderer"
},
"renderAvatar": {
  "description": "",
  "type": "AvatarRenderer"
},
"renderSubject": {
  "description": "",
  "type": "SubjectRenderer"
},
"renderBody": {
  "description": "",
  "type": "BodyRenderer"
},
"renderDefaultActions": {
  "description": "",
  "type": "DefaultActionsRenderer"
},
"renderCustomActions": {
  "description": "",
  "type": "CustomActionsRenderer"
}
}}
/>

### Usage

```tsx
import { InboxContent } from "@novu/react";

function CustomInbox() {
  return (
    <div className="custom-inbox-wrapper">
      <InboxContent
        onNotificationClick={(notification) => {
          // Handle notification click
          console.log(notification);
        }}
        onPrimaryActionClick={(notification) => {
          // Handle primary action click
          console.log(notification);
        }}
        hideNav={false}
        renderNotification={({ body, createdAt }) => (
          <div className="notification-item">
            <p>{body}</p>
            <time>{new Date(createdAt).toLocaleDateString()}</time>
          </div>
        )}
      />
    </div>
  );
}
```

## Subscription

### Props

<TypeTable
  name="SubscriptionProps"
  type={{
"children": {
  "description": "",
  "type": "ReactNode"
},
"renderPreferences": {
  "description": "",
  "type": "PreferencesRenderer"
},
"open": {
  "description": "",
  "type": "boolean"
},
"placement": {
  "description": "",
  "type": "Placement"
},
"placementOffset": {
  "description": "",
  "type": "OffsetOptions"
},
"topicKey": {
  "description": "",
  "type": "string"
},
"identifier": {
  "description": "",
  "type": "string"
},
"preferences": {
  "description": "",
  "type": "UIPreference[]"
},
"localization": {
  "description": "",
  "type": "SubscriptionLocalization"
},
"appearance": {
  "description": "",
  "type": "ReactSubscriptionAppearance"
},
"container": {
  "description": "",
  "type": "string | Node | null"
}
}}
/>

### Appearance configuration

<TypeTable
  name="SubscriptionAppearance"
  type={{
"variables": {
  "description": "",
  "type": "Variables"
},
"elements": {
  "description": "",
  "type": "Partial<{ root: ElementStyles; button: ElementStyles; input: ElementStyles; icon: ElementStyles; badge: ElementStyles; ... 5 more ...; tooltipTrigger: ElementStyles; } & {} & { ...; }>"
},
"animations": {
  "description": "",
  "type": "boolean"
},
"icons": {
  "description": "",
  "type": "SubscriptionIconOverrides"
},
"baseTheme": {
  "description": "",
  "type": "SubscriptionTheme | SubscriptionTheme[]"
}
}}
/>

### Usage

```tsx
import { NovuProvider, Subscription } from "@novu/react";

function SubscriptionManager() {
  return (
    <NovuProvider
      subscriber="SUBSCRIBER_ID"
      applicationIdentifier="APPLICATION_IDENTIFIER"
    >
      <Subscription
      topic="product-updates"
      identifier="user-preference-1"
      preferences={["workflow-one", "workflow-two"]}
      appearance={{
        baseTheme: isDark ? subscriptionDarkTheme : undefined,
      }}
    />
    </NovuProvider>
  );
}
```


# Novu React Native SDK (/platform/sdks/react-native)

Learn how to add Novu powered Inbox to your React Native app

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

You can build your own Inbox UI with Novu's React Native hooks SDK. Novu will take care of data fetching will help you build a fully custom notification-center UI.

<Callout type="info">
  View our [React Native Expo Template](https://github.com/novuhq/novu-expo) for a live example of
  the inbox in action.
</Callout>

<Steps>
  <Step title="Install the React Native hooks SDK">
    ```bash
    npm install @novu/react-native
    ```
  </Step>

  <Step title="Add the Novu provider to your react-native file">
    The `NovuProvider` component is used to provide the Novu context to the inbox hooks. Make sure that the provider is wrapping your Inbox hook usages at the component tree.

    <Tabs items={['US Region', 'EU Region', "HMAC Encryption"]}>
      <Tab value="US Region">
        ```tsx
        import { NovuProvider } from "@novu/react-native";

        function Layout() {
          return (
            <NovuProvider
              subscriber="YOUR_SUBSCRIBER_ID"
              applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
            >
              {/* Your app components where you want to use the hooks */}
            </NovuProvider>
          );
        }
        ```
      </Tab>

      <Tab value="EU Region">
        ```tsx
        import { NovuProvider } from "@novu/react-native";

        function Layout() {
          return (
            <NovuProvider
              subscriber="YOUR_SUBSCRIBER_ID"
              applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
              apiUrl="https://eu.api.novu.co"
              socketUrl="wss://eu.socket.novu.co"
            >
              {/* Your app components where you want to use the hooks */}
              <YourCustomInbox />
            </NovuProvider>
          );
        }
        ```
      </Tab>

      <Tab value="HMAC Encryption">
        <Callout type="info">
          Read more about [HMAC Encryption](/platform/inbox/prepare-for-production#secure-your-inbox-with-hmac-encryption).
        </Callout>

        ```tsx
        import { NovuProvider } from '@novu/react-native';

        function App() {
          return (
            <NovuProvider
              subscriber="SUBSCRIBER_ID"
              applicationIdentifier="APPLICATION_IDENTIFIER"
              subscriberHash="SUBSCRIBER_HASH_HMAC_ENCRYPTION"
            >
              {/* Your app components */}
            </NovuProvider>
          );
        }
        ```
      </Tab>
    </Tabs>

    <Callout type="info">
      You can find the `applicationIdentifier` in the Novu Dashboard under the [API keys page](https://dashboard.novu.co/api-keys).
      The `subscriberId` is the unique identifier of the user in your application, learn more about subscribers [here](/platform/concepts/subscribers).
    </Callout>
  </Step>

  <Step title="Build your own inbox UI">
    ```tsx
    import {
      FlatList,
      View,
      Text,
      ActivityIndicator,
      RefreshControl,
    } from "react-native";

    import { useNotifications, Notification } from "@novu/react-native";

    function YourCustomInbox() {
      const { notifications, isLoading, fetchMore, hasMore, refetch } =
        useNotifications();

      const renderItem = ({ item }) => (
        <View>
          <Text>{item.body}</Text>
        </View>
      );

      const renderFooter = () => {
        if (!hasMore) return null;

        return (
          <View>
            <ActivityIndicator size="small" color="#2196F3" />
          </View>
        );
      };

      const renderEmpty = () => (
        <View>
          <Text>No updates available</Text>
        </View>
      );

      if (isLoading) {
        return (
          <View style={styles.loadingContainer}>
            <ActivityIndicator size="large" color="#2196F3" />
          </View>
        );
      }

      return (
        <FlatList
          data={notifications}
          renderItem={renderItem}
          keyExtractor={(item) => item.id}
          contentContainerStyle={styles.listContainer}
          onEndReached={fetchMore}
          onEndReachedThreshold={0.5}
          ListFooterComponent={renderFooter}
          ListEmptyComponent={renderEmpty}
          refreshControl={
            <RefreshControl
              refreshing={isLoading}
              onRefresh={refetch}
              colors={["#2196F3"]}
            />
          }
        />
      );
    }
    ```
  </Step>

  <Step title="Trigger a notification">
    Now that you have the inbox component added to your application, you can trigger an Inbox notification to see it in action.
  </Step>
</Steps>


# Novu .NET SDK (/platform/sdks/server/dotnet)

Connect a .NET application to Novu

Novu's .NET SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your C#/.NET application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-csharp)

## Installation

```csharp
dotnet add package Novu
```

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```csharp
    using Novu;
    using Novu.Models.Components;
    using System.Collections.Generic;

    var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

    var res = await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
        WorkflowId = "workflow_identifier",
        Payload = new Dictionary<string, object>() {
            { "comment_id", "string" },
            { "post", new Dictionary<string, object>() {
                { "text", "string" },
            } },
        },
        Overrides = new Overrides() {},
        To = To.CreateStr(
            "SUBSCRIBER_ID"
        ),
    });
    ```
  </Tab>

  <Tab value="EU Region">
    ```csharp
    using Novu;
    using Novu.Models.Components;
    using System.Collections.Generic;

    var sdk = new NovuSDK(
        serverUrl: "https://eu.api.novu.co",
        secretKey: "YOUR_SECRET_KEY_HERE"
    );

    var res = await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
        WorkflowId = "workflow_identifier",
        Payload = new Dictionary<string, object>() {
            { "comment_id", "string" },
            { "post", new Dictionary<string, object>() {
                { "text", "string" },
            } },
        },
        Overrides = new Overrides() {},
        To = To.CreateStr(
            "SUBSCRIBER_ID"
        ),
    });
    ```
  </Tab>
</Tabs>


# Go SDK for Novu (/platform/sdks/server/go)

Connect a Go application to Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Novu's Go SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Go application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-go)

## Installation

```go
go get github.com/novuhq/novu-go
```

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```go
    package main

    import (
    	"context"
    	novugo "github.com/novuhq/novu-go"
    	"github.com/novuhq/novu-go/models/components"
    	"log"
    	"os"
    )

    func main() {
    ctx := context.Background()

        s := novugo.New(
        	novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")),
        )

        res, err := s.Trigger(ctx, components.TriggerEventRequestDto{
        	WorkflowID: "workflow_identifier",
        	Payload: map[string]any{
        		"comment_id": "string",
        		"post": map[string]any{
        			"text": "string",
        		},
        	},
        	Overrides: map[string]map[string]any{
        		"email": map[string]any{
        			"bcc": "no-reply@novu.co",
        		},
        	},
        	To: components.CreateToSubscriberPayloadDto(
        		components.SubscriberPayloadDto{
        			SubscriberID: "subscriber_uniuqe_identifier",
        			FirstName: "Albert",
        			LastName: "Einstein",
        			Email: "albert@einstein.com",
        		},
        	),
        }, nil)
        if err != nil {
        	log.Fatal(err)
        }
        if res.TriggerEventResponseDto != nil {
        	// handle response
        }

    }

    ```
  </Tab>

  <Tab value="EU Region">
    ```go
    package main

    import (
    	"context"
    	novugo "github.com/novuhq/novu-go"
    	"github.com/novuhq/novu-go/models/components"
    	"log"
    	"os"
    )

    func main() {
    	ctx := context.Background()

    	s := novugo.New(
    		novugo.WithServerURL("https://eu.api.novu.co"),
    		novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")),
    	)

    	res, err := s.Trigger(ctx, components.TriggerEventRequestDto{
    		WorkflowID: "workflow_identifier",
    		Payload: map[string]any{
    			"comment_id": "string",
    			"post": map[string]any{
    				"text": "string",
    			},
    		},
    		Overrides: map[string]map[string]any{
    			"email": map[string]any{
    				"bcc": "no-reply@novu.co",
    			},
    		},
    		To: components.CreateToSubscriberPayloadDto(
    			components.SubscriberPayloadDto{
    				SubscriberID: "subscriber_uniuqe_identifier",
    				FirstName: "Albert",
    				LastName: "Einstein",
    				Email: "albert@einstein.com",
    			},
    		),
    	}, nil)
    	if err != nil {
    		log.Fatal(err)
    	}
    	if res.TriggerEventResponseDto != nil {
    		// handle response
    	}
    }
    ```
  </Tab>
</Tabs>


# Novu Server Side SDKs documentation (/platform/sdks/server)

Explore Novu's comprehensive collection of server-side SDKs for seamless notification integration across multiple programming languages

import { Card, Cards } from 'fumadocs-ui/components/card';
import { DotnetIcon } from '@/components/icons/dotnet';
import { GolangIcon } from '@/components/icons/golang';
import { JavaIcon } from '@/components/icons/java';
import { LaravelIcon } from '@/components/icons/laravel';
import { PhpIcon } from '@/components/icons/php';
import { PythonIcon } from '@/components/icons/python';
import { RubyIcon } from '@/components/icons/ruby';
import { KotlinIcon } from '@/components/icons/kotlin';
import { TypescriptIcon } from '@/components/icons/typescript';

## Server Side SDKs

Novu's server-side SDKs simplify the integration with Novu's REST API.

### Offical SDKs maintained by Novu:

<Cards cols={2}>
  <Card title="Typescript (Official)" icon={<TypescriptIcon />} color="#ea5a0c" href="/platform/sdks/server/typescript">
    Connect your JS/TS app to Novu via the Typescript SDK.
  </Card>

  <Card title="Python (Official)" icon={<PythonIcon />} color="#dc2626" href="/platform/sdks/server/python">
    Connect your Python app to Novu via the Python SDK.
  </Card>

  <Card title="Go (Official)" icon={<GolangIcon />} color="#0285c7" href="/platform/sdks/server/go">
    Connect your Golang app to Novu via the Go SDK.
  </Card>

  <Card title="PHP (Official)" icon={<PhpIcon />} color="#16a34a" href="/platform/sdks/server/php">
    Connect your PHP app to Novu via the PHP SDK.
  </Card>

  <Card title=".NET (Official)" icon={<DotnetIcon />} color="#dc2626" href="/platform/sdks/server/dotnet">
    Connect your C#/.NET app to Novu via the .NET SDK.
  </Card>

  <Card title="Java (Official)" icon={<JavaIcon />} color="#dc2626" href="/platform/sdks/server/java">
    Connect your Java app to Novu via the Java SDK.
  </Card>
</Cards>

### SDKs maintained by the community:

<Cards cols={2}>
  <Card title="Laravel (Community)" icon={<LaravelIcon />} color="#dc2626" href="/platform/sdks/server/laravel">
    Connect your Laravel app to Novu via the Laravel SDK.
  </Card>

  <Card title="Kotlin (Community)" icon={<KotlinIcon />} color="#dc2626" href="/platform/sdks/server/kotlin">
    Connect your Kotlin app to Novu via the Kotlin SDK.
  </Card>

  <Card title="Ruby (Community)" icon={<RubyIcon />} color="#dc2626" href="/platform/sdks/server/ruby">
    Connect your Ruby app to Novu via the Ruby SDK.
  </Card>
</Cards>


# Novu Java SDK (/platform/sdks/server/java)

Connect a Java application to Novu

Novu's Java SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Java application.

[Explore the source code on GitHub.](https://github.com/novuhq/novu-java)

## Installation

JDK 11 or later is required.

Maven users:

```xml
<dependency>
    <groupId>co.novu</groupId>
    <artifactId>novu-java</artifactId>
    <version>LATEST</version>
</dependency>
```

The latest version can be found [on GitHub.](https://github.com/novuhq/novu-java#sdk-installation)

Gradle users:

```groovy
implementation 'co.novu:novu-java:LATEST'
```

Sync your project, and you should have the artifacts downloaded.

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```java
    package hello.world;

    import co.novu.Novu;
    import co.novu.models.components.*;
    import co.novu.models.errors.*;
    import co.novu.models.operations.EventsControllerTriggerResponse;
    import java.lang.Exception;
    import java.util.Map;

    public class Application {

        public static void main(String[] args) throws PayloadValidationExceptionDto, ErrorDto, ValidationErrorDto, Exception {

            Novu sdk = Novu.builder()
                    .secretKey("YOUR_SECRET_KEY_HERE")
                .build();

            EventsControllerTriggerResponse res = sdk.trigger()
                    .body(TriggerEventRequestDto.builder()
                        .workflowId("workflow_identifier")
                        .to(To2.of("SUBSCRIBER_ID"))
                        .payload(Map.ofEntries(
                            Map.entry("comment_id", "string"),
                            Map.entry("post", Map.ofEntries(
                                Map.entry("text", "string")))))
                        .overrides(TriggerEventRequestDtoOverrides.builder()
                            .build())
                        .actor(TriggerEventRequestDtoActor.of("<value>"))
                        .context(Map.ofEntries(
                            Map.entry("tenant", TriggerEventRequestDtoContextUnion.of("org-acme"))))
                        .build())
                    .call();

            if (res.triggerEventResponseDto().isPresent()) {
                // handle response
            }
        }
    }
    ```
  </Tab>

  <Tab value="EU Region">
    ```java
    package hello.world;

    import co.novu.Novu;
    import co.novu.models.components.*;
    import co.novu.models.errors.*;
    import co.novu.models.operations.EventsControllerTriggerResponse;
    import java.lang.Exception;
    import java.util.Map;

    public class Application {

        public static void main(String[] args) throws PayloadValidationExceptionDto, ErrorDto, ValidationErrorDto, Exception {

            Novu sdk = Novu.builder()
                    .serverUrl("https://eu.api.novu.co")
                    .secretKey("YOUR_SECRET_KEY_HERE")
                .build();

            EventsControllerTriggerResponse res = sdk.trigger()
                    .body(TriggerEventRequestDto.builder()
                        .workflowId("workflow_identifier")
                        .to(To2.of("SUBSCRIBER_ID"))
                        .payload(Map.ofEntries(
                            Map.entry("comment_id", "string"),
                            Map.entry("post", Map.ofEntries(
                                Map.entry("text", "string")))))
                        .overrides(TriggerEventRequestDtoOverrides.builder()
                            .build())
                        .actor(TriggerEventRequestDtoActor.of("<value>"))
                        .context(Map.ofEntries(
                            Map.entry("tenant", TriggerEventRequestDtoContextUnion.of("org-acme"))))
                        .build())
                    .call();

            if (res.triggerEventResponseDto().isPresent()) {
                // handle response
            }
        }
    }
    ```
  </Tab>
</Tabs>


# Novu Kotlin SDK (/platform/sdks/server/kotlin)

Connect a Kotlin application to Novu

<Callout type="warn">
  This SDK is community maintained. Feel free to contribute on our [GitHub
  repository](https://github.com/novuhq/novu-kotlin).
</Callout>

Novu's Kotlin SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Kotlin application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-kotlin)

## Installation

Maven users:

```xml
<dependency>
  <groupId>co.novu</groupId>
  <artifactId>novu-kotlin</artifactId>
  <version>{use-latest-version}</version>
</dependency>
```

The latest version can be found [on GitHub.](https://github.com/novuhq/novu-kotlin#installation)

Gradle users:

```groovy
implementation 'co.novu:novu-kotlin:{use-latest-version}' //Groovy

implementation ("co.novu:novu-kotlin:{use-latest-version}") //Kotlin
```

Sync your project, and you should have the artifacts downloaded.

## Usage

```kotlin

// without changing the backend URL
import co.novu.Novu
import co.novu.extentions.environments

fun main() {
    val novu = Novu(apiKey = "NOVU_SECRET_KEY")
    val environment = novu.environments()
    println(environment)
}

```


# Novu Laravel SDK (/platform/sdks/server/laravel)

Connect a Laravel application to Novu

<Callout type="warn">
  This SDK is community maintained. Feel free to contribute on our [GitHub
  repository](https://github.com/novuhq/novu-laravel).
</Callout>

Novu's Laravel SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Laravel application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-laravel)

## Installation

```php
composer require novu/novu-laravel
```

<Callout type="info">
   If you're ready to start integrating in your Laravel app, jump straight to our [Laravel
  quickstart.]()
</Callout>

## Usage

```php
use Novu\Laravel\Facades\Novu;

$response = Novu::triggerEvent([
    'name' => '<WORKFLOW_TRIGGER_IDENTIFIER_FROM_DASHBOARD>',
    'payload' => ['customVariables' => 'Hello'],
    'to' => [
        'subscriberId' => '<SUBSCRIBER_ID_FROM_DASHBOARD>',
        'phone' => '07983887777'
    ]
])->toArray();

// or you can use the novu() helper function like so:
novu()->triggerEvent([
    'name' => '<WORKFLOW_TRIGGER_IDENTIFIER_FROM_DASHBOARD>',
    'payload' => ['customVariables' => 'Hello'],
    'to' => [
        'subscriberId' => '<SUBSCRIBER_ID_FROM_DASHBOARD>',
        'phone' => '07983887777'
    ]
])->toArray();
```


# PHP SDK for Novu (/platform/sdks/server/php)

Connect a PHP application to Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Novu's PHP SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your PHP application.

[Explore the source code on GitHub](https://github.com/novuhq/php-novu)

## Installation

The SDK relies on [Composer](https://getcomposer.org/) to manage its dependencies.

To install the SDK and add it as a dependency to an existing composer.json file:

```bash
composer require "novuhq/novu"
```

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```php
    declare(strict_types=1);
     
    require 'vendor/autoload.php';
     
    use novu;
    use novu\Models\Components;
     
    $sdk = novu\Novu::builder()
        ->setSecurity(
            '<YOUR_SECRET_KEY_HERE>'
        )
        ->build();
     
    $triggerEventRequestDto = new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\SubscriberPayloadDto(
            subscriberId: 'subscriber_unique_identifier',
            firstName: 'Albert',
            lastName: 'Einstein',
            email: 'albert@einstein.com',
        ),
        payload: [
            'comment_id' => 'string',
            'post' => [
                'text' => 'string',
            ],
        ],
        overrides: [
            'email' => [
                'bcc' => 'no-reply@novu.co',
            ],
        ],
    );
     
    $response = $sdk->trigger(
        triggerEventRequestDto: $triggerEventRequestDto,
        idempotencyKey: '<value>'
     
    );
     
    if ($response->triggerEventResponseDto !== null) {
        // handle response
    }
    ```
  </Tab>

  <Tab value="EU Region">
    ```php
    declare(strict_types=1);

    require 'vendor/autoload.php';

    use novu;
    use novu\Models\Components;

    $sdk = novu\Novu::builder()
        ->setServerURL('https://eu.api.novu.co')
        ->setSecurity(
            '<YOUR_SECRET_KEY_HERE>'
        )
        ->build();

    $triggerEventRequestDto = new Components\TriggerEventRequestDto(
        workflowId: 'workflow_identifier',
        to: new Components\SubscriberPayloadDto(
            subscriberId: 'subscriber_unique_identifier',
            firstName: 'Albert',
            lastName: 'Einstein',
            email: 'albert@einstein.com',
        ),
        payload: [
            'comment_id' => 'string',
            'post' => [
                'text' => 'string',
            ],
        ],
        overrides: [
            'email' => [
                'bcc' => 'no-reply@novu.co',
            ],
        ],
    );

    $response = $sdk->trigger(
        triggerEventRequestDto: $triggerEventRequestDto,
        idempotencyKey: '<value>'

    );

    if ($response->triggerEventResponseDto !== null) {
        // handle response
    }
    ```
  </Tab>
</Tabs>


# Novu Python SDK (/platform/sdks/server/python)

Connect a Python application to Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Novu's Python SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Python application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-py)

## Installation

<Tabs items={['PIP', 'Poetry', 'Shell and script usage with uv']}>
  <Tab value="PIP">
    PIP is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

    ```bash
    pip install novu-py
    ```
  </Tab>

  <Tab value="Poetry">
    Poetry is a modern tool that simplifies dependency management and package publishing by using a single pyproject.toml file to handle project metadata and dependencies.

    ```bash
    poetry add novu-py
    ```
  </Tab>

  <Tab value="Shell and script usage with uv">
    You can use this SDK in a Python shell with uv and the uvx command that comes with it like so:

    ```bash
    uvx --from novu-py python
    ```

    It's also possible to write a standalone Python script without needing to set up a whole project like so:

    ```python
    #!/usr/bin/env -S uv run --script
    # /// script
    # requires-python = ">=3.9"
    # dependencies = [
    #     "novu-py",
    # ]
    # ///

    from novu_py import Novu

    sdk = Novu(
      # SDK arguments
    )

    # Rest of script here...
    ```

    Once that is saved to a file, you can run it with uv run `script.py` where `script.py` can be replaced with the actual file name.
  </Tab>
</Tabs>

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    <Tabs items={['Synchronous', 'Asynchronous']}>
      <Tab value="Synchronous">
        ```python
        import novu_py
        from novu_py import Novu
        import os

        with Novu(
        secret_key=os.getenv("NOVU_SECRET_KEY", ""),
        ) as novu:

            res = novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
                workflow_id="workflow_identifier",
                to={
                    "subscriber_id": "subscriber_unique_identifier",
                    "first_name": "Albert",
                    "last_name": "Einstein",
                    "email": "albert@einstein.com",
                },
                payload={
                    "comment_id": "string",
                    "post": {
                        "text": "string",
                    },
                },
                overrides={
                  "email": {
                    "bcc": "no-reply@novu.co"
                  }
                },
            ))

            # Handle response
            print(res)

        ```
      </Tab>

      <Tab value="Asynchronous">
        ```python
        import asyncio
        import novu_py
        from novu_py import Novu
        import os

        async def main():
        async with Novu(
        secret_key=os.getenv("NOVU_SECRET_KEY", ""),
        ) as novu:

                res = await novu.trigger_async(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
                    workflow_id="workflow_identifier",
                    to={
                        "subscriber_id": "subscriber_unique_identifier",
                        "first_name": "Albert",
                        "last_name": "Einstein",
                        "email": "albert@einstein.com",
                    },
                    payload={
                        "comment_id": "string",
                        "post": {
                            "text": "string",
                        },
                    },
                    overrides={
                      "email": {
                        "bcc": "no-reply@novu.co",
                      }
                    },
                ))

                # Handle response
                print(res)

        asyncio.run(main())
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="EU Region">
    ```python
    import novu_py
    from novu_py import Novu
    import os

    with Novu(
    server_url="https://eu.api.novu.co",
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
    ) as novu:

        res = novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
            workflow_id="workflow_identifier",
            to={
                "subscriber_id": "subscriber_unique_identifier",
            },
            payload={
                "comment_id": "string",
                "post": {
                    "text": "string",
                },
            },
            overrides={
              "email": {
                "bcc": "no-reply@novu.co"
              }
            },
        ))

        # Handle response
        print(res)

    ```
  </Tab>
</Tabs>

```
```


# Novu Ruby SDK (/platform/sdks/server/ruby)

Connect a Ruby application to Novu

<Callout type="warn">
  This SDK is community maintained. Feel free to contribute on our [GitHub
  repository](https://github.com/novuhq/novu-ruby).
</Callout>

Novu's Ruby SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code that integrates seamlessly with your Ruby application.

[Explore the source code on GitHub](https://github.com/novuhq/novu-ruby)

## Installation

```bash
gem install novu
```

## Usage

```ruby
require 'novu'

client = Novu::Client.new(access_token: 'YOUR_NOVU_API_TOKEN')

payload = {
    'name' => 'Trigger1',
    'payload' => { # optional
        'first-name' => 'Adam' # optional
    },
    'to' => {
        'subscriberId' => '7789'
    },
    'transactionId' => '89kjfke9893' #optional
}

client.trigger_event(payload)
```


# Novu Typescript SDK (/platform/sdks/server/typescript)

Connect a TS/JS application to Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Novu's Typescript SDK provides simple, yet comprehensive notification management, and delivery capabilities through multiple channels that you can implement using code. It integrates seamlessly with your Node.js, Bun, Deno, and Cloudflare Workers applications.

[Explore the source code on GitHub](https://github.com/novuhq/novu-ts)

## Installation

<Tabs items={['NPM', 'PNPM', 'Yarn', 'Bun']}>
  <Tab value="NPM">
    ```bash
    npm add @novu/api
    ```
  </Tab>

  <Tab value="PNPM">
    ```bash
    pnpm add @novu/api
    ```
  </Tab>

  <Tab value="Yarn">
    ```bash
    yarn add @novu/api zod@^3

    ## Note that Yarn does not install peer dependencies automatically. You will need

    ## to install zod as shown above.

    ```
  </Tab>

  <Tab value="Bun">
    ```bash
    bun add @novu/api
    ```
  </Tab>
</Tabs>

## Usage

<Tabs items={['US Region', 'EU Region']}>
  <Tab value="US Region">
    ```typescript
    import { Novu } from "@novu/api";

    const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

    async function run() {
      const result = await novu.trigger({
        to: {
          subscriberId: "subscriber_unique_identifier",
          firstName: "Albert",
          lastName: "Einstein",
          email: "albert@einstein.com",
          phone: "+1234567890",
        },
        workflowId: "workflow_identifier",
        payload: {
          comment_id: "string",
          post: {
            text: "string",
          },
        },
        overrides: {
          email: {
            bcc: "no-reply@novu.co",
          },
        },
      });
    }

    run();
    ```
  </Tab>

  <Tab value="EU Region">
    ```javascript
    import { Novu } from "@novu/api";

    const novu = new Novu({
      secretKey: "<YOUR_SECRET_KEY_HERE>",
      serverUrl: "https://eu.api.novu.co",
    });

    async function run() {
      const result = await novu.trigger({
        to: {
          "subscriberId": "subscriber_unique_identifier",
          "firstName": "Albert",
          "lastName": "Einstein",
          "email": "albert@einstein.com",
          "phone": "+1234567890",
        },
        workflowId: "workflow_identifier",
        payload: {
          "comment_id": "string",
          "post": {
            "text": "string",
          },
        },
        overrides: {
          "email": {
            "bcc": "no-reply@novu.co"
          },
        },
      });

      // Handle the result
      console.log(result);
    }

    run();
    ```
  </Tab>
</Tabs>

## Sending custom header

To send custom headers, you can use the `HTTPClient` class. Read more on how to configure custom [http client](https://github.com/novuhq/novu-ts?tab=readme-ov-file#custom-http-client).

```typescript
import { Novu } from "@novu/api";
import { HTTPClient } from "@novu/api/lib/http";

const httpClient = new HTTPClient();

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request);
  nextRequest.headers.set("x-custom-header", "custom-header-value");

  return nextRequest;
});

const novu = new Novu({
  httpClient,
  secretKey: "SECRET_KEY_VALUE",
  serverURL: "https://eu.api.novu.co",
});

novu.trigger({
  workflowId: "WORKFLOW_ID_VALUE",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    message: "Hello, world!",
  },
});
```


# How to configure code steps in a workflow (/platform/workflow/add-and-configure-steps/code-steps)

Learn how to add code steps to a workflow, publish them with the Novu CLI, and use code-managed steps with UI-managed steps in a workflow.

Novu allows you to write step handlers as TypeScript code in your project and publish them to Novu as serverless functions. Instead of configuring notification content in a visual editor, you define a handler file that returns the output for your step. Novu calls it at send time with the subscriber data, trigger payload, and any dashboard-defined controls.

You can create both UI-managed steps and code-managed steps within the same workflow.

## Supported channels

| Channel | Required Output                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------- |
| Email   | `subject`, `body` (HTML string)                                                                    |
| SMS     | `body`                                                                                             |
| Push    | `subject`, `body`                                                                                  |
| Chat    | `body`                                                                                             |
| In-App  | `subject`, `body` (plus optional `avatar`, `primaryAction`, `secondaryAction`, `data`, `redirect`) |

## Quick Start

### 1. Create workflow and step in the UI

Create a workflow and add any channel step in the workflow from UI. Once the step is added. Go to the step editor and Toggle the switch to **Custom Code** from **Editor** option to enable custom code for this step.

![Create workflow and step in the UI](/images/workflows/add-and-configure-steps/code/create-step.gif)

### 2. Get the CLI command from the dashboard

The Novu dashboard shows a prefilled publish command in the step editor screen, click on the **Copy** button to copy the command. It includes your secret key, workflow ID, step ID, and API URL.

### 3. Run the CLI command in your project

```bash
npx novu step publish \
  --workflow your-workflow-id \
  --step your-step-id \
  --secret-key nv-sk-...
```

The CLI supports the following flags and options:

| Flag                      | Type                | Default                         | Description                                                                                                                                                    |
| ------------------------- | ------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-s, --secret-key <key>`  | string              | `$NOVU_SECRET_KEY`              | Novu API secret key                                                                                                                                            |
| `-a, --api-url <url>`     | string              | config or `https://api.novu.co` | Novu API URL                                                                                                                                                   |
| `--config <path>`         | string              | `novu.config.ts`                | Path to config file                                                                                                                                            |
| `--out <path>`            | string              | from config or `./novu`         | Directory containing handlers                                                                                                                                  |
| `--workflow <id>`         | string (repeatable) | all                             | Deploy only steps for specific workflow(s)                                                                                                                     |
| `--step <id>`             | string (repeatable) | all                             | Deploy only a specific step within a workflow                                                                                                                  |
| `--template <path>`       | string              | —                               | Path to a React Email template; scaffolds a React Email email handler if the step file doesn't exist. Requires `--workflow` and `--step` (single values each). |
| `--bundle-out-dir [path]` | string or boolean   | —                               | Write bundle artifacts to disk (debug mode, skips minification)                                                                                                |
| `--dry-run`               | boolean             | `false`                         | Bundle without deploying                                                                                                                                       |

The CLI will perform the following:

1. Look up the step type from the Novu API.
2. Auto-scaffold a placeholder handler at `novu/<workflowId>/<stepId>.step.tsx`.
3. Bundle all handlers in the `novu/` directory.
4. Deploy to Novu.

For email steps, you can optionally link a React Email template directly:

```bash
npx novu step publish \
  --workflow your-workflow-id \
  --step your-step-id \
  --template ./emails/welcome.tsx \
  --secret-key nv-sk-...
```

If you dont want to pass secret key to CLI, it will try to read NOVU\_SECRET\_KEY variable from `.env` file if present.

Also similarly for `apiUrl`, by default it uses US, but you can specify EU or other regions either in novu.config.ts or directly in CLI command.

### 4. Edit the handler

The generated file will be located at `novu/<workflowId>/<stepId>.step.tsx`. The folder name is the `workflowId`. The CLI reads it from the path at publish time. You should commit this file to your repository.

Open the generated file and replace the placeholder content with your real logic. Each handler receives the full context:

```typescript title="novu/workflow-id/step-id.step.tsx"
export default step.inApp(
  "in-app-step",
  async (controls, { payload, subscriber }) => ({
    subject: controls.subject,
    body: `Hi ${subscriber.firstName}, ${controls.body} `,
  }),
  {
    controlSchema: {
      type: "object",
      properties: {
        subject: { type: "string", default: "New activity" },
        body: { type: "string", default: "You have a new notification." },
      },
      additionalProperties: false,
    } as const,
  }
);
```

### 5. Republish when you make changes

```bash
npx novu step publish
```

If the bundle content changed, Novu deploys a new version. This `publish` command by default will publish all step handler in novu folder, if you want to publish just one workflow or one step you can specify `--workflow` and `--step` flags

## Defining Controls (Optional)

Controls allow dashboard users to override specific values without changing code. You can define a `controlSchema` using Zod or plain JSON Schema:

```typescript
import { step } from '@novu/framework/step-resolver';
import { z } from 'zod';

export default step.sms(
  'send-sms',
  async (controls, { subscriber }) => ({
    body: `${controls.greeting} ${subscriber.firstName ?? 'there'}, ${controls.message}`,
  }),
  {
    controlSchema: z.object({
      greeting: z.string().default('Hello'),
      message: z.string().default('You have a new notification.'),
    }),
  }
);
```

After publishing, the dashboard renders form fields for each control property.

### Controls vs Payload

| Property    | Controls                                         | Payload                                 |
| ----------- | ------------------------------------------------ | --------------------------------------- |
| Set by      | Dashboard users (with code-defined defaults)     | Your application at trigger time        |
| Purpose     | Content overrides (subject lines, toggles, copy) | Dynamic data (username, order ID, etc.) |
| Defined via | `controlSchema` in the step handler              | `payloadSchema` (types only)            |

## Skipping a Step Conditionally

Use `skip` to prevent a step from executing at runtime based on your logic. The function receives `(controls, ctx)` where `ctx` contains `payload`, `subscriber`, `context`, and `steps`.

```typescript
export default step.sms(
  'send-sms',
  async (controls, { payload }) => ({
    body: `You have a new message: ${payload.text}`,
  }),
  {
    skip: (controls, { payload }) => payload.optedOutOfSms === true,
  }
);
```

<Callout type="info">
  `skip` is not called during preview. You will always see the step output in the dashboard preview regardless of the skip condition.
</Callout>

## Provider Overrides

Provider overrides let you customize the raw request sent to the underlying notification provider for a step. This is useful for setting provider-specific options not exposed by Novu standard output schema.

```typescript
import { step } from '@novu/framework/step-resolver';

export default step.email(
  'welcome-email',
  async (controls, { payload }) => ({
    subject: 'Welcome!',
    body: `<p>Hello ${payload.name}</p>`,
  }),
  {
    providers: {
      sendgrid: ({ outputs }, ctx) => ({
        _passthrough: {
          body: {
            categories: ['onboarding'],
            asm: { group_id: 12345 },
          },
        },
      }),
    },
  }
);
```

The `_passthrough` field merges directly into the API body sent to the provider. You can also set `headers` and `query` for header and query string overrides.

## Disabling Output Sanitization

Novu sanitizes HTML in `email` and `in_app` outputs by default to prevent XSS vulnerabilities. To opt out, you can set `disableOutputSanitization`:

```typescript
export default step.email(
  'raw-html-email',
  async (controls, { payload }) => ({
    subject: 'Your report',
    body: payload.htmlContent,
  }),
  {
    disableOutputSanitization: true,
  }
);
```

## Configuration File (Optional)

You can create a `novu.config.ts` file for advanced use cases:

```typescript
// novu.config.ts
const config = {
  outDir: './novu',
  apiUrl: 'https://api.novu.co',
  aliases: {
    '@emails': './src/emails',
  },
};

export default config;
```

## TypeScript Support

You can install `@novu/framework` as a dev dependency to get full TypeScript types for `controls`, `payload`, `subscriber`, `context`, and `steps`:

```bash
npm install --save-dev @novu/framework
```

<Callout type="info">
  The CLI publishes to non production environments only. Publishing directly to Production is blocked. To promote changes to Production, use the **Publish changes** button in the Novu dashboard.
</Callout>

## Troubleshooting

| Problem                                              | Solution                                                                                |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| "Publishing to Production is not allowed"            | Use your Development environment's secret key. Promote to Production via the dashboard. |
| "Template file not found"                            | Check the `--template` path is correct relative to your current directory.              |
| "Workflow not found" / "Step not found"              | Create the workflow and step in the Novu dashboard before publishing.                   |
| Authentication failed (401)                          | Verify your secret key is correct.                                                      |
| Bundle too large (>10 MB)                            | Reduce dependencies or publish specific workflows with `--workflow`.                    |
| No step files found                                  | Run with `--workflow=<id> --step=<id>` to scaffold, or create the file manually.        |
| Preview not updating in dashboard                    | Republish your handler. The dashboard polls every 3 seconds.                            |
| Controls not appearing in dashboard                  | Export a `controlSchema` in your step handler and republish.                            |
| `--step requires --workflow`                         | The `--step` flag must always be paired with `--workflow`.                              |
| Provider output rejected (`INVALID_PROVIDER_OUTPUT`) | Check that your `providers` function returns values matching the provider schema.       |
| `skip` not working in preview                        | By design, `skip` is only evaluated at send time, not during dashboard preview.         |


# How to add and configure Workflow Steps (/platform/workflow/add-and-configure-steps)

Learn how workflow steps work in Novu, the different step types available, and how to add and execute steps in a notification workflow.

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Bell, Mail, MessageSquare, MessagesSquare, Smartphone } from 'lucide-react';

Steps are the building blocks of a workflow. Each step represents a distinct action or delivery mechanism that determines what happens, when it happens, and how a notification is delivered.

A workflow is built as a sequence of steps, executed linearly from top to bottom. You define and arrange steps using the workflow editor in the Novu dashboard, where each node on the canvas represents a single step in the execution flow.

Each step operates independently. If one step fails, other steps in the workflow can still succeed. Workflows support two types of steps from the Novu dashboard.

![Types of steps](/images/workflows/add-and-configure-steps/steps.png)

<Callout>You can create a custom step using Novu Framework. For more information, refer to the [Custom steps](/framework/custom).</Callout>

## Channel steps

Channel steps deliver notifications to users through supported communication channels. Each channel step includes its own template editor for defining notification content and channel-specific behavior.

Supported channel types include:

<Cards>
  <Card title="Email" icon={<Mail className="h-4 w-4" />} href="/platform/integrations/email" description="Send notifications to your subscribers’ email. Supports layouts, visual block editing, custom HTML, and dynamic data." />

  <Card title="In-App" icon={<Bell className="h-4 w-4" />} href="/platform/inbox" description="Deliver notifications directly inside your application through the Novu <Inbox/>." />

  <Card title="Push" icon={<Smartphone className="h-4 w-4" />} href="/platform/integrations/push" description="Send notifications to user devices, either mobile, desktop, or web." />

  <Card title="SMS" icon={<MessageSquare className="h-4 w-4" />} href="/platform/integrations/sms" description="Send notification to your subscribers’ devices." />

  <Card title="Chat" icon={<MessagesSquare className="h-4 w-4" />} href="/platform/integrations/chat" description="Send notifications to chat platforms such as Slack or Microsoft Teams." />
</Cards>

To send notifications through Email, Push, Chat, or SMS channels, you must configure the appropriate [channel provider integration](/platform/integrations) for your environment. Without an active integration, messages sent through that channel won’t be delivered.

<Callout>Novu provides built-in [demo integrations](/platform/integrations/demo-integration) for the Email and SMS channels. These sandboxed providers let you test workflows before configuring a provider.</Callout>

## Action steps

Action steps introduce logic and flow control into a workflow. They do not send notifications directly, but instead affect when and how downstream steps execute. Action steps are typically placed before or between channel steps to shape delivery behavior.

### Delay

The Delay step pauses workflow execution for a specified duration before continuing to the next step.

Delay is used when timing matters, whether you need to wait a fixed amount of time, resume execution at a scheduled moment, or defer execution based on data from the trigger payload. This is useful for use cases such as:

* Waiting for X amount of time before sending the message.
* Waiting for a short period before sending a push message in case the user has seen the notification in the Inbox component.
* Sending a reminder email 24 hours after a user abandons their shopping cart to encourage checkout completion.
* Sending a follow-up message 3 days after user registration to check if they need onboarding assistance.

**How does Delay work?**

When a workflow reaches a Delay step:

1. Execution pauses for the configured duration or until the scheduled time.
2. Once the delay condition is satisfied, the workflow continues to the next step.
3. All downstream steps execute normally unless blocked by conditions or other controls.

Steps placed before the Delay step run immediately. Steps placed after the Delay step run only after the delay completes.

Delay can be added anywhere in a workflow and can be conditionally skipped using step conditions.

<Callout>To learn how to configure delay types and scheduling behavior, refer to the [Configure Delay Step](/platform/workflow/add-and-configure-steps/configure-action-steps/delay) documentation.</Callout>

### Digest

The Digest step controls how often downstream steps execute by batching multiple workflow trigger events into a single execution.

Instead of running the workflow once per event, Digest collects events over time, groups them per subscriber, and then allows the workflow to continue once per digest window. Use Digest to

* Prevent over-notifying users during bursts of activity
* Replace many similar notifications with a single summary
* Batch repeated events that occur within a short period
* Deliver notifications on a fixed cadence (for example, daily or weekly summaries)

**How does Digest work?**

When a Digest step is added:

1. Workflow trigger events are collected instead of immediately flowing downstream.
2. Events are grouped per subscriber (and optional grouping key).
3. Once the digest window completes, the workflow continues once, with the aggregated events available as context.

![Digest Engine](/images/workflows/add-and-configure-steps/digest-engine.png)

Steps placed before the Digest step execute in real time. Steps placed after the Digest step execute only when the digest duration is completed.

<Cards>
  <Card href="/platform/workflow/add-and-configure-steps/configure-action-steps/digest" title="Configure Digest step">
    Learn how to configure Digest windows, group rules, and schedule behavior.
  </Card>

  <Card href="/platform/workflow/add-notification-content/personalize-content#digest-variables" title="Use digest data">
    Learn how to use the result from a Digest step to personalize content in the channel step editor.
  </Card>
</Cards>

### Throttle

The Throttle step lets you limit the number of workflow executions within a specified time window. You can configure throttling directly in Novu workflow editor. By setting limits, you can prevent subscribers from receiving duplicate or excessive notifications when a trigger fires repeatedly.

![Throttle](/images/workflows/add-and-configure-steps/throttle.png)

Some use cases for this include:

* Limiting high-frequency alerts (such as CPU or billing usage checks) to one notification per hour, day, or week.
* Preventing duplicate messages from automated cron jobs or recurring triggers.
* Controlling notification frequency for subscribers who belong to multiple projects or contexts.

**How does Throttle work?**

At a high level, the throttle step counts the number of times a workflow is triggered for a specific subscriber.

* If the count is within the defined execution threshold for the time window, then the workflow proceeds as normal.
* If the count exceeds the threshold, then the workflow execution is halted at the throttle step. Any steps placed after the throttle step in your workflow will not be run. For example, if you have an email step following a throttle step, then that email will not be sent once the limit is reached.
  ![Throttle feed activity feed](/images/workflows/add-and-configure-steps/throttle-step-activity-feed.png)

Throttling applies consistently across channels, whether the workflow sends email, in-app, SMS, chat, or push notifications.

The throttle step applies to all workflows, including those marked as critical. If a critical workflow is triggered more frequently than the throttle limit allows, then it will be skipped just like any other workflow. This ensures that even high-priority alerts do not overwhelm a subscriber.

To the subscriber, the experience is transparent. They are not aware that any throttling has occurred; they either receive a notification or they don’t. The subscriber is never exposed to information about the throttle itself.

<Callout>To learn how to configure throttle windows, thresholds, and grouping behavior, refer to the [Configure Throttle Step](/platform/workflow/add-and-configure-steps/configure-action-steps/throttle) documentation.</Callout>

### HTTP

The HTTP step allows workflows to call external APIs during execution. It provides a native way to interact with systems outside of Novu directly from your workflows without relying on external webhooks or custom infrastructure.

This is useful for use cases such as:

* Fetching additional user or event data from your internal databases to enrich notifications.
* Determining if a user has an active premium subscription before sending a specific promotional email.
* Pinging an internal delivery system or observability tool with workflow context.

**How does HTTP work?**

When a workflow reaches an HTTP step:

1. The workflow pauses momentarily to execute the configured HTTP request (e.g., `GET`, `POST`, `PUT`).
2. Contextual data like subscriber information or previous step results can be injected into the request URL, headers, or body using LiquidJS.
3. Once the API responds, the response data is stored as a step result.
4. Downstream steps and conditions can consume the stored response data to personalize content or branch workflow execution.

If the HTTP request fails (e.g., due to a network timeout or a non-2xx status code), the workflow can either halt or continue execution based on how you configure the failure behavior.

<Callout>To learn how to configure the request, test endpoints, and consume API responses, refer to the [Configure HTTP Step](/platform/workflow/add-and-configure-steps/configure-action-steps/http-step) documentation.</Callout>

## Add a step to a workflow

You add steps from the Workflow Editor when building or editing a workflow.

The first step in every workflow is the Workflow Trigger, which represents the event that starts the workflow.

To add steps:

1. Open a workflow in the Workflow Editor.
2. Click the **+** (Add step) icon at the desired position.
3. Select a step type from the available options.
4. Configure the step if required.

![Add steps](/images/workflows/add-and-configure-steps/add-step.gif)

You can add multiple steps and reorder them at any time to change the execution flow.

## How steps execute

When a workflow is triggered:

* Steps execute sequentially, from top to bottom.
* Each step receives the same workflow payload.
* A step must complete before the next step begins.

This execution model allows you to build complex notification sequences that adapt to timing, user behavior, and delivery requirements such as:

1. Send an in-App message.
2. Wait 24 hours (Delay).
3. If the in-app message is unread, send an email.
4. If the subscriber is a premium user, then follow up with an SMS message.

This allows Novu workflows to adapt to user behavior and preferences while keeping the configuration visual and testable.


# Step Conditions (/platform/workflow/add-and-configure-steps/step-conditions)

Create dynamic notification workflows using rule-based conditions. Control message delivery based on subscriber, payload, and workflow data.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Step conditions let you control whether a workflow step runs or is skipped. They allow you to build adaptive notification flows that respond to subscriber attributes, payload schema data, and outcomes from previous steps.

Conditions are configured per step and apply to both channel steps and action steps.

## Add step conditions

You configure step conditions from the Workflow Editor.

1. Select a step in the Workflow Editor.
2. In the **Configure** step panel, click **Step Conditions**.
   ![Step conditions](/images/workflows/add-and-configure-steps/step-conditions/step-conditions.png)
3. Proceed to add your step conditions.

![Step conditions](/images/workflows/add-and-configure-steps/step-conditions/step-conditions.gif)

If the condition evaluates to `true`, the step runs. If it evaluates to `false`, the step is skipped and the workflow continues.

## How the condition builder works

The step condition builder is rule-based and composed of three core elements:

* **Logical operators**: Choose **AND** or **OR** to define how conditions are evaluated.
* **Conditions**: Individual rules that compare a field, an operator, and a value.
* **Condition groups**: Nested groups that allow more complex logic.

In the UI, you’ll see:

* **AND / OR** selector buttons
* **+ Add condition** to add a rule
* **Add group** to create nested condition groups

This structure allows you to model both simple checks and complex branching logic.

## Supported operators

The condition builder supports a wide range of comparison operators:

| Operator              | Description                             | Example                                         |
| --------------------- | --------------------------------------- | ----------------------------------------------- |
| `=`                   | Equal to                                | `subscriber.locale = "en-US"`                   |
| `!=`                  | Not equal to                            | `subscriber.isOnline != true`                   |
| `<`                   | Less than                               | `payload.totalAmount < 100`                     |
| `>`                   | Greater than                            | `payload.totalAmount > 100`                     |
| `<=`                  | Less than or equal to                   | `payload.totalAmount <= 200`                    |
| `>=`                  | Greater than or equal to                | `payload.totalAmount >= 200`                    |
| `contains`            | Contains a substring                    | `payload.orderId contains "123"`                |
| `begins with`         | Starts with                             | `subscriber.firstName begins with "J"`          |
| `ends with`           | Ends with                               | `subscriber.email ends with "@xyz.com"`         |
| `does not contain`    | Does not contain a substring            | `payload.orderId does not contain "456"`        |
| `does not begin with` | Does not start with                     | `subscriber.firstName does not begin with "M"`  |
| `does not end with`   | Does not end with                       | `subscriber.lastName does not end with "Smith"` |
| `is null`             | Is null                                 | `subscriber.phone is null`                      |
| `is not null`         | Is not null                             | `subscriber.email is not null`                  |
| `in`                  | Matches one of several values           | `subscriber.locale in ["en-US", "es-ES"]`       |
| `not in`              | Does not match any of the listed values | `subscriber.locale not in ["fr-FR", "de-DE"]`   |
| `between`             | Within a range                          | `payload.totalAmount between [50, 200]`         |
| `not between`         | Outside of a range                      | `payload.totalAmount not between [0, 50]`       |

## Data used for step conditions

Step conditions can evaluate data from several sources. Choose the source that best represents the decision you’re trying to make.

### Subscriber data

You can apply conditions on subscriber attributes so notifications only go to the right people. For example, send an SMS only when `subscriber.isOnline` is `false` (isOnline is a subscriber attribute that comes from whether the subscriber has an active Inbox session).

For custom fields you store on the subscriber (e.g. plan, preferences), use the full path to the property. For example, use `subscriber.data.subscription_plan` equals `premium` to run a step only for subscribers on the premium plan.

<Callout>To learn more about Subscribers model, refer to the [Subscribers documentation](/platform/concepts/subscribers)</Callout>

### Payload data

You can use data from the [payload schema](/platform/workflow/configure-workflow#payload-schema) or custom payload data passed during the workflow trigger call to the Novu API to configure step conditions. This allows you to define dynamic rules based on the data unique to each workflow execution.

Example payload data:

```json
{
  "orderId": "12345",
  "totalAmount": 150,
  "orderStatus": "completed"
}
```

You can configure conditions such as:

* `payload.orderStatus = "completed"`
* `payload.totalAmount > 100`

### Workflow variables

You can base conditions on workflow variables. These variables provide metadata about the workflow being executed and allow you to add conditional logic.

![Workflow step conditions](/images/workflows/add-and-configure-steps/step-conditions/workflow-step-conditions.png)

The following workflow variables are available:

* `{{workflow.name}}`: The name of the workflow.
* `{{workflow.description}}`: The description of the workflow.
* `{{workflow.tags}}`: An array of tags associated with the workflow.
* `{{workflow.severity}}`: The severity level (high, medium, low, none) of the workflow.
* `{{workflow.workflowId}}`: The unique identifier of the workflow.

### Previous step result

For workflows involving sequential steps, conditions can also depend on the outcome of a previous step. For example, if the prior step was an in-app notification, then the condition could check:

* `steps.in-app-step.seen`
* `steps.in-app-step.read`
* `steps.in-app-step.lastSeenDate`
* `steps.in-app-step.lastReadDate`

This can be used for follow-up notifications. For instance, send an email only if the in-app notification was not read within 24 hours.

### Context

You can use context variables in the **Step conditions** tab of a workflow step to add conditional logic to your notifications.

<Callout>To learn more about context, refer to the [Context documentation](/platform/workflow/advanced-features/contexts).</Callout>

### Dynamic data fields

The **value** field in a condition can also be a dynamic data field. This allows you to compare two data points dynamically rather than using static values.

For example:

```json
{
  "operator": "AND",
  "conditions": [
    {
      "field": "payload.foo",
      "operator": "=",
      "value": "{{payload.bar}}"
    }
  ]
}
```

In this case, the step will execute only if `payload.foo` is equal to `payload.bar` at runtime. This enables flexible condition logic based on real-time data comparisons.

<Callout title="Advanced application state calculations" type="info">For more complex scenarios where you need to perform advanced calculations based on your application state, you can use the [Novu Framework](/framework/typescript/steps).</Callout>


# Template Editors (/platform/workflow/add-notification-content/channels-template-editors)

Learn how to design and configure notification content for email, in-app, push, and SMS.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

The channel template editors are where you define the content of the notification that is delivered to your subscribers when a workflow runs.

Each channel exposes an editor aligned with how messages are delivered on that channel:

* **SMS and chat**: Body field only
* **Push, email, and in-app**: Subject and body fields

All editors (including the Subject field editors) support variables and dynamic data that can be used to [personalize notification content](/platform/workflow/add-notification-content/personalize-content). Notification preview is also supported on all editors.

While some channel editors share common features, some channels expose additional channel-specific features that can be used to configure and customize the notification content for that channel.

<Callout>Variables autocomplete is supported in all channel template editors</Callout>

## In-app template editor

The in-app template editor defines how notifications appear inside your application through the Novu <Method href="/platform/inbox">{`<Inbox />`}</Method>. In-app notifications are UI-driven, not just message-driven. This means that the template is responsible for both content and interaction.

<Callout>To learn how in-app notifications are rendered and displayed in your application, see the <Method href="/platform/inbox">{`<Inbox />`}</Method> documentation.</Callout>

The template editor lets you control what users see, how they act on it, and how it appears in your application and consists of the following configurable fields:

![Template fields](/images/workflows/add-notification-content/channels-template-editors/template-fields.gif)

### Disable content sanitization

By default, Novu sanitizes both the subject and body fields to prevent unsafe HTML from being rendered. This includes sanitizing:

* Suspicious HTML tags.
* HTML entities such as `<`, `>`, and `&`.

You should only disable content sanitization when:

* You fully trust the trigger payload.
* You control all dynamic data sources.

<Callout type="warn"> Disabling sanitization can expose your application to security risks such as XSS attacks. Only disable this option when using trusted data sources.</Callout>

### Avatar customization

You can control how the notification avatar is displayed using one of the following methods:

* Provide a custom avatar URL.
* Select from the available built-in icons.

![Customize Avatar](/images/workflows/add-notification-content/channels-template-editors/customize-avatar.gif)

### Action buttons

In-app notifications support primary and secondary actions. For each action, you can configure:

* Button text
* Redirect URL
* Navigation targets (`_self`, `_blank`, `_parent`, `_top`, and `_unfencedTop`)

![Action buttons](/images/workflows/add-notification-content/channels-template-editors/action-button.gif)

Actions allow users to respond directly from the Inbox without navigating elsewhere in the UI.

### Redirect URL

The redirect URL defines where the user is navigated when the notification itself is clicked.

You can:

* Define a static or dynamic URL.
* Control navigation behavior using targets.
* Omit the redirect URL and handle clicks using the `onNotificationClick` handler in the <Method href="/platform/inbox">{`<Inbox />`}</Method> component.

This enables full control over client-side navigation behavior.

### Data object

The data object is a customizable key-value store available in the in-app step. You can use it to extend each Inbox component notification by embedding custom data.

<Callout>To learn more about how to use the data object to customize how messages appear in the <Method href="/platform/inbox">{`<Inbox />`}</Method>, refer to the [Data Object](/platform/inbox/configuration/data-object) documentation.</Callout>

## Email template editor

The email template editor defines how email notifications are structured, rendered, and delivered. Novu dashboard provides multiple authoring modes:

<Callout>You can submit custom HTML email templates via the Novu API. This method supports workflows where you render templates externally and use Novu purely for delivery.</Callout>

### Block editor

The block editor is a `WYSIWYG` editor that allows you to create and edit email templates. It has two fields: subject and body.

A block can be added by clicking on the plus (+) icon in the top-left corner of body field or by adding a forward slash (`/`). In both cases, a menu appears with the list of supported blocks:

<Accordions type="single">
  <Accordion title="Supported Content Blocks">
    <ul>
      <li>Blockquote</li>
      <li>Bullet List</li>
      <li>Button</li>
      <li>Cards</li>
      <li>Columns</li>
      <li>Custom HTML code</li>
      <li>Divider</li>
      <li>Footers</li>
      <li>Hard Break</li>
      <li>Headers</li>
      <li>Heading 1</li>
      <li>Heading 2</li>
      <li>Heading 3</li>
      <li>Image</li>
      <li>Inline Image</li>
      <li>Numbered List</li>
      <li>Repeat</li>
      <li>Section</li>
      <li>Spacer</li>
      <li>Text</li>
    </ul>
  </Accordion>
</Accordions>

You can duplicate or delete blocks using the block menu controls.

<Callout>Once you switch from block editor to code editor, you can’t go back to the block editor unless you reset the template.</Callout>

#### Custom HTML block

The custom HTML block allows you to insert raw HTML inside a block editor layout.

* Allows injecting variables using `{{ ... }}`
* Supports LiquidJS control structures like `{% for %}` or `{% if %}`

Use this block when you need inline markup control within a visual layout, but don't require full LiquidJS logic.

#### Repeat block

The repeat block lets you iterate over an array and render its child blocks for each item in that array. It works similarly to a JavaScript `for` loop and is used for displaying structured or repeated data such as order items, activity feeds, or grouped records.

When the workflow runs, Novu evaluates the array you provide and repeats the block’s content for every element, allowing you to build dynamic lists.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/yC--z0mQ3Bg" title="Learn how to use Novu email editor Repeat block" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen />

In the video above, the repeat block iterates over the following array:

* `{{payload.order.items}}` is the array containing the items in an order.

Within the repeat block, each item in the array becomes the current iteration context, which allows you to reference item-level properties directly. For example:

* `{{payload.order.items.name}}`
* `{{payload.order.items.price}}`

This approach ensures each item in the array is rendered with its own data, making the Repeat block ideal for building dynamic, data-driven content.

#### Show block conditionally

The show block conditionally feature lets you control whether a content block is rendered based on runtime data. It allows you to show or hide specific parts of a template using conditions evaluated against subscriber properties or payload variables when the workflow runs.

This is useful for keeping templates flexible and avoiding duplicated layouts, for example, showing a call-to-action only when it’s relevant to the recipient.

The feature is supported by the following blocks:

* Button block
* Custom HTML block
* Image block
* Repeat block

In the editor, conditional visibility is accessed using the **eye icon** on a supported block. When enabled, you define a condition that determines whether the block is rendered.

For example, you can display a **Track your order** button only when a subscriber has a custom data field `showTracking` set to `true`. You can apply the same logic using payload variables passed when triggering the workflow, allowing content to adapt dynamically to each notification.

<img src="/images/workflows/add-notification-content/channels-template-editors/show-block.gif" alt="Show block" />

#### Digest block

The Digest block allows you to loop over the events collected by your digest step and displays them in your email content. It handles both layout and repetition automatically.

The Digest block is only available in Email steps that come after a Digest step in the workflow.

When you add a digest block to your email template editor:

* Novu automatically inserts a Repeat block that iterates over the digested events.
* You can define how many times the event is iterated.
* Inside the loop, you can also use the special alias variable `current` to reference the item currently being processed, for example, `current.payload.name`.
* The block also supports rendering a summary using the `steps.digest-step.eventCount` variable, typically with the pluralize LiquidJS filter.

![Digest block](/images/workflows/add-notification-content/channels-template-editors/digest-block.gif)

<Callout>To learn more about using digested data and digest-related variables in templates, see the [Personalize Content](/platform/workflow/add-notification-content/personalize-content) documentation.</Callout>

### Code editor (Custom HTML)

The code editor provides a built-in interface for writing raw HTML and embedding LiquidJS expressions directly inside the Novu dashboard. This gives you full control over layout, structure, and rendering beyond the capabilities of Novu's block editor.

The editor supports advanced use cases such as:

* Migrating existing HTML email templates
* Implementing full design systems
* Executing flow control logic directly inside email templates
* Complete layout and styling freedom without editor constraints

![Novu code editor](/images/workflows/add-notification-content/channels-template-editors/code-editor.png)

<Callout type="warn">Switching from code editor to the block editor will reset your code.</Callout>

### Email layouts

Layouts are reusable components used with email steps in the workflow, designed to bring consistency, maintainability, and efficiency to your email communications. With layouts, you can create a component using headers, footers and other branding elements and reuse that component across multiple email steps.

Every layout must include the `{{content}}` variable. This variable dynamically injects the content of the email step.

<Callout type="info"> On the Free plan, only one layout can be created per environment. Pro and higher plans support up to 100 layouts per environment. If you need more than 100 layouts, please [contact Support](mailto:support@novu.co).</Callout>

#### Layout features

* Reusable across workflows.
* Support both block and code editors.
* Each environment maintains its own set of layouts.
* Supports variables and translations.

<Callout>Payload variables are not supported in layouts because one layout can be used across multiple workflows and workflows can have strict payload schema validation.</Callout>

#### Apply an email layout to a workflow

1. Navigate to [Workflows page](https://dashboard.novu.co/workflows) on Novu dashboard.
2. Select a workflow from the list.
3. Select an email step.
4. Choose your layout from the Layout selector.

![Using layouts in workflow](/images/workflows/add-notification-content/channels-template-editors/email-layout.gif)

The selected layout wraps around the content written in the email editor.

#### Manage email layouts

Email layouts are managed from the **Layouts** section of the Novu dashboard. From here, you can create, edit, delete, and reuse layouts across workflows.

![Layouts page](/images/workflows/add-notification-content/channels-template-editors/layouts-page.gif)

**Create an email layout**

1. Navigate to the <a href="https://dashboard.novu.co/layouts" target="_blank" rel="noopener noreferrer">Layout page</a> on Novu dashboard.
2. Click on the **Create layout** button on the top right corner.
3. Fill in:

* **Layout name**: Provide a human-readable name.
* **Identifier**: Provide a unique ID. Novu generates one automatically if you do not provide it. You cannot change the identifier after it is created.

4. (Optional) Enable [translations](/platform/workflow/advanced-features/translations) for the layout.
5. Click **Create layout**.

A new layout is created and can be edited using either the block editor or the code editor.

**Edit email layout**

1. Navigate to <a href="https://dashboard.novu.co/layouts" target="_blank" rel="noopener noreferrer">Layout page</a> on Novu dashboard.
2. Select a layout from the list.
3. To update the layout name or enable translations, click the **cog** icon in the editor.
   ![Edit a layout](/images/workflows/add-notification-content/channels-template-editors/edit-layout.gif)
4. Modify the layout content using the block or code editor.
5. Click **Save changes**.

Changes apply immediately to all workflows using the layout.

**Delete an email layout**

<Callout type="warn">Deleting a layout is permanent and cannot be undone.</Callout>

1. Navigate to <a href="https://dashboard.novu.co/layouts" target="_blank" rel="noopener noreferrer">Layout page</a> on Novu dashboard.
2. Select a layout from the list.
3. Click the cog icon in the layout editor.
4. Click **Delete layout** and confirm. If the layout is used by an email step, then you are notified on which step uses this layout.
   ![Delete layout](/images/workflows/add-notification-content/channels-template-editors/delete-layout.gif)


# Personalize Content (/platform/workflow/add-notification-content/personalize-content)

Learn how to personalize notification content in Novu using template variables, context data, and LiquidJS filters across all channel template editors.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Novu allows you to personalize notification content in all channel template editors using variables, conditional logic, and runtime data. This enables you to generate notifications that adapt to each subscriber and reflect the data available at the time a workflow is executed.

## Template variables

Template variables are placeholders that are resolved at workflow execution time and replaced with actual values when a notification is rendered. They allow templates to reference data from the workflow trigger payload, subscriber profile, workflow metadata, and outputs from previous steps.

To insert a variable into a notification template, use double curly braces:

```liquid
{{variable_name}}
```

Variables also support nested objects and arrays. Use dot notation to access nested values:

```liquid
{{ variable_name.customer.name }}
{{ variable_name.customer.email }}

```

Template variables can be used anywhere content is supported. They can be rendered directly, formatted using LiquidJS filters, or used within conditional logic and loops to control how content is displayed.

<Callout>You can [configure all template variables](/platform/workflow/add-notification-content/personalize-content#configure-variables) from the template editor to fit your use case.</Callout>

### Payload variables

Payload variables represent the structured data available to a workflow through its payload schema. This payload data can originate from the event trigger or be defined and managed directly in the workflow’s payload schema.

Payload variables are accessed using the `payload` namespace:

```liquid
{{ payload.propertyName }}
```

For example, if your payload schema defines the following fields:

```json
{
  "orderId": "string",
  "amount": "number",
  "currency": "string"
}
```

You can reference them in your notification templates as:

```liquid
Order {{ payload.orderId }} totaling {{ payload.amount }} {{ payload.currency }} has been confirmed.
```

Payload variables provide a stable, predictable interface for dynamic data in your templates. By defining them in the payload schema, you ensure that all templates, step conditions, and action configurations reference a consistent set of fields.

<Callout> To learn how payload data is defined and validated, see the [Payload schema](/platform/workflow/configure-workflow#payload-schema) documentation. </Callout>

### Subscriber variables

Subscriber variables expose data associated with the recipient of a notification. They allow you to personalize message content based on who the notification is for, making each delivery feel contextual and relevant.

Subscriber variables are accessed using the `subscriber` namespace:

```liquid
{{ subscriber.propertyName }}
```

You can reference both standard subscriber fields and custom subscriber attributes stored on the subscriber profile.

Standard fields include commonly used properties such as `subscriber.firstName`, `subscriber.lastName`, and `subscriber.email`. Custom attributes are stored under the `data` object and can be accessed using `subscriber.data.*`.

```liquid
Hi {{ subscriber.firstName }},
 
You've been upgraded to the {{ subscriber.data.plan }} plan.
 
Thanks,
The Novu Team
```

<Callout> To learn more about subscriber metadata and profile structure, refer to the [Subscriber documentation](/platform/concepts/subscribers#subscriber-metadata-and-profile-structure). </Callout>

### Workflow variables

Workflow variables provide access to metadata defined on the workflow that is being executed such as the workflow:

* Severity level
* Tags
* Name
* Description
* Workflow identifier

This workflow data can be used in the templates editor to personalize message content. Workflow variables are accessed using the `workflow` namespace:

```html
<p>This is a <strong>{{workflow.severity}}</strong> priority message regarding your account.</p>
```

### Environment variables

Values stored in the environment variables are available to all workflows in that environment. They are accessed using the `env` namespace:

```liquid
{{ env.MY_API_BASE_URL }}
```

<Callout>To learn how to create and manage environment variables, refer to [Environment variables](/platform/developer/environment-variables).</Callout>

### Digest variables

Digest variables expose the data produced by a Digest step and are available to all channel steps that run after that digest step. They allow you to summarize, list, or otherwise represent multiple events that were grouped during the digest window.

Digest variables are accessed under the `steps` namespace and are scoped to the specific digest step.

<Callout type="info"> Digest variables are only available in steps that follow a Digest step. They are not available before the digest runs.</Callout>

Digest support is split into two categories:

* Digest step variables: Raw values produced by the digest step
* Digest template helpers: Preformatted helpers built on top of those raw values

The step variables expose data, while template helpers optimize for common notification use cases.

#### Digest step variables

Digest step variables expose the underlying data collected during the digest window. These variables hold values only.

* **steps.digest-step.events**: The `steps.digest-step.events` variable is an array that contains all the events collected by the digest step. Each item in the array represents a digested event, including the payload with which the workflow was triggered.

  ```liquid
  {{steps.digest-step.events}}
  ```

  You can loop through it to build dynamic message lists, such as comment summaries or blog post digests, or use <a href="https://liquidjs.com/filters/overview.html" target="_blank" rel="noopener noreferrer">LiquidJS filters</a>.

* **steps.digest-step.eventCount**: The `steps.digest-step.eventCount` variable holds the total number of events collected during the digest step window.
  ```liquid
  {{steps.digest-step.eventCount}}
  ```
  It is an integer value and can be used directly in the template editor or passed into <a href="https://liquidjs.com/filters/overview.html" target="_blank" rel="noopener noreferrer">LiquidJS filters</a> like pluralize to generate grammatically correct summaries.

#### Digest template helpers

Digest template helpers are preconfigured template variables designed to simplify common digest use cases. Internally, they are built by combining digest step variables with LiquidJS filters.

They exist to reduce template complexity and eliminate repetitive logic.

* **steps.digest-step.countSummary**: The `countSummary` variable returns a human-readable summary of the total number of digested events with correct pluralization applied.

  This helper is built using `steps.digest-step.eventCount` and the LiquidJS `pluralize` filter. When used, it inserts logic equivalent to:

  ```liquid
  {{ steps.digest-step.eventCount | pluralize: 'notification' }}
  ```

  For example, if the digest collected five events, then the output would be:

  ```text
  5 notifications
  ```

  You can use this helper when you want a concise count without manually managing plural rules.

* **steps.digest-step.sentenceSummary**: The `sentenceSummary` variable returns a sentence-style string listing key items from the digested events array, such as a list of names, and gracefully handles formatting depending on the number of items present.

  This helper is built using `steps.digest-step.events` and the LiquidJS `toSentence` filter. When the `sentenceSummary` variable is used in the template editor, it inserts logic equivalent to:

  ```liquid
  {{ steps.digest-step.events | toSentence: 'payload.name', 3, 'others' }}
  ```

  If the events contain names "Radek", "Dima", and five more users, then the result would be:

  ```text
  Radek, Dima, and 5 others
  ```

  You can configure the `toSentence` filter from the template editor by passing:

  * A key path to extract from each item, for example, `payload.name`. This is a required argument.
  * The number of items to display before collapsing.
  * The suffix to use for remaining items, for example, "others".

### Context variables

Context variables come from context data. Once a context is created either through the Novu dashboard or API, its data becomes available in all channel template editors and can be referenced using the context namespace.

```liquid
{{ context.* }}
```

Context variables are typically used for tenant details, branding and configuration that should not live in the workflow payload or data shared amongst different entities in Novu.

<Callout>To learn how to create and manage context data, and how to use the context data in the template editor, refer to [Context](/platform/workflow/advanced-features/contexts).</Callout>

## Apply logic with LiquidJS

All Novu template editors support <a href="https://liquidjs.com/index.html" target="_blank" rel="noopener noreferrer">LiquidJS</a>. This allows you to add logic and control flow to your notification content, including conditional rendering, iteration, and value transformation directly inside channel template editors.

<Callout>Autocomplete suggestions are not available inside control statements like `{% if %}` or `{% for %}`.</Callout>

### Conditional rendering

You can use the conditional statements in LiquidJS `if-else` statements to control whether content is shown based on a condition.

```liquid
{% if subscriber.data.plan == 'enterprise' %}
  You have access to priority support.
{% endif %}
```

<Callout>When comparing string values in Liquid conditional statements, always use single quotes (`'value'`). Double quotes (`"value"`) are not supported.</Callout>

### Iteration and loops

You can loop over arrays using `{% for %}` loop. This is useful when rendering lists of items, events, or grouped data.

```liquid
{% for item in payload.order.items %}
  - {{ item.name }} ({{ item.price }})
{% endfor %}
```

### Filters and transformations

You can use filters to transform values before rendering them. Filters are applied using the pipe (`|`) symbol and can be chained.

```liquid
Your workspace {{ payload.workspaceName | upcase }} has been successfully created.
```

## Configure variables

Novu provides a built-in variable configuration UI in the template editor that allows you to apply LiquidJS filters to variable output.

![Configure variable](/images/workflows/add-notification-content/personalize-content/configure-variable.png)

When you insert a variable into the template editor, click the variable to open the configuration menu.

![Configure variable](/images/workflows/add-notification-content/personalize-content/configure-variable.gif)

From this menu, you can:

* Apply Liquid filters
* Reorder applied filters

The filter input also provides filter suggestions, making it easier to discover and apply available filters. You can apply one or more filters to control how the variable value is rendered in your notification content.

Filters are applied top to bottom, meaning the output of one filter becomes the input for the next. You can reorder filters using drag and drop to change the execution order.


# Translations (/platform/workflow/advanced-features/translations)

Learn how to translate your workflow step content into multiple languages

Novu supports multi-language translations for workflows, allowing notifications to dynamically adapt to each of your subscriber's preferred language. You can enable, configure, and manage translations across your notification workflows from the Novu dashboard.

<Callout type="info">
  The translations feature is in `beta` and available on `Team` and `Enterprise` [plans](https://novu.co/pricing).
</Callout>

Each workflow can support multiple locales. Novu automatically selects the correct translation based on the subscriber’s locale.

<Callout type="warn">Novu currently supports locale codes in `language_REGION` format only, for example, `en_US`, `fr_FR`. Language-only locale codes such as `en` are not supported.</Callout>

Benefits:

* Deliver notifications in the subscriber's preferred language
* Customize content per workflow or layout
* Improve communication across geographies

Manage translations from the [translation page](https://dashboard.novu.co/translations) in the Novu dashboard. Set a default language and add target languages as needed.

![Translation page](/images/platform/workflow/translations/translations-page.png)

## Enabling translations

To use translations for a workflow, you need to enable them on the workflow level.

### While creating a new workflow

* Turn on the **Enable Translations** toggle
* Set the default locale, such as `en_US` or `en_GB`
* Add the target locales you wish to support, such as `fr_FR`, `es_ES`, `ja_JP`

### While editing an existing workflow

* Open an existing workflow
* Turn on the **Enable Translations** toggle
* You don't need to take any action if the toggle is already on

You can configure the default and targeted locales on the [translation page](https://dashboard.novu.co/translations).

![Translation locale](/images/platform/workflow/translations/translations-default-and-target-locale.gif)

## Translation groups

A translation group contains all language variants for a workflow identified by a unique workflow ID.

You can:

* Search for groups on the translations page
* View status per locale ('Outdated' or 'Up to date')
* Import or export translations for a specific locale, such as `en_US`
* Import or export translations for all workflows where translations are enabled

## Translation JSON format

Each locale supports JSON-based translation files. For example, the `en_US.json` file contains the default translations for the workflow. You can update the translation JSON files using the JSON editor on the translation page.

```json
{
  "in-app": {
    "title": "Welcome to Novu!",
    "message": "Hi {{subscriber.firstName}}, let's get started!"
  },
  "email": {
    "subject": "Get Started",
    "body": "Thank you for joining us, {{subscriber.fullName}}"
  }
}
```

You can update translations by editing the JSON files in the editor on the translations page or by exporting and re-uploading them.

![Translation JSON format](/images/platform/workflow/translations/translations_locale_content_edit.gif)

## Exporting and importing translations

If you prefer to create/update translations in a JSON file outside the Novu dashboard, you can do so by exporting and importing them.

### How to export translations

1. Navigate to the translations page.
2. Select the workflow you want to export translations for
   * To export the default locale for all workflows with translations enabled, click the **Export** button.
3. Select the workflow locale you want to export.
4. Click the download icon to download the latest translation JSON file for the selected locale.
   ![Export translations](/images/workflows/translations/export-translations.png)

### How to import translations

1. Navigate to the translations page.
2. Select the workflow you want to import translations into.
   * To import locale into all workflows with translations enabled, click the **Import** button.
3. Click on the locale, such as `en_US`, now click on the **Import translation(s)** button to upload the translation JSON file.
   ![Import translations](/images/workflows/translations/import-translations.png)

<Callout type="info">Translation files must be named using the `language_REGION.json` format, for example, `en_US.json`, `fr_FR.json`. Novu detects the locale automatically using the file name.</Callout>

Translation changes in default locale such as `en_US` will mark other locales as *Outdated, needs update*

### Master JSON file

Master JSON file is a JSON file that contains the default locale's translations keys of all the workflows where translations are enabled. You can import or export this file from the translations page. Below is an example of a master JSON file:

```json
{
  "workflows": {
    "events-publish": {
      "key": "value"
    },
    "events-update": {
      "subject": "A new update",
      "content": "{{payload.eventName}} event has been updated"
    }
  }
}
```

![Master JSON file export and import options](/images/platform/workflow/translations/translations_master_json_file.png)

## Using translation keys in step content editor

In Email or In-App editors, use `{{t.key}}` to insert a translatable string. If the key already exists for the locale, it appears in the suggestions list.

Clicking **Add to Translations** automatically adds a new key to default locale.

Example:

```html
{{t.subject}} → "Let's get you started"

{{t.product.details.description}}
```

![Using translation keys in step content editor](/images/platform/workflow/translations/translations_variable_use_in_step_editor.gif)

## Testing translations

Use the Preview Context to:

* Simulate subscriber locale such as `fr_FR` or `ru_RU`
* Preview step content for the selected language.
* Update or correct missing translations on the fly.

## Keeping translations up to date

Any edit to the default locale will invalidate others. You’ll see a warning: `Outdated, needs update`. Re-export the default, update translated files, and re-upload.

## Disabling translations

A translation group can be disabled by clicking on the three dots and selecting **Disable & delete translations**. This action is irreversible and removes all associated translation data.

## Translation in email layouts

Translations feature in layouts works the same as in email steps. You can use `{{t.key}}` to insert a translatable string. If the key already exists for the locale, it appears in the suggestions list. To use translations in layouts, you need to enable translations in the layout settings. Checkout the below example video on how to use translations in layouts.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/v5H8Eyc0prY" title="Learn how to use translations in email layouts" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen />

## Best practices

* Always finalize your default content before exporting.
* Avoid hardcoded language in the content editor.
* Use variables and translation keys consistently.
* Set subscriber locale properly to deliver notifications in the correct language.
* Ensure subscriber locales are mapped to a supported `language_REGION` format before sending them to Novu.


# Discord Chat Integration (/platform/integrations/chat/discord)

Learn about how to use Discord provider for chat notifications

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

When using Discord, you will have to store the integration credentials within the subscriber entity. Discord supports two ways to do this:

1. Using the **Discord Webhook** integration.
2. Using the **Discord Bot** integration.

Right now, Novu only supports the **Discord Webhook** integration. This approach has been because the easiest way to set it up is when you have a predefined destination for where the notifications should be sent. It's particularly useful for notifying a specific channel about updates.

**Quickstart:**

To get started with using Novu's Discord Webhook integration, you need a 'webhook token'. Here's how you can generate the same for testing purposes:

1. Go to the channel you want to add the webhook to (you need to be an admin of the discord server).
2. Right-click the channel and select "Edit Channel".
3. Integrations -> Webhooks -> New Webhook
4. Copy the webhook URL.
5. After obtaining the webhook URL in the previous step, you need to store it within the subscriber entity. Doing this ensures that Novu knows where (in which discord channel) to send the notification to. Here's how to do it:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.Discord,
        credentials: {
          webhookUrl: "<WEBHOOK_URL>",
        },
        integrationIdentifier: "discord-MnGLxp8uy",
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "discord",
      "credentials": {
          "webhookUrl": "<WEBHOOK_URL>"
      },
      "integrationIdentifier": "discord-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

* `subscriberId` is a custom identifier used when identifying your users within the Novu platform.
* `providerId` is a unique provider identifier. We recommend using our ChatOrPushProviderEnum to specify the provider.
* The third parameter is the credentials object. In this case, we use the `webhookUrl` property to specify the webhook URL generated in the previous step.

6. You are all set up and ready to send your first chat message via our `@novu/api` package or directly using the REST API in the channel you chose on your discord server.


# Mattermost (/platform/integrations/chat/mattermost)

Learn about how to use Mattermost provider for chat notifications

When using Mattermost, you will have to store the integration credentials within the subscriber entity. Mattermost supports two ways to do this:

1. Using the **Mattermost Webhook** integration.
2. Using the **Mattermost Bot** integration.

### Mattermost Webhook Integration

To integrate Mattermost with your application using the Mattermost Webhook integration, follow these steps:

1. Create an incoming webhook in Mattermost. This can be done by going to the **Integrations** page and clicking on the **Incoming Webhooks** tab.
2. Click on the **Add Incoming Webhook** button and configure the webhook settings. Be sure to select the channel where you want to receive notifications.
3. Click on the **Save** button to generate a webhook URL.

Once you have the webhook URL, you can store it in the subscriber entity in your application. This will allow you to send notifications to Mattermost using the following code:

```typescript
import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.Mattermost,
    credentials: {
      webhookUrl: "<WEBHOOK_URL>",
    },
    integrationIdentifier: "mattermost-MnGLxp8uy",
  },
  "subscriberId"
);
```

## SDK trigger example

Send a notification to mattermost using the subscriber ID and workflow ID via `@novu/api` sdk

```typescript
await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'subscriberId',
  },
  payload: {
    message: 'This is a notification from my application!',
  },
});
```


# Microsoft Teams Integration (/platform/integrations/chat/ms-teams)

Learn about how to use MS Teams provider for chat notifications

The Novu Microsoft Teams integration enables you to send notifications to Teams channels and direct messages (DMs) across different customer workspaces using a single multi-tenant bot.

You create and host a Microsoft Teams bot in your Azure environment, and your customers then approve the app (via Admin Consent) and install it in their Teams tenants.

Once a customer connects their workspace, Novu establishes a secure channel connection using your bot's credentials. You then map specific destinations, whether the destinations involve public channels or individual users to channel endpoints, allowing Novu to route notifications dynamically to the correct tenant and conversation context.

<Callout type="info">
  This feature is currently in public beta, please contact us at [support@novu.co](mailto:support@novu.co) to enable it for your organization.
</Callout>

## Prerequisites

* Access to <a href="https://portal.azure.com/" target="_blank" rel="noopener noreferrer">Azure Portal</a> with App Registration permissions.
* Access to <a href="https://dev.teams.microsoft.com/home" target="_blank" rel="noopener noreferrer">Microsoft Teams Developer Portal</a>
* Administrator privileges for granting API permissions
* Access to <a href="https://dashboard.novu.co" target="_blank" rel="noopener noreferrer">Novu dashboard</a>

## Azure and Teams configuration

Before you can configure Novu, you must create the infrastructure that hosts your bot. This involves two distinct portals:

* **Azure portal**: To create the identity (App Registration) and infrastructure (Bot Service).
* **Teams Developer Portal**: To create the app package that your customers can install.

### Create the app identity (Azure AD)

First, create a multi-tenant identity for your bot.

1. Log in to the <a href="https://portal.azure.com/" target="_blank" rel="noopener noreferrer">Azure Portal</a>.
2. In the menu, click **Microsoft Entra ID** (formerly Azure Active Directory).
3. In the Manage section, click **App registrations**.
4. To create an app, click **New registration**.
   ![New app](/images/channels-and-providers/chat/msteams/app-registrations.png)
5. Fill in the form:
   * **Name**: Enter any name of your choice.
   * **Supported account types**: Select **Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)**.
     ![Register app](/images/channels-and-providers/chat/msteams/register-application.png)
6. Click **Register**.
   ![Create app](/images/channels-and-providers/chat/msteams/create-app.png)
7. After creating the app, note the Application (client) ID and  Directory (tenant) ID. You need these values to configure Microsoft Teams in Novu.

### Configure client secret

1. On your new app's overview page, click **Certificates & secrets**.
2. Click **New client secret**.
   ![Client secret](/images/channels-and-providers/chat/msteams/client-secret.png)
3. Add a description.
4. Set an expiry date.
5. Click **Add**.
   ![Client secret](/images/channels-and-providers/chat/msteams/certificates-and-secret.png)
6. Copy the value. This value becomes your `BOT_APP_SECRET`, and you’ll paste it into Novu. You can view the secret only once right after you create it, so save it before you leave the page.

### Add Novu’s redirect URI

After your customers go through the administrator consent page, Microsoft needs to know where to send them back after they accept.

1. Click **Authentication (Preview)**.
2. Click **Add Redirect URI**.
3. In the menu that appears, click **Web**.
4. In the **Redirect URI** field, set the redirect URI to the Novu OAuth callback URL:
   * US region
   ```bash
   https://api.novu.co/v1/integrations/chat/oauth/callback
   ```
   * EU region
   ```bash
   https://eu.api.novu.co/v1/integrations/chat/oauth/callback
   ```
   ![Add redirect uri](/images/channels-and-providers/chat/msteams/add-redirect-uri.png)
5. Click **Configure**.

### Add Microsoft Graph app permissions

These permissions let your app list teams and channels and decide where to send messages.

1. Click **API permissions**.
2. Click **Add a permission**.
3. Click **Microsoft Graph**.
   ![Add permissions](/images/channels-and-providers/chat/msteams/add-permissions.png)
4. Click **Application permissions**.
5. Search for and select the following permissions:
   * `Team.ReadBasic.All`
   * `Channel.ReadBasic.All`
   * `AppCatalog.Read.All`
   * `TeamsAppInstallation.ReadWriteSelfForTeam.All` (optional, for automation)
   * `TeamsAppInstallation.ReadWriteSelfForUser.All` (optional, for automation)
6. Click **Add permissions**.

### Create an Azure Bot resource

Now you register your bot with the Azure AI Bot Service and link it to the app registration that you just created.

1. In the Azure portal menu, click **Create a resource**.
2. Search for “Azure Bot”, and then click the Azure Bot resource.
   ![Azure bot](/images/channels-and-providers/chat/msteams/azure-bot.png)
3. Click **Create**.
4. Fill in the basics:
   * **Bot handle**: The unique display name in Azure.
   * **Subscription**: Select the Azure subscription.
   * **Resource group**: A collection of resources that share the same lifecycle, permissions, and policies, you can either select or create one.
   * **Data residency**: Specify an option for data residency, either global or regional.
5. Under **Microsoft App ID**:
   * **Type of app**: Select Single-tenant app registration.
   * **Creation type**: Choose “Use existing app registration” and use app IDs [you created earlier](/platform/integrations/chat/ms-teams#create-the-app-identity-azure-ad):
     * **App ID**: Replace with the Application (client) ID.
     * **App tenant ID**: Replace with the Directory (tenant) ID.
       ![Create azure bot](/images/channels-and-providers/chat/msteams/create-azure-bot.png)
6. Click **Review + create**.
7. Click **Create**.

### Enable the Microsoft Teams channel

This connects your bot resource to Teams and lets your Teams app install cleanly.

1. Once the deployment finishes, click **Go to resource**.
   ![Go to resource](/images/channels-and-providers/chat/msteams/go-to-resource.png)
2. Click **Settings**.
3. Click **Channels**.
4. In the available channels section, click **Microsoft Teams**.
5. In the menu that appears, accept the terms of services.
6. In the **Messaging** section, choose the appropriate environment, typically **Microsoft Teams Commercial**.
7. Click **Apply**.

### Create a Teams app

Now you create the Teams “wrapper” around your app registration and bot.

1. Open the <a href="https://teams.microsoft.com/v2/" target="_blank" rel="noopener noreferrer">Teams client</a> (desktop or web).
2. In the left sidebar, click **Apps**.
3. Search for **Developer Portal** and click **Add**, then open it.
   ![Developer portal](/images/channels-and-providers/chat/msteams/developer-portal.png)
4. In the Developer Portal dashboard, click **Create a new app**.
   ![Create new app](/images/channels-and-providers/chat/msteams/create-new-app.png)
5. Enter a name of your choice and click **Create**.
6. In the left sidebar, click **Basic information**.
7. Fill in the required fields (names, descriptions, developer info, URLs) and then click **Save**.
8. In the sidebar, click **App features**.
9. Select **Bot**.
   ![Bot](/images/channels-and-providers/chat/msteams/bot.png)
10. Under **Identify your bot**, select **Enter a bot ID** and then paste your Application (client) ID from Microsoft Azure.
11. In the **What can your bot do?** section, select "Only send notification" (at minimum).
12. Under **Select the scopes where people can use your bot**, enable the scopes based on your use case:
    * **Team**
    * **Personal**
    * **Group chat**
13. Click **Save**.
14. In the top right, click **Distribute** and then click **Download the app package**. This will save a copy of the app package to your computer in ZIP format.
    ![Distribute your app](/images/channels-and-providers/chat/msteams/distribute-your-app.png)

### Upload your app

Next, you must install the app into a specific Team or for a specific User.

Follow the steps in the <a href="https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/apps-upload#upload-your-app" target="_blank" rel="noopener noreferrer">Microsoft Teams documentation</a> to learn how to upload the just downloaded app package and also how to add the app to a specific location.

## Configure the Teams (Bot) integration in Novu

Now that you’ve configured your Azure Bot, provide Novu with the credentials to integrate it.

1. Log in to the Novu dashboard.
2. In the sidebar, click Integrations Store.
3. Click **Connect Provider**.
4. Select **Chat** and click **MSTeams**.
5. Enter the credentials you saved from the Azure Portal:
   * **Client ID**: Enter your `BOT_APP_ID`.
   * **Client Secret**: Enter your `BOT_APP_SECRET`.
   * **App Tenant ID**: Enter your `APP_TENANT_ID`. This value identifies the tenant where you registered the app.
   * **Redirect URL** (Optional): If you want to control where your users land after they grant administrator consent, then enter that URL here. If you leave it empty, then the consent window closes automatically.
     ![Novu integration](/images/channels-and-providers/chat/msteams/novu-msteams-integration.png)
6. Click **Create Integration**.

From now on, Novu can send messages as your bot, once a customer tenant is connected and the app is installed.

<Callout type="info" title="Try the Microsoft Teams integration with a demo app">If you’ve completed the previous steps, you can test your bot configuration end to end with this <a href="https://github.com/novuhq/ms-teams-example" target="_blank" rel="noopener noreferrer">demo app</a>.</Callout>

## Let your customers connect their tenant

Each of your customers has their own Microsoft 365 tenant. Before you can send them messages, they must grant your app a one time administrator consent. This authorizes your bot to act within their environment.

### Generate a Connect Teams URL

On your backend, use the Novu SDK to generate the authorization URL. This URL is specific to the customer's tenant context in your system.

```tsx
import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

const url = await novu.integrations.generateChatOAuthUrl({
  integrationIdentifier: 'ms-teams-bot', // The identifier used for that integration on Novu
  subscriberId: 'customer-admin-id',     // (optional)
  context: { tenant: 'acme-corp' },      // (optional)
});
```

Novu returns a URL pointing to Microsoft's administrator consent endpoint. This URL already includes your Client ID, Redirect URI, and the necessary Graph scopes.

### Show it in your UI

In your frontend app, bind this URL to a button:

```
// On "Connect Microsoft Teams" button click:
window.open(url, '_blank');
```

### What the customer administrator does

Steps the customer administrator would take:

1. A Teams/Microsoft 365 Admin from your customer's organization logs into your product.
2. They click your **Connect Microsoft Teams** button.
3. They see a Microsoft consent page listing the permissions.
4. They click **Accept**.

Once the user completes this step, Microsoft redirects the user back to Novu. Novu captures the customer's tenant ID and automatically creates a Teams connection for that specific tenant context. You don't need to handle the callback yourself.

### Customer installs your app in their Teams

Granting Admin consent in the previous step only authorizes your bot to exist in the customer's tenant. It doesn't automatically add the bot to any specific teams or chats.

For the bot to send messages, install it in the specific context where notifications should appear:

* **For channel messages**: Install the app in the specific Team.
* **For direct messages**: Install the app for the specific user in their personal scope.

The customer’s administrator can install your app from the Teams app store or their org catalog, depending on how you published. If you requested the `TeamsAppInstallation.ReadWriteSelfForTeam.All` permission, your backend can programmatically install the app into a specific Team using the Microsoft Graph API.

## Tell Novu where to send the messages

Your customer decides where notifications should land and gives you the right IDs and then your backend registers them as Channel Endpoints in Novu.

You can choose between two destination types:

* **Channels**: Send a message to a specific channel within a Team.
* **Users**: Send a direct message to a specific user.

### Sending message to channels

To send a notification to a specific channel, you must discover the Team ID and Channel ID from Microsoft, and then register them in Novu.

#### Find the Team and Channel IDs (Microsoft Graph)

You can discover these IDs using the Microsoft Graph API. This requires an App-Only Token (Client credentials) scoped to the customer's tenant.

1. Get a Graph access token:

```bash
POST https://login.microsoftonline.com/{SUBSCRIBER_TENANT_ID}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={BOT_APP_ID}
&client_secret={BOT_APP_SECRET}
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&grant_type=client_credentials
```

The `SUBSCRIBER_TENANT_ID` represents the customer's tenant ID, which Novu stored on the `ChannelConnection` object after completing the Admin Consent flow.

```bash
GET /v1/channel-connections
{
  "identifier": "chconn-eeybt4",
  "integrationIdentifier": "msteams",
  "providerId": "msteams",
  "channel": "chat",
  "subscriberId": "689c4a87c5bdaa96aaef0cfd",
  "workspace": {
    "id": "e6633b86-ef94-4416-863f-f0f409700ca0" // the customer's tenant workspace ID
  },
  "auth": {
    "accessToken": "app-only"
  },
}
```

2. List Teams:

```bash
GET https://graph.microsoft.com/v1.0/teams
Authorization: Bearer {ACCESS_TOKEN}
```

3. List channels in a Team:

```bash
GET https://graph.microsoft.com/v1.0/teams/{TEAM_ID}/channels
Authorization: Bearer {ACCESS_TOKEN}
```

#### Register the channel endpoint (Novu)

Once you have the IDs, create an `ms_teams_channel` endpoint in Novu. This maps a subscriber to that specific channel.

```bash
POST /v1/channel-endpoints
Authorization: ApiKey {CUSTOMER_API_KEY}
Content-Type: application/json

{
  "identifier": "msteams-main-notifications",
  "integrationIdentifier": "ms-teams-bot-1",
  "providerId": "msteams",
  "channel": "chat",

  "subscriberId": "workspace_abc",
  "connectionIdentifier": "msteams-tenant-subscriberX",

  "type": "ms_teams_channel",
  "endpoint": {
    "teamId": "TEAM_ID",
    "channelId": "CHANNEL_ID"
  },
}
```

Novu stores this as `ChannelEndpoint<'ms_teams_channel'>`. You can later target it from workflows via `subscriberId` + `context`.

### Send a direct message to a user

To send a direct message (DM), you need the user's Teams User ID before registering the user endpoint in Novu.

#### Find the user ID (Bot framework)

Use the <a href="https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-overview?view=azure-bot-service-4.0" target="_blank" rel="noopener noreferrer">Bot framework API</a> to inspect the roster of the Team where you installed the bot.

1. Install the bot in at least one Team that includes the target user.
2. Get a Bot Framework token:
   ```bash
   POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials&
   client_id={BOT_APP_ID}&
   client_secret={BOT_APP_SECRET}&
   scope=https%3A%2F%2Fapi.botframework.com%2F.default
   ```
3. Call the roster API for that Team, using the Team’s `19:...@thread.tacv2` id as `{TEAM_CONVERSATION_ID}`:
   ```bash
   GET https://smba.trafficmanager.net/teams/v3/conversations/{TEAM_CONVERSATION_ID}/members
   Authorization: Bearer {BOT_ACCESS_TOKEN}
   ```

From the returned members, take the member’s `id`; this value represents the Teams user ID (`29:...`) you’ll use as `userId`.

#### Register the user endpoint (Novu)

Once you have the IDs, create the endpoint in Novu using the `ms_teams_user` type.

```bash
POST /v1/channel-endpoints
Authorization: ApiKey {CUSTOMER_API_KEY}
Content-Type: application/json

{
  "identifier": "msteams-user-alice",
  "integrationIdentifier": "ms-teams-bot-1",
  "providerId": "msteams",
  "channel": "chat",

  "subscriberId": "user_123",
  "connectionIdentifier": "msteams-tenant-subscriberX",

  "type": "ms_teams_user",
  "endpoint": {
    "userId": "29:1GcS4EyB_oSI8A88XmWB..."
  },

  "contextKeys": []
}
```

Novu stores this as `ChannelEndpoint<'ms_teams_user'>`. From here, any workflow that resolves to this endpoint can send a DM from your bot to that user.

## Workflows for Teams (Webhook-style)

If you don't need a full Bot identity or Direct Message capabilities, then you can support a simplified, channel-only integration using Workflows for Microsoft Teams.

This approach relies on a unique Webhook URL generated by the Teams client. It requires no Azure app registration and no administrator consent.

### User generates the webhook URL (Teams client)

The setup begins inside the Microsoft Teams app. Instruct your users to follow these steps:

1. In Microsoft Teams, go to **Apps** in the sidebar.
2. Search for and open **Workflows**.
3. Click **Create new flow**, either from blank or template.
4. Choose a trigger, such as “When a Teams webhook request is received”.
5. Add an action to post a message into a specific channel.
6. Save the workflow.
7. Once created, the workflow generates a unique URL. The user must copy this URL.

### Register the webhook endpoint (Novu)

Unlike the Bot integration, you don't use `ms_teams_channel` here. Instead, you treat this as a generic webhook endpoint. Your app should provide a form where the user can paste the URL they generated in the previous step.

```bash
await novu.channelEndpoints.create({
  type: 'webhook',
  identifier: 'teams-workflow-alerts',
  integrationIdentifier: 'ms-teams-workflow',
  subscriberId: 'customer-account-id',
  context: { tenant: 'acme' },
  endpoint: {
    url: 'https://prod-00.westeurope.logic.azure.com:443/workflows/...' // workflow URL
  },
});
```

### Sending the notification

When you trigger a workflow that targets this subscriber:

1. Novu sends a standard HTTP POST payload to the Teams Workflow URL.
2. Workflows for Teams receives the payload.
3. The Workflow runs and posts the message content into the configured channel.


# Slack Chat Integration (/platform/integrations/chat/slack)

Learn about how to use Slack provider for chat notifications

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The Slack chat integration lets your application send notifications directly to your subscribers' Slack workspaces using their own Slack accounts and workspace permissions. With this integration, Novu can deliver messages to Slack channels, direct messages (DMs) to Slack users, and incoming webhooks. For incoming webhooks, Novu can use Slack's native channel picker during OAuth.

Novu handles the full lifecycle of Slack connections and message delivery. You define where notifications should be delivered, and Novu automatically routes each message to the correct Slack workspace, channel, or user.

This guide walks you through setting up Slack chat, connect workspaces, and deliver notifications to the exact Slack destinations your users expect it.

<Callout type="info">
  This feature is currently in public beta, please contact us at [support@novu.co](mailto:support@novu.co) to enable it for your organization.
</Callout>

## Configure a Slack app

Before integrating Slack chat with Novu, you must create and configure a Slack app. The Slack app manages the OAuth permissions, bot token scopes, and redirect URLs needed for Novu to connect to your users' workspaces securely.

<Callout>Novu provides a test Slack integration for new organizations. The integration is limited to 300 messages per month and stricter rate limits apply.</Callout>

### Create a Slack app

First, you need to create a Slack app. This provides you with the credential you need to create a Slack integration in Novu.

1. Go to the <a href="https://api.slack.com/apps" target="_blank" rel="noopener noreferrer">Slack API dashboard</a>.
2. Click **Create an App**.
3. Select **From scratch**.
4. Enter an app name of your choice in the **App Name** field.
5. Pick a Slack workspace to develop your app in.
   ![Create app](/images/channels-and-providers/chat/slack/create-app.png)
6. Click **Create App**. You'll be directed to the **Basic Application** for the Slack app which contains the credentials you need for configuring Slack chat inside Novu:
   * App ID
   * Client ID
   * Client Secret
     ![Basic application](/images/channels-and-providers/chat/slack/basic-information.png)

### Configure scopes (Permissions)

Your app needs permission to perform actions like sending messages or reading channel lists.

1. In the sidebar, select **OAuth & Permissions**.
2. Scroll down to the **Scopes** section.
3. Under Bot Token Scopes, click **Add an OAuth Scope**.
   ![Add an OAuth Scope](/images/channels-and-providers/chat/slack/scopes.png)
4. Add the following recommended scopes:
   * `chat:write`
   * `chat:write.public`
   * `channels:read`
   * `groups:read`
   * `users:read`
   * `users:read.email`
   * (optional) `incoming-webhook` if you want Slack's built-in channel picker.

These scopes are required for Novu to send messages, read channels and read users (for DMs and pickers). If you remove some of them, then certain features like channel or user selection might not work.

### Set the redirect URL

This tells Slack where to send the user after they successfully authorize your app.

1. In the sidebar, select **OAuth & Permissions**.
2. Scroll down to the **Redirect URLs** section.
3. Click **Add New Redirect URL**.
   ![Add New Redirect URL](/images/channels-and-providers/chat/slack/redirect-urls.png)
4. Paste the Novu OAuth callback URL. Add the redirect URL that matches your Novu region:
   * US region:
     ```
     https://api.novu.co/v1/integrations/chat/oauth/callback
     ```
   * EU region:
     ```
     https://api.eu.novu.co/v1/integrations/chat/oauth/callback
     ```
5. Click **Add** to save the URLs. If you use a self-hosted Novu instance, then add your instance's callback URL instead.

## Configure Slack integration in Novu

Once your Slack app is set up, the next step is to configure the Slack Chat integration inside Novu.

1. Log in to the Novu dashboard.
2. In the sidebar, click **Integrations Store**.
3. Click **Connect Provider**
4. Select **Chat** and click **Slack**.
5. Fill in the required fields using the credentials from your Slack app:
   * **Application Id**: Paste your Slack app App ID.
   * **Client ID**: Paste your Slack App Client ID.
   * **Client Secret**: Paste your Slack App Client Secret.
   * **Redirect URL (Optional)**: Enter the URL where you want users to be redirected to after they successfully connect their workspace. If there is no redirect URL, then Novu closes the tab immediately after the OAuth flow completes.
     ![Connect slack integration in Novu](/images/channels-and-providers/chat/slack/slack-integration.png)
6. Click **Create Integration** to create the Slack integration. Once saved, Novu is able to:
   * Generate OAuth (Connect Slack) URLs for your users
   * Receive Slack's OAuth callback.
   * Store workspace tokens as connections.

You are now ready to implement the frontend flow to let users connect their workspaces.

## Let users connect their Slack workspace

To send messages to Slack, your users must first authorize Novu to access one of their Slack workspaces. This authorization happens through Slack's OAuth flow, which Novu generates and manages for you.

### Generate the OAuth URL

When a user clicks **Connect Slack** in your application, your backend should request a unique authorization URL from Novu.

This URL is specific to the Subscriber or the Context (Tenant) it will be generated for.

<Callout type="warn">The generated OAuth URL is valid for only <strong>5 minutes</strong>. Do not cache this URL; generate it dynamically when the user initiates the flow.</Callout>

```tsx
import { Novu } from '@novu/api'; 

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

// This function should be called by your API when the user requests to connect
async function getSlackUrl(user, orgId) {
  
  const oauthUrl = await novu.integrations.generateChatOAuthUrl({
    integrationIdentifier: 'slack',
    subscriberId: user.id,           // The ID of the user performing the action
    context: { tenant: orgId },      // The tenant/workspace context
  });

  return oauthUrl;
}
```

Your application can support multiple Slack workspace connections per user or per tenant by triggering separate OAuth flows.

Novu allows one connection per (integration + subscriber + context). To connect multiple workspaces, provide different combinations of subscriber or context.

### Redirect the user

Once your backend returns the `oauthUrl`, open it in a new tab or window.

```tsx
window.open(oauthUrl, '_blank');
```

Slack then guides the user through:

1. Reviewing your app's requested permissions
2. Approving the authorization
3. Redirecting back to Novu's callback URL

After the user approves access, Novu handles the rest of the OAuth flow automatically.

1. Novu exchanges the code for a Slack token.
2. Novu creates a Slack connection for that workspace, it is referenced by `connectionIdentifier` when creating endpoints.You can also provider a custom `connectionIdentifier` to the `generateChatOAuthUrl()` and then connection with such identifier will be created instead of randomly generated one.

## Choose delivery destinations

After a workspace is connected, you or users decide where in Slack to send the messages. This can either be a Slack channel, to a user or an incoming webhook URLs. After the delivery location has been selected, a Slack endpoint is then created for that location.

### Send to a Slack channel

This is the typical flow for sending notifications to public or private channels.

1. **Get the channel ID**: First, the channel where the message will be sent to must be selected, one way to do this is by using your Slack app token to list channels in your own UI.

   ```bash
   curl -X GET "https://slack.com/api/conversations.list" \
     -H "Authorization: Bearer <YOUR_BOT_TOKEN>"
   ```

   To learn more about using <a href="https://docs.slack.dev/apis/web-api/using-the-conversations-api" target="_blank" rel="noopener noreferrer">Slack conversations API</a> to either get public or private channels, refer Slack documentation.

2. **Create the endpoint**: Once the user selects a channel, save it as an endpoint in Novu.

   ```tsx
   await novu.channelEndpoints.create({
     subscriberId: 'user-123',
     integrationIdentifier: 'slack',
     connectionIdentifier: 'conn_slack_acme', // The identifier of the connection created in Step 2
     context: { tenant: 'acme' },
     type: 'slack_channel',                   // TYPE: Channel
     endpoint: {
       channelId: 'C012345'                   // Slack channel ID of the channel selected by the user
     }
   });
   ```

### Send to a Slack user (Direct messages)

Use this to send personal messages and notifications directly to a specific user.

1. **Get the Slack user ID**: You can use Slack’s users API to get user IDs.

   ```bash
   curl -X GET "https://slack.com/api/users.list" \
     -H "Authorization: Bearer <YOUR_BOT_TOKEN>"
   ```

   For example, you can look up a Slack user ID by their email address, if you requested the `users:read.email` scope.

To learn more about using <a href="https://docs.slack.dev/reference/methods/users.list" target="_blank" rel="noopener noreferrer">Slack `users.list` method</a>, refer Slack documentation.

2. Create the endpoint: Save the returned User ID as the endpoint.

   ```tsx
   await novu.channelEndpoints.create({
     type: 'slack_user',
     subscriberId: 'user-123',
     integrationIdentifier: 'slack',
     connectionIdentifier: 'conn_slack_acme',
     context: { tenant: 'acme' },
     endpoint: {
       userId: 'U01234567',                  // Slack user ID
     },
   });
   ```

### Incoming webhook URLs

If `incoming-webhook` scope was included when configuring the OAuth and permissions scopes in [Step 1.1](/platform/integrations/chat/slack#configure-scopes-permissions). Slack would show its own channel picker during the OAuth flow:

1. The user selects a channel directly in Slack.
2. Slack returns an `incoming_webhook.url`.
3. Novu automatically creates a webhook endpoint for that subscriber using that URL.

You don’t need to collect `channelId` yourself in this mode, Slack’s native channel picker handles it.

## Send notifications

Once you have at least one Slack connection, and one or more Slack endpoints. You can trigger the workflow:

```jsx
import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
  name: 'order-shipped',
  to: {
    subscriberId: 'user-123',
  },
  context: { tenant: 'acme' },       // optional routing context
  payload: {
    orderNumber: 'ORD-12345',
    trackingUrl: 'https://acme.com/track/123',
  },
});
```

When the workflow is triggered, Novu will:

1. Find Slack endpoints matching `subscriberId` and `context`.
2. Use the right Slack workspace connection.
3. Deliver messages to the configured destinations.


# WhatsApp Integration (/platform/integrations/chat/whats-app)

Learn about how to use WhatsApp for chat notifications

## Getting Started

To integrate WhatsApp Business with Novu, You will have to create a facebook developer app and obtain the necessary credentials.

<Steps>
  <Step title="Create a Facebook developer app">
    Visit the [Facebook Developer Portal](https://developers.facebook.com/apps/) and create a new app.

    Select "Other" for "What do you want your app to do?" and select "Business" for "Select an app type".
  </Step>

  <Step title="Setup WhatsApp product">
    On the App Setup page, click on "Set Up" under the "WhatsApp" product. You will need to create or
    add a Facebook Business Account to your app.
  </Step>

  <Step title="Send a sandbox message">
    Copy the following pieces and paste them in the Novu WhatsApp Business integration settings:

    * Temporary access token - Access API token field
    * Phone Number ID - Phone number identification field

    <Callout type="warn">
      It's important to note that the test credentials for whatsapp cannot be used
      in production and will expire in 24 hours. You will need to submit your app
      for review to obtain production credentials.
    </Callout>
  </Step>

  <Step title="Add a test phone number">
    You can add a test phone number to the sandbox by clicking on the **"Add Phone Number"** button.
    This number can be used to test your integration with Novu before submitting for a review.
  </Step>

  <Step title="Send a test notification from Novu">
    You can now create a new workflow with a "chat" node, and add your content. Save your workflow, and click on **"Trigger Notification"** button.

    In the to field, specify the phone number you added in the sandbox, and click on "Send Notification".

    ```json
    {
      "subscriberId": "TEST_SUBSCRIBER_ID",
      "phone": "+11111111111"
    }
    ```

    and in the `overrides` field, add the following:

    ```json
    {
      "chat": {
        "template": {
          "name": "hello_world",
          "language": {
            "code": "en_US"
          }
        }
      }
    }
    ```

    <Callout type="info">
      For test credentials you can only used the built in Whats App Template.
    </Callout>
  </Step>
</Steps>

## Going to production

<Steps>
  <Step title="Register a business phone number">
    To go live you will need to add a real business phone number and submit your app for review.
    Follow the [Facebook Instructions](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/add-a-phone-number) on how to proceed.
  </Step>

  <Step title="Generate a permanent access token">
    Follow the [Facebook
    Instructions](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started/)
    on how to generate a permanent access token. Depending on your use case.
  </Step>

  <Step title="Create a WhatsApp template">
    You will need to create a WhatsApp Template to send notifications to your customers. Create a template in the [Business Manager](https://business.facebook.com/wa/manage/message-templates) and submit it for review.
    After your template is approved, you can use the `template_name` to send notifications to your customers.

    To send a notification with a template, you will need to add the following to the `overrides` field:

    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
        phone: '+11111111111',
      },
      payload: {},
      overrides: {
        chat: {
          template: {
            name: 'template_name',
            language: {
              code: 'en_US',
            },
          },
        },
      },
    });
    ```
  </Step>
</Steps>


# Zulip Chat Integration (/platform/integrations/chat/zulip)

Learn about how to use Zulip provider for chat notifications

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Zulip does not need any API Key or client ID to push messages in it. All it needs is the webhook URL of the channel you want to send messages to. That itself acts as the credential.

Similar to Discord, the credential for this provider needs to be stored in the subscriber entity.

## Getting a Zulip webhook URL

* Sign up or Login to your Zulip account.

* Click on the Settings icon in the top right corner of the screen, and then click "Personal settings" from the drop-down menu.

![Zulip settings menu](/images/channels-and-providers/chat/zulip/step_01.png)

* Click "Add a new bot" button in "Bots" tab.

![Add new bot button](/images/channels-and-providers/chat/zulip/step_02.png)

* Set bot type as "Incoming webhook".

![Set bot type](/images/channels-and-providers/chat/zulip/step_03.png)

* Click the small link icon to generate webhook URL for provider. Set Integration as `Slack compatible webhook`, choose your channel and copy webhook URL.

![Generate webhook URL](/images/channels-and-providers/chat/zulip/step_04.png)

## Connecting our subscribers to Zulip

The URL generated above will be the target channel of a subscriber that you want to integrate with. To make this connection, you have to:

1. Copy the URL that you generated above

2. Update the subscriber credentials with this URL using the Zulip provider id. You can do this step by using the `@novu/api` library, as shown below:

## Update credential webhookUrl

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.Zulip,
        credentials: {
          webhookUrl: "<WEBHOOK_URL>",
        },
        integrationIdentifier: "zulip-MnGLxp8uy",
      },
      "subscriberId"
    );

    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "zulip",
      "credentials": {
          "webhookUrl": "<WEBHOOK_URL>"
      },
      "integrationIdentifier": "zulip-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

* `subscriberId` is a custom identifier used when identifying your users within the Novu platform.
* `providerId` is a unique provider identifier. We recommend using our ChatOrPushProviderEnum to specify the provider.
* The third parameter is the credentials object, in this case, we use the `webhookUrl` property to specify the Zulip channel webhook URL or by calling the `Update Subscriber Credentials` endpoint on Novu API. Check endpoint details [here](/api-reference/subscribers/update-provider-credentials).

3. You are all set up and ready to send your first chat message via our \`@novu/api package or directly using the REST API.


# Amazon SES Integration (/platform/integrations/email/amazon-ses)

Learn how to use the Amazon SES provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

You can use the [Amazon SES](https://aws.amazon.com/ses/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Amazon SES provider in the email channel, you will need to create an SES account and add your credentials to the Amazon SES integration on the Novu platform.

## Setting up SES in AWS?

* Create a new IAM account with appropriate permission policies.
  <Callout type="info">Example policy rule `arn:aws:ses:<REGION>:<ACCOUNT>:identity/*`</Callout>
* Create a new access key and save generated `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` carefully
* Choose Amazon Simple Email Service.
* Create a new identity.
* Either choose domain or email.
* Verify your domain (by adding a few DNS records as mentioned in SES instructions) or email (AWS sends a verification email to your email).
* Verify the recipient email also by creating a new email identity type \[only in sandbox mode].
* Test if your SES is set up correctly using the test email feature.

## Creating an SES integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-integrations-ses) page on Novu.
* Click on Add a Provider.
* Select Amazon SES service.
* Enter previously saved `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY`.
* Fill in the `From email address` field using the authenticated sender email id in the previous step.
* Enter `region` and `Sender name` also.

<Callout type="info">
  Example region format:- `us-east-1`. By default Novu uses `us-east-1` region.
</Callout>

* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Amazon SES in Novu.

## FAQs

### Trigger from novu is successful but the subscriber is not receiving email

Possible reasons:

* Subscriber's email address is not verified in SES if SES account is in sandbox environment.
* SES account daily sending limit has been reached if SES account is in sandbox environment.
* Incorrect credentials have been used while creating SES integration.

### SignatureDoesNotMatch error with SES

* Ensure that the `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` values are correct and have the necessary permissions. If using SMTP credentials, change it with IAM role credentials.
* If the issue persists, regenerate the credentials and update the integration with new credentials.

## Next Steps

<EmailProviderNextSteps />


# Braze Email Integration (/platform/integrations/email/braze)

Learn how to use the Braze provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Braze](https://braze.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Braze provider in the email channel, you will need to create a [Braze account](https://braze.com/) and add your API key and other credentials to the Braze integration on the Novu platform.

## Generating an API Key

To generate a new API key in Braze, you can follow these steps:

* [Sign up](https://braze.com) or [Log in](https://braze.com) to your Braze account.
* Go to **Settings > API Keys**.
* Click **+ Create New API Key**.
* Give your new key a name for identification at a glance.
* Select the right permission you want to be associated with the new API key.

## Creating a Braze integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-braze) page on Novu.
* Click on `Add a Provider`.
* Locate **Braze** under the Email section and click on the **Next** button.
* Select Your Environment add condition (Optional).
* Click on the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `API Key`.
* Enter the `Base URL`.
* Enter the `From email address`.
* Enter the `Sender name`.
* Click on the **Update** button.

## Next Steps

<EmailProviderNextSteps />


# Brevo (Sendinblue) integration guide (/platform/integrations/email/brevo)

Learn how to use the Sendinblue provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

You can use the [Brevo](https://www.brevo.com/) provider to send transactional emails to your customers using the Novu Platform with a single API.

## Getting Started

To use the Brevo provider in the email channel, you will need to create a Brevo account and add your API key to the Brevo integration on the Novu platform.

## Finding the API Key

* To find your Brevo API key, log into your Brevo account and navigate to the [API Keys](https://account.brevo.com/advanced/api) page.

## Authenticating your sender identity

Before you can send emails on a large scale, you will need to authenticate your sender's identity. This is due to the latest regulatory changes regarding SPAM rules and email fraud. Most of the providers including Brevo require you to authenticate your sender identity before you can send emails.

Brevo allows you to authenticate your sender identity using one of the following methods:

* [Single Sender Verification](https://account.brevo.com/senders) - This is the easiest way to authenticate your sender identity.
* [Entire Domain Authentication](https://help.brevo.com/hc/en-us/articles/12163873383186-Authenticate-your-domain-with-Brevo-Brevo-code-DKIM-record-DMARC-record) - This is recommended if you are sending emails from multiple accounts under your domain.

## Creating a Brevo integration with Novu

* Visit the [Integrations store](https://dashboard.novu.co/integrations?utm_campaign=docs-brevo) on the Novu web dashboard.
* Click on Add a Provider.
* Select Brevo service.
* Enter your Brevo API key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Brevo in Novu.

## Next Steps

<EmailProviderNextSteps />


# Custom SMTP (/platform/integrations/email/custom-smtp)

Learn how to use the Custom SMTP provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use a Custom SMTP provider like [Nodemailer](https://nodemailer.com/about/) to send transactional emails through your custom SMTP server to your customers using the Novu Platform with a single API.

## Getting Started

To use the Custom SMTP provider in the email channel, you will need to have your personal SMTP server configured and add `host`, `port`, `user`, and `password` to the Custom SMTP integration on the Novu platform.

You can also provide value **`true`** for the `secure` field if you want the connection to be secure, and if not, leave it empty.

### DKIM (DomainKeys Identified Mail)

DKIM options can be used in order to sign messages sent using Custom SMTP with DKIM keys.

Those options are:

* `DKIM Domain`
* `DKIM Private Key`
* `DKIM Key Selector`

## Creating a Custom SMTP integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-customsmtp) page on Novu.
* Click on Add a Provider.
* Select Custom SMTP service.
* Enter your SMTP credentials
  * `host`
  * `port`
  * `username`
  * `password`
  * `secure` (on demand)
  * And `DKIM` options if you want to sign messages with *DKIM*
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Custom SMTP in Novu.

## Next Steps

<EmailProviderNextSteps />


# Infobip email integration guide (/platform/integrations/email/infobip)

Learn how to use the Infobip provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Infobip](https://www.infobip.com/developers/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Infobip provider in the email channel, you will need to create an Infobip account and add your API key and Base URL to the Infobip integration on the Novu platform.

## Generating an API Key

To generate a new API key in Infobip, you can follow these steps:

* [Sign up](https://www.infobip.com/signup) or [Log in](https://portal.infobip.com/login/) to your Infobip account.
* Navigate to the [Settings](https://portal.infobip.com/settings/accounts/api-keys) of your account and look for the API Keys section at the top of the settings page.

## Creating an Infobip integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-infobip) page on Novu.
* Click on Add a Provider.
* Select Infobip service.
* Enter your Infobip API Key.
* Enter your Base URL.
  * To see your base URL, log in to the account. Once logged in, on all pages, you should see your base URL in this format: `xxxxx.api.infobip.com`.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Fill in the `Sender's name`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Infobip in Novu.

## Next Steps

<EmailProviderNextSteps />


# MailerSend (/platform/integrations/email/mailersend)

Learn how to use the MailerSend provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[MailerSend](https://www.mailersend.com/) is an email delivery service that allows you to send emails from your application.

## Getting Started

To use the MailerSend provider in the email channel, you will need to create a MailerSend account and add your API key to the MailerSend integration on the Novu platform. To generate the API token go visit the [MailerSend API Tokens](https://www.mailersend.com/help/managing-api-tokens) page.

## Creating the MailerSend integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-mailersend) page on Novu.
* Click on Add a Provider.
* Select MailerSend service.
* Enter the API key.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using MailerSend in Novu.

## Using MailerSend template

Novu has its own email editor for writing email template. If you want to use pre made template from MailerSend, you can use `customData` filed of email overrides to send template details. Make sure your `Api Key` has enough permission to read and process the template.

<Callout type="info">
  sending `customData` field in overrides to send mailersend template will work only in following cases:

  * if workflow is triggered to only one subscriber
  * if workflow is triggered to multiple subscribers or topic but mailersend template does not have any dynamic variables related to subscriber attributes like `firstName`, `lastName`, `email`, etc as same overrides will be applied to all subscribers or topic
</Callout>

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: "subscriberId",
      payload: {},
      overrides: {
        email: {
          customData: {
            // mailersend template templateId 
            templateId: "mailersend-template-id",
            // mailersend template variables 
            personalization: [{
              email: 'recipient@email.com',
              data: {
                items: {
                  price: '',
                  product: '',
                  quantity: '',
                },
                order: {
                  date: '',
                  order_number: '',
                  billing_address: '',
                  customer_message: '',
                },
                store: {
                  name: '',
                },
                invoice: {
                  total: '',
                  subtotal: '',
                  pay_method: '',
                },
                customer: {
                  name: '',
                  email: '',
                  phone: '',
                },
              },
            }, ],
          },
        }
      },
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl --location 'https://api.novu.co/v1/events/trigger' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    --data '{
        "name": "workflowIdentifier",
        "to":  ["subscriberId"],
        "payload": {},
        "overrides": {
            "email": {
                "customData": {
                    "templateId": "mailersend-template-id",
                    "personalization": [{
                        "email": "recipient@email.com",
                        "data": {
                            "items": {
                                "price": "",
                                "product": "",
                                "quantity": ""
                            },
                            "order": {
                                "date": "",
                                "order_number": "",
                                "billing_address": "",
                                "customer_message": ""
                            },
                            "store": {
                                "name": ""
                            },
                            "invoice": {
                                "total": "",
                                "subtotal": "",
                                "pay_method": ""
                            },
                            "customer": {
                                "name": "",
                                "email": "",
                                "phone": ""
                            }
                        }
                    }]
                }
            }
        }
    }'
    ```
  </Tab>
</Tabs>

## Next Steps

<EmailProviderNextSteps />


# Mailgun email integration guide (/platform/integrations/email/mailgun)

Learn how to use the Mailgun provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Mailgun](https://mailgun.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Mailgun provider in the email channel, you will need to create a Mailgun account and add your API key and domain name to the Mailgun integration on the Novu platform.

## Generating an API Key

To generate a new API key in Mailgun, you can follow these steps:

* [Sign up](https://signup.mailgun.com/new/signup) or [Log in](https://login.mailgun.com/login/) to your Mailgun account.
* Click on the **Profile** section in the top right corner of the screen, and then click "API Keys" from the drop-down menu.
* On the [API Keys](https://app.mailgun.com/app/account/security/api_keys) page, copy the generated **Private API Key**

## Adding a new domain name

Mailgun recommends that you add a subdomain as a domain name. To do so:

* Visit the page to add a [domain name](https://app.mailgun.com/app/sending/domains/new).
  * During this process, you will need to choose a region for the domain name which is between `US` and `EU`. The default is `US`.
* Follow the [instructions](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain-1) to verify the domain name.

## Creating a Mailgun integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-mailgun) page on Novu.
* Click on Add a Provider.
* Select Mailgun service.
* Enter your Mailgun API Key.
* Enter your Base URL.
  * For domains created in the EU region, the base URL is: `https://api.eu.mailgun.net/`
  * Otherwise, leave the base URL blank.
* Fill in the `Username`.
* Fill in the `Domain name` registered on Mailgun.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Fill in the `Sender's name`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Mailgun in Novu.

## Next Steps

<EmailProviderNextSteps />


# Mailjet email integration guide (/platform/integrations/email/mailjet)

Learn how to use the Mailjet provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Mailjet](https://mailjet.com/) provider to send transactional emails to your customers using the Novu Platform with a single API.

## Getting Started

To use the Mailjet provider in the email channel, you will need to create a Mailjet account and add your API key to the Mailjet integration on the Novu platform.

## Generating an API Key

To generate a new API key in Mailjet, you can follow these steps:

* Log in to your Mailjet account.
* Click on **Settings** in the top-right corner of the screen, and then click **API KEYS & TRACKING** from the drop-down menu.
* On the API Keys page, click the **Create an API Key** button.
* Give the API key a name and choose the access level **Write and Read**
* Click the **Generate Key** button to create the new key. Once generated you can see the key but it will be hidden after the refresh

## Authenticating your sender identity

Before you can send emails on a large scale, you will need to authenticate your Sender identity. This is due to the latest regulatory changes regarding SPAM rules and email fraud. Most of the providers including Mailjet require you to authenticate your Sender identity before you can send emails.

Mailjet allows you to authenticate your sender identity using one of the following methods:

* [Single Sender Verification](https://dev.mailjet.com/email/guides/senders-and-domains/#sender-validation) - This is the easiest way to authenticate your sender identity.
* [Entire Domain Authentication](https://dev.mailjet.com/email/guides/senders-and-domains/#spf-and-dkim-validation) - This is recommended if you are sending emails from multiple accounts under your domain.

## Creating a Mailjet integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-mailjet) page on Novu.
* Click on Add a Provider.
* Select Mailjet service.
* Enter your Mailjet API key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Mailjet in Novu.

## Next Steps

<EmailProviderNextSteps />


# Mailtrap Email Provider (/platform/integrations/email/mailtrap)

Learn how to use the Mailtrap provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Mailtrap](https://mailtrap.io/email-sending/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Mailtrap provider in the email channel, you will need to create a Mailtrap account and add your API key to the Mailtrap integration on the Novu platform.

## Generating an API Key

To generate a new API key in Mailtrap, you can follow these steps:

* [Sign Up](https://mailtrap.io/register/signup) or [Log in](https://mailtrap.io/signin) to your Mailtrap account.
* Click on the **Email Sending** link on the sidebar, and then click the "Sending Domains" link that pops up from the available options.
* On the [Sending Domains](https://mailtrap.io/sending/domains) page, type your domain name and confirm with the `Add Your Domain` button. Then, proceed to copy DNS records Mailtrap provides to your domain’s DNS.
* Go to [API Keys](https://mailtrap.io/api-tokens) page and copy token with `Domain Admin` access level for your registered domain.

## Authenticating your Sender Identity

Before you can send emails, you will need to [verify your sending domain ownership](https://help.mailtrap.io/article/69-sending-domain-setup). Mailtrap rejects sending emails from unverified domains to prevent spam and email fraud.

## Creating a Mailtrap integration with Novu

* Visit the [Integrations store](https://dashboard.novu.co/integrations?utm_campaign=docs-mailtrap) on the Novu web dashboard.
* Click on Add a Provider.
* Select Mailtrap service.
* Enter your Mailtrap API Key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications through Mailtrap using Novu.

## Next Steps

<EmailProviderNextSteps />


# Mandrill Email Provider (/platform/integrations/email/mandrill)

Learn how to use the Mandrill provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Mandrill by Mailchimp](https://mandrillapp.com/) provider to send transactional emails to your customers using the Novu Platform with a single API.

## Getting Started

To use the Mandrill provider in the email channel, you will need to create a Mandrill account and add your API key to the Mandrill integration on the Novu platform.

## Generating an API Key

To generate a new API key in Mandrill, you can follow these steps:

* [Sign up](https://login.mailchimp.com/signup/) or [Log in](https://login.mailchimp.com/) to your Mandrill account.
* Navigate to the [Settings](https://mandrillapp.com/settings) of your account and look for the API Keys section at the bottom of the settings page.
* Click on the **+ Add API Key** button to create an API key. Copy the generated key immediately and store it in a secure location. You won’t be able to see or copy the key once you finish generating it.

## Adding a sending domain

To get started, you’ll need to add the domain that you want to send messages from.

* Navigate to the [Settings page](https://mandrillapp.com/settings/sending-domains) and choose Domains
* Type a new domain in the domain input and click Add
* Follow the instructions to [verify ownership](https://mailchimp.com/developer/transactional/docs/authentication-delivery/#authentication) of your sending domain and [update your DNS records](https://mailchimp.com/developer/transactional/docs/authentication-delivery/#configure-your-dns).

## Creating the Mandrill integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-mandrill) page on Novu.
* Click on Add a Provider.
* Select Mandrill service.
* Enter your Mandrill API key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Fill in the `Sender's name`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Mandrill in Novu.

## Next Steps

<EmailProviderNextSteps />


# Maqsam SMS Provider (/platform/integrations/email/maqsam)

Learn how to use the Maqsam provider to send sms notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Maqsam](https://maqsam.com/) provider to send SMS messages to your customers using the Novu platform with a single API to create multi-channel experiences.

## Getting Started

To use the Maqsam provider in the sms channel, you will need to create a Maqsam account and add your access key & secret to the Maqsam integration on the Novu platform. Contact `support@maqsam.com` to enable the API feature for your account, then you can generate `access_key_id` and `access_secret` combination from the account settings.

## Creating the Maqsam integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-maqsam) page on Novu.
* Click the "Add a provider" button.
* Select Maqsam service
* Click `Next`
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Maqsam in Novu.

## Next Steps

<EmailProviderNextSteps />


# Netcore Email Provider (/platform/integrations/email/netcore)

Learn how to use the Netcore provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Netcore](https://netcorecloud.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Netcore provider in the email channel, you will need to create a Netcore account and add your API key to the Netcore integration on the Novu platform.

## Generating an API Key

To generate a new API key in Netcore, you can follow these steps:

* [Log in](https://email.netcorecloud.com/) to your Netcore account.
* Go to the **Integration** page under the **Settings** menu and click on the **API** tab.
* The API Key is hidden for security purposes. Click Show. The system will prompt you to enter your account password. Once you enter the password, the API key will be accessible.

## Setting up sending domains

To start sending emails, you need to add and verify your sending domains. You can either use your top-level domain (e.g. my-company.com) or a sub-domain like email.my-company.com. The verification is done to ensure your sending domain’s security.

Follow the instructions on this [page](https://emaildocs.netcorecloud.com/docs/what-is-a-sending-domain-how-to-set-up-sending-domains) to get started

## Creating a Netcore integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-netcore) page on Novu.
* Click on Add a Provider.
* Select Netcore service.
* Enter your Netcore API Key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Fill in the `Sender's name`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Netcore in Novu.

## Next Steps

<EmailProviderNextSteps />


# Outlook 365 (/platform/integrations/email/outlook365)

Learn how to use the Outlook 365 provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Outlook 365](https://office.com/) provider to send transactional emails through your instance of Office 365 to your customers using the Novu Platform with a single API.

## Getting Started

To use the Outlook 365 provider in the email channel, you will need to have the sender's email (user) and the password for the account. This account cannot be a shared mailbox or distribution list. It will need to be properly licensed to send email via Office 365.

## Creating the Outlook 365 integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-office365) page on Novu.
* Click on Add a Provider.
* Select Outlook service.
* Enter your SMTP credentials
  * `from`: The Complete email address of the sending user. (e.g. [jdoe@mycompany.com](mailto:jdoe@mycompany.com))
  * `senderName`: Sender Name should be the same email address of the sending user. (e.g. [jdoe@mycompany.com](mailto:jdoe@mycompany.com))
  * `password`: Password used to sign in with the email account.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Outlook 365 in Novu.

<Callout type="info">
  In order to create outlook integration, turn off multi factor authentication from account security
  settings.
</Callout>

## Next Steps

<EmailProviderNextSteps />


# Plunk email integration guide (/platform/integrations/email/plunk)

Learn how to use the Plunk provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Plunk](https://useplunk.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Plunk provider in the email channel, you will need to create a Plunk account and add your API key to the Plunk integration on the Novu platform.

## Get API Key

To generate a new API key in Plunk, you can follow these steps:

* Log in to your Plunk account.
* Click on `Project Settings` on the side bar and then `API keys` on the tab.
* On the API Keys page, click on `Secret API key` to copy.

## Authenticate your sender identity

Before you can send emails on a large scale, you will need to authenticate your Sender Identity. Plunk allows you to authenticate your sender identity using [Domain Authentication](https://app.useplunk.com/settings/identity)

## Create a Plunk integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-plunk) page on Novu.
* Click on Add a Provider.
* Select Plunk service.
* Enter your Plunk secret API Key.
* Fill the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Plunk in Novu.

## Next Steps

<EmailProviderNextSteps />


# Postmark Email Provider (/platform/integrations/email/postmark)

Learn how to use the Postmark provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

It is possible to use [Postmark](https://postmarkapp.com/) as a provider to send transactional emails to your customers using the Novu Platform with a single API.

## Getting Started

The first step to use the Postmark provider in the email channel is to create a Postmark account and add the personal API key to the Postmark integration on the Novu platform.

## Getting the API Key

* To find the Postmark API key, log into the personal Postmark account and navigate to the servers page.
* After selecting the server to use, the API key (referred to as "Server API tokens") will be in the "API Tokens" section of the server chosen.

## Authenticating the sender's identity

Due to the latest regulatory changes regarding SPAM rules and email fraud, it is needed to authenticate the sender's identity before sending emails on a large scale. Most of the providers, including Postmark, require authentication to unlock the possibility of sending emails.

Postmark allows the authentication of the sender's identity using one of the following methods:

* [Single Sender Verification](https://account.postmarkapp.com/signatures/new) - This is the easiest way to authenticate the sender's identity.
* [Entire Domain Authentication](https://postmarkapp.com/support/article/1046-how-do-i-verify-a-domain#:~:text=be%20verified%20automatically.-,Navigate%20to%20Sender%20Signatures.,to%20your%20DNS%2C%20choose%20Verify.) - This is recommended for sending emails from multiple accounts under the same domain.

## Create a Postmark integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-postmark) page on Novu.
* Click on Add a Provider.
* Select Postmark service.
* Enter the Postmark API key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* Now is possible to send notifications using Postmark in Novu.

## Next Steps

<EmailProviderNextSteps />


# Resend email integration guide (/platform/integrations/email/resend)

Learn how to use the Resend provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [Resend](https://resend.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Resend provider in the email channel, you will need to create a Resend account and add your API key to the Resend integration on the Novu platform.

## Generating an API Key

To generate a new API key in Resend, you can follow these steps:

* [Sign up](https://resend.com/secret) or [Log in](https://resend.com/login) to your Resend account.
* Click on the **API Keys** link in the left sidebar, and then click the "Create API Key" button on the top right part of the page.
* On the [API Keys](https://resend.com/api-keys) page, click the **Create API Key** button.
* Give the API key a name and click on the **Add** button.
* Copy the generated API Key.

## Authenticating your Sender Identity

Before you can send emails on a large scale, you will need to authenticate your Sender Identity.

Resend allows you to authenticate your sender identity using [Domain Authentication](https://resend.com/docs/dashboard/domains/introduction).

## Creating a Resend integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-resend) page on Novu.
* Click on Add a Provider.
* Select Resend service.
* Enter your Resend API Key.
* Fill in the `From email address` field using the authenticated email from the previous step.
  * For testing, you can use `onboarding@resend.dev` if you have not authenticated your sender identity.
* Fill in the `Sender's name`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Resend in Novu.

## Next Steps

<EmailProviderNextSteps />


# SendGrid Email Integration (/platform/integrations/email/sendgrid)

Learn how to use the SendGrid provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

You can use the [SendGrid](https://sendgrid.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

### Getting Started

To use the Sendgrid provider in the email channel, you will need to create a Sendgrid account and add your API key to the SendGrid integration on the Novu platform.

### Generating an API Key

To generate a new API key in SendGrid, follow these steps:

* Log in to your SendGrid account.
* Click on the **Settings** gear icon in the top right corner of the screen, and then click "API Keys" from the drop-down menu.
* On the API Keys page, click the **Create API Key** button.
* Give the API key a name and select the following permissions
* **Mail Send** - Full Access
* (Optional) Template Engine - Read Only
* Click the **Create & View** button to generate the API key. The key will be displayed on the screen, but you will only be able to view it once, so make sure to save it in a safe place.

NOTE

The access level of the key will determine what actions the API Key can take, so please choose the correct one.

* **Mail Send** - Full Access
* (Optional) Template Engine - Read Only

### Authenticating your [Sender Identity](https://docs.sendgrid.com/for-developers/sending-email/sender-identity)

Before you can send emails on a large scale, you will need to authenticate your Sender Identity. This is due to the latest regulatory changes regarding SPAM rules and email fraud. Most of the providers including Sendgrid require you to authenticate your Sender Identity before you can send emails.

SendGrid allows you to authenticate your sender identity using one of the following methods:

* [Single Sender Verification](https://docs.sendgrid.com/ui/sending-email/sender-verification) - This is the easiest way to authenticate your sender identity.
* [Entire Domain Authentication](https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication) - This is recommended if you are sending emails from multiple accounts under your domain.

### SendGrid integration with Novu

* Visit the [Integrations store](https://dashboard.novu.co/integrations?utm_campaign=docs-sendgrid) on the Novu web dashboard.
* Click on Add a Provider.
* Select SendGrid service.
* Enter your SendGrid API Key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications through SendGrid using Novu.

### Using SendGrid template

Novu has its own email editor for writing email template. To send pre-made template in SendGrid, providers overrides can be used to send template details. Make sure sendgrid `Api Key` has enough permission to read and process the template.

<Callout type="info">
  Sending `customData` field in overrides to send sendgrid template will work
  only in following cases:

  * if workflow is triggered to only one subscriber
  * if workflow is triggered to multiple subscribers or topic but sendgrid
    template does not have any dynamic variables related to subscriber attributes
    like `firstName`, `lastName`, `email`, etc as same overrides will be applied
    to all subscribers.
</Callout>

<Tabs items={['Node.js', 'cURL', 'Novu Framework']}>
  <Tab value="Node.js">
    ```typescript
    import {
      Novu
    } from "@novu/api";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      payload: {},
      overrides: {
        providers: {
          sendgrid: {
            templateId: "d-d965b02b1b5d4856bf332a5e98c7470c",
            dynamicTemplateData: {
              total: "$ 239.85",
              items: [{
                text: "New Line Sneakers",
                image: "https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
                price: "$ 79.95",
              }, {
                text: "Old Line Sneakers rlfjrjrh4hr4rh4",
                image: "https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
                price: "$ 79.95",
              }, ],
              receipt: true,
              name: "Sample Name",
              address01: "1234 Fake St.",
              address02: "Apt. 123",
              city: "Place",
              state: "CO",
              zip: "80202",
            },
          },
        },
      },
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl --location 'https://api.novu.co/v1/events/trigger' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    --data '{
        "name": "workflowIdentifier",
        "to":  ["subscriberId"],
        "payload": {},
        "overrides": {
            "providers": {
                "sendgrid": {
                    "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c",
                    "dynamicTemplateData": {
                        "total": "$ 239.85",
                        "items": [
                            {
                                "text": "New Line Sneakers",
                                "image": "https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
                                "price": "$ 79.95"
                            },
                            {
                                "text": "Old Line Sneakers rlfjrjrh4hr4rh4",
                                "image": "https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
                                "price": "$ 79.95"
                            }
                        ],
                        "receipt": true,
                        "name": "Sample Name",
                        "address01": "1234 Fake St.",
                        "address02": "Apt. 123",
                        "city": "Place",
                        "state": "CO",
                        "zip": "80202"
                    }
                }
            }
        }
    }'
    ```
  </Tab>

  <Tab value="Novu Framework">
    ```typescript
    import { workflow } from "@novu/framework";
    import { z } from "zod";

    export const sendgridOverridesEmailExample = workflow(
      "sendgrid-email-overrides",
      async ({ step, payload }) => {
        await step.email(
          "sendgrid-email-overrides",
          async () => {
            return {
              subject: "SendGrid Overrides Example",
              body: "This body content should be overridden by the SendGrid template",
            };
          },
          {
            providers: {
              sendgrid: ({}) => ({
                _passthrough: {
                  body: {
                    templateId: payload.dynamicTemplateId,
                    dynamicTemplateData: {
                      // Example variables to be used in the template
                      total: "$ 239.85",
                      items: [
                        {
                          text: payload.itemName,
                          image:
                            "https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png",
                          price: "$ 79.95",
                        },
                        {
                          text: "Old Line Sneakers rlfjrjrh4hr4rh4",
                          image:
                            "https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png",
                          price: "$ 79.95",
                        },
                      ],
                      receipt: true,
                      name: "Sample Name",
                      address01: "1234 Fake St.",
                      address02: "Apt. 123",
                      city: "Place",
                      state: "CO",
                      zip: "80202",
                    },
                  },
                },
              }),
            },
          }
        );
      },
      {
        payloadSchema: z.object({
          itemName: z.string().default("New Line Sneakers"),
          dynamicTemplateId: z
            .string()
            .default("d-d965b02b1b5d4856bf332a5e98c7470c"),
        }),
      }
    );
    ```
  </Tab>
</Tabs>

## Next Steps

<EmailProviderNextSteps />


# Sparkpost (/platform/integrations/email/sparkpost)

Learn how to use the Sparkpost provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

You can use the [SparkPost](https://messagebird.com/email/cloud-sending) provider to send transactional emails to your customers using the Novu Platform with a single API.

## Getting Started

To use the SparkPost provider in the email channel, you will need to create a SparkPost account and add your API key to the SparkPost integration on the Novu platform.

## Generating an API Key

To generate a new API key in SparkPost, you can follow these steps:

* [Sign up](https://app.sparkpost.com/join) or [Log in](https://app.sparkpost.com/auth) to your SparkPost account.
  > During sign up, note that SparkPost is available in multiple regions. "SparkPost" refers to the SparkPost service hosted in North America. "SparkPost EU" refers to the SparkPost service hosted in Western Europe. An account created with SparkPost cannot be used with SparkPost EU, and vice-versa. You may use accounts in both regions.
  >
  > \~ *[SparkPost Documentation](https://support.sparkpost.com/docs/getting-started/getting-started-sparkpost/)*
* Click on the **Configuration** link on the navbar, and then click the "API Keys" link that pops up from the available options.
* On the [API Keys](https://app.sparkpost.com/account/api-keys) page, click the **Create API Key** button.
* Give the API key a name and click on the **Create API key** button.
* Copy the generated API Key.

## Authenticating your Sender Identity

Before you can send emails on a large scale, you will need to authenticate your Sender Identity.

SparkPost allows you to authenticate your sender identity using [Sending Domains](https://app.sparkpost.com/domains/list/sending).

## Creating a SparkPost integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sparkpost) page on Novu.
* Click on Add a Provider.
* Select SparkPost service.
* Enter your SparkPost API Key.
* Fill in the `From email address` field using the authenticated email from the previous step.
* Fill in the `Sender's name`.
* Toggle the `eu` switch to true if you're in Western Europe
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using SparkPost in Novu.

## Next Steps

<EmailProviderNextSteps />


# Email Webhook (/platform/integrations/email/webhook)

Learn how to use the Email Webhook provider to send email notifications using Novu

import { EmailProviderNextSteps } from '@/snippets/channels/email/email-provider-next-steps.tsx';

[Email Webhooks](https://www.socketlabs.com/blog/what-is-a-webhook/#:~:text=Email%20webhooks%20are%20an%20extremely,%2C%20successful%20messages%2C%20and%20bounces.) are an extremely flexible way for developers to monitor the health of their mail stream in real time

## Getting Started

First go to [Email Settings](https://dashboard.novu.co/settings/email?utm_campaign=docs-webhook) in Settings menu to configure Email Webhook.

## Creating the Email Webhook integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-webhook) page on Novu.
* Click the "Add a provider" button.
* Select Email Webhook service
* Click `Next`
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Add `Webhook URL` & `Secret Hmac Key` to sign off the email
* Finally add `From email address` & `Sender name` to identify email sender
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using Email Webhook in Novu.

## Next Steps

<EmailProviderNextSteps />


# Email Activity Tracking (/platform/integrations/email/activity-tracking)

Learn how to enable activity tracking to get real-time delivery and engagement events like delivered, opened, and clicked from your email providers.

Activity tracking gives you visibility into what happens to notifications after they are sent to the subscriber. With it, Novu receive and process real-time events from third-party providers, so that you know when the notification is delivered, opened, clicked, or bounced.

## How activity tracking works

When your provider emits an event (for example, an email delivered or bounced), Novu:

* Receives the event via inbound webhooks.
* Create step-run trace, so the event is visible in the activity feed.
* Forwards supported events to outbound webhooks if they are enabled in your project.
* Enriches the workflow-run lifecycle with engagement and delivery data, which empowers analytics and workflow variables.

With activity tracking enabled, you get a full picture of the workflow-run lifecycle, not just that a message was “sent,” but whether it reached the recipient, was opened, or engaged with. This closes the feedback loop and allows you to build more reliable notification experiences.

## How to enable activity tracking

First [create the integration](/platform/integrations/email/adding-email). After that, you can enable activity tracking by following these steps:

1. Log in to the Novu dashboard
2. Navigate to the **Integrations Store** page from the sidebar of your Novu dashboard.
3. Click **Connect Provider** and select the email provider you want to configure.
4. Scroll down to find the **Email Activity Tracking** section and click the toggle to enable it.
   ![Enable the inbound webhook](/images/developer-tools/enable-inbound.png)
   When enabled, Novu will auto-configure delivery webhooks using your existing API key.
   ![Inbound webhook enabled](/images/developer-tools/inbound-enabled.png)

## Manual configuration

If auto-configuration fails or isn’t supported for your provider, you will need to set it up manually. You can do that by  following these provider specific guides:

<Cards>
  <Card title="Amazon SES" href="/platform/integrations/email/activity-tracking/manual-configuration/ses">
    Manual configuration for Amazon SES Email Activity Tracking
  </Card>

  <Card title="Mailgun" href="/platform/integrations/email/activity-tracking/manual-configuration/mailgun">
    Manual configuration for Mailgun Email Activity Tracking
  </Card>

  <Card title="SendGrid" href="/platform/integrations/email/activity-tracking/manual-configuration/sendgrid">
    Manual configuration for SendGrid Email Activity Tracking
  </Card>

  <Card title="Resend" href="/platform/integrations/email/activity-tracking/manual-configuration/resend">
    Manual configuration for Resend Email Activity Tracking
  </Card>
</Cards>

## Event semantics in Novu

Inbound webhook events are normalized into a consistent set of Novu event statuses. These statuses let you track the full lifecycle of a notification across providers in a unified way.

| Novu status    | Meaning                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `blocked`      | The provider refused to send the message because the recipient is on a suppression or block list. |
| `bounced`      | The message was rejected by the recipient’s server (hard or soft bounce).                         |
| `clicked`      | The recipient clicked a link inside the message.                                                  |
| `complaint`    | The recipient marked the message as spam or filed a complaint.                                    |
| `delayed`      | The provider delayed the message delivery (for example, due to throttling).                       |
| `delivered`    | The provider confirmed that the message was delivered to the recipient’s server.                  |
| `dropped`      | The provider dropped the message before attempting delivery.                                      |
| `opened`       | The recipient opened the message (tracked via the provider’s open logic).                         |
| `rejected`     | The provider could not send the message (for example, invalid address, failed policy check).      |
| `sent`         | The provider has accepted the message for delivery.                                               |
| `unsubscribed` | The recipient unsubscribed from further messages.                                                 |

## Supported providers and events

Novu currently supports inbound webhooks for several email providers. Each provider sends events in its own format, which Novu normalizes into a consistent set of internal statuses. These normalized statuses are used in the activity feed, step-run traces, and outbound webhook forwarding.

Events not listed in the tables below are ignored.

### SendGrid

| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
| ---------------------------------- | ---------------------------------- |
| `blocked`                          | `blocked`                          |
| `bounce`                           | `bounced`                          |
| `click`                            | `clicked`                          |
| `delivered`                        | `delivered`                        |
| `dropped`                          | `dropped`                          |
| `open`                             | `opened`                           |

### Mailgun

| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
| ---------------------------------- | ---------------------------------- |
| `clicked`                          | `clicked`                          |
| `complained`                       | `complaint`                        |
| `delivered`                        | `delivered`                        |
| `opened`                           | `opened`                           |
| `permanent_fail`, `failed`         | `rejected`                         |
| `unsubscribed`                     | `unsubscribed`                     |

### Resend

| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
| ---------------------------------- | ---------------------------------- |
| `email.bounced`                    | `bounced`                          |
| `email.clicked`                    | `clicked`                          |
| `email.complained`                 | `complaint`                        |
| `email.delivered`                  | `delivered`                        |
| `email.delivery_delayed`           | `delayed`                          |
| `email.failed`                     | `rejected`                         |
| `email.opened`                     | `opened`                           |
| `email.sent`                       | `sent`                             |

### Amazon SES

| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
| ---------------------------------- | ---------------------------------- |
| `Bounce`                           | `bounced`                          |
| `Complaint`                        | `complaint`                        |
| `Click`                            | `clicked`                          |
| `Delivery`                         | `delivered`                        |
| `DeliveryDelay`                    | `delayed`                          |
| `Open`                             | `opened`                           |
| `Reject`                           | `rejected`                         |
| `Send`                             | `sent`                             |

## Viewing event data

Once your inbound webhooks are configured, Novu will start processing events from your provider. You can see this new data in two key places within the platform.

### Activity feed

The Activity Feed provides the most direct view of the notification lifecycle. After a notification is sent, you will see new status updates such as Delivered, Opened, and Clicked appear in the timeline as they are received from your provider. This gives you a complete, real-time picture of subscriber engagement for each notification.

### Outbound webhooks integration

Inbound webhooks don’t just update Novu internally, they can also trigger outbound webhooks, allowing you to send normalized events to your own systems in real time. This makes it possible to extend Novu’s notification lifecycle into your existing infrastructure.

How it works:

1. A provider emits an event (for example, delivered).
2. Novu receives and normalizes the event (for example, → delivered).
3. Novu updates its internal message entity and step-run trace.
4. If outbound webhooks are enabled, Novu forwards the normalized event to your configured outbound webhook endpoint.

This is useful in a number of use cases including:

* Internal logging: Forward all events into your organization’s centralized logging pipeline.
* Custom analytics: Combine Novu’s lifecycle data with your own metrics to measure engagement and delivery performance.
* Workflow triggers: Kick off custom business logic when specific events occur (for example, flagging accounts with high bounce rates).


# Apple Push Notification Service (APNS) (/platform/integrations/push/apns)

Learn how to use the Apple Push Notification Service (APNS) provider to send push notifications using Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

This guide explains how to configure and use the <a href="https://developer.apple.com/notifications/" target="_blank" rel="noopener noreferrer">Apple Push Notification Service (APNS)</a> with Novu to deliver push notifications to iOS devices. It outlines:

* The required setup in your Apple Developer account.
* The connection process in Novu.
* How to manage device tokens and message payloads.

## Configuring APNS with Novu

Before sending notifications, APNS must be configured with the correct credentials from your Apple Developer account. Novu uses these credentials to securely authenticate with Apple’s servers.

### Obtain APNS credentials

Apple provides two authentication options for connecting to APNS:

* A certificate-based `.p12` certificate
* A token-based `.p8` key

Novu supports both, but this guide focuses on the `.p8` token-based approach, which is recommended for most production setups.

To generate the required credentials, use an <a href="https://developer.apple.com/" target="_blank" rel="noopener noreferrer">Apple Developer account</a> with an [Admin role](https://appstoreconnect.apple.com/access/users). Follow <a href="https://developer.apple.com/help/account/keys/create-a-private-key" target="_blank" rel="noopener noreferrer">Apple’s official steps</a> to create and download a private `.p8` key.

The following identifiers are also needed for integration:

* <a href="https://developer.apple.com/help/account/keys/get-a-key-identifier/" target="_blank" rel="noopener noreferrer">**Key ID**</a>: A unique 10-character identifier for the authentication key.
* **Team ID**: This is found in your Apple Developer account.
* **Bundle ID**: The identifier for your app, which is available in the app info section.

### Add APNS credentials to Novu

Once the Apple credentials are available, you can add them in Novu’s Integration Store.

1. Log in to your Novu account.
2. On your dashboard, click **Integration Store**.
3. Click **Connect provider**.
4. Click the **Push** tab.
5. Select **APNS**.
6. In the APNS integration form, fill in the **Name** and **Identifier** fields.
7. In the **Delivery Provider Credentials** section, fill in the following fields:
   * **Private Key**: The content of your `.p8` file.
   * **Key ID**: Your 10-character Key ID.
   * **Team ID**: Your 10-character Team ID.
   * **Bundle ID**: Your app's Bundle ID.
     ![APNS Integration in Novu](/images/channels-and-providers/push/apns/apns-integration.png)
8. Click **Create Integration**.

## Sending notifications with APNS

After configuration, APNS can be used in any Novu workflow that includes a Push step. The process involves registering device tokens for subscribers and then triggering workflows to deliver messages.

### Registering subscriber device tokens

Each subscriber (user) must have one or more device tokens registered to receive push notifications. Tokens can be added or updated through Novu’s API using the [Update Subscriber Credentials](/api-reference/subscribers/update-provider-credentials) endpoint.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "[https://eu.api.novu.co](https://eu.api.novu.co)",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.Apns,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "string",
        credentials: {
          deviceTokens: ["token1", "token2", "token3"],
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "apns",
      "deviceTokens": ["token1", "token2"],
      "integrationIdentifier": "string"
    }'
    ```
  </Tab>
</Tabs>

### Triggering workflows

Once subscribers’ devices are registered, push notifications are delivered through [workflows that include a Push step](/platform/workflow/create-a-workflow). A workflow can be triggered using the Novu [SDK](/platform/sdks) or [API](/api-reference/events/trigger-event).

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // Your payload data
  },
});
```

## Customizing notifications with overrides

Novu supports an `overrides` field that lets you attach APNS-specific payload parameters when triggering a workflow. This feature is useful for customizing the behavior or presentation of notifications, such as setting titles, bodies, or custom data fields.

The `overrides` field supports all <a href="https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc" target="_blank" rel="noopener noreferrer">APNS Notification payload</a> values. Here is an example:

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    abc: 'def', // If the notification is a data notification, then the payload is sent as the data
  },
  overrides: {
    apns: {
      payload: {
        aps: {
          notification: {
            title: 'Test',
            body: 'Test push',
          },
          data: {
            key: 'value',
          },
        },
      },
    },
  },
});
```


# Expo Push (/platform/integrations/push/expo-push)

Learn how to use the Expo Push provider to send push notifications using Novu

This guide explains the process of configuring and using Expo Push with Novu, from getting your credentials to sending your first notification.

## How to configure Expo with Novu

Before you can send notifications, you must connect your Expo project to Novu by generating an access token and adding it to your integration settings.

### Step 1: Generate your access token from Expo Push

Generate an access token from your dashboard. This token authorizes Novu to send notifications on behalf of your project.

1. Log in to the <a href="https://expo.dev/" target="_blank" rel="noopener noreferrer">Expo console</a>.
2. Navigate to the **Credentials** section in the project settings sidebar.
3. Click <a href="https://expo.dev/settings/access-tokens" target="_blank" rel="noopener noreferrer">**Access Token**</a>.
   ![Create Expo token](/images/channels-and-providers/push/expo-push/create-token.png)
4. Click **Create Token**. A menu appears.
5. Give it a descriptive name, and then click **Generate New Token**.
   ![Generate Expo token](/images/channels-and-providers/push/expo-push/generate-token.png)
6. Copy and save the generated access token. You need it in the next step.
   ![Copy Expo token](/images/channels-and-providers/push/expo-push/copy-token.png)

### Step 2: Connect Expo Push to Novu

Next, add the access token to your Expo integration in the Novu dashboard.

1. Log in to the Novu dashboard.
2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect provider**.
4. In the **Push** tab, select **Expo Push**.
5. In the Expo integration form, paste the access token that you copied from Expo into the **Access Token** field.
   ![Expo Integration in Novu](/images/channels-and-providers/push/expo-push/expo-integration.png)
6. Click **Create Integration**.

## Using Expo Push with Novu

Once your integration is configured, you can start sending push notifications by registering your subscribers' device tokens and triggering a workflow.

### Step 1: Add subscriber device token

Before Novu can send a push notification to a subscriber (user), you must associate their device's unique push token with their Novu subscriber profile.

You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.Expo,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "string",
        credentials: {
          deviceTokens: [
            "token1",
            "token2"
          ]
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "expo",
      "deviceTokens": ["token1", "token2"],
      "integrationIdentifier": "string"
    }'
    ```
  </Tab>
</Tabs>

<Callout type="info">Novu automatically removes invalid device tokens from a subscribers' profile and then sends the failure details to the `MESSAGE_FAILED` webhook.</Callout>

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/create-a-workflow) and trigger it. Novu sends the notification to all devices associated with the subscriber.

The example below demonstrates a simple trigger using Novu’s SDK.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // Your payload data
  },
});
```

## Using overrides to customize notifications

Novu provides an overrides field that let you send additional Expo-specific message fields. You can use this to control how messages are displayed or to attach custom payloads.

The overrides field supports all <a href="https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format" target="_blank" rel="noopener noreferrer">Expo Message Request</a> values. Here is an example:

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "subscriber-id-123" },
  payload: {
    orderId: "12345",
  },
  overrides: {
    providers: {
      expo: {
        title: "Order Update",
        body: "Your order #12345 has been shipped!",
        data: {
          deepLink: "myapp://orders/12345",
          orderId: "12345",
        },
        sound: "default",
        priority: "high",
        ttl: 3600,
      },
    },
  },
});
```


# Firebase Cloud Messaging (FCM) (/platform/integrations/push/fcm)

Learn how to use the Firebase Cloud Messaging (FCM) provider to send push notifications using Novu

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

This guide explains the process of configuring and using FCM with Novu, from getting your credentials to sending your first notification.

<Callout> Novu uses FCM version V1</Callout>

## Step 1: Generate your service account key from Firebase

Get your project's service account credentials from the Firebase Console.

1. Log in to the <a href="https://console.firebase.google.com/" target="_blank" rel="noopener noreferrer">Firebase console</a>.
2. Create a new Firebase project or select an existing project.
   ![Select Firebase Project](/images/channels-and-providers/push/select-firebase-project.png)
3. Click the gear icon ⚙️ next to **Project Overview**.
4. Select **Project settings**.
   ![Firebase Project Settings](/images/channels-and-providers/push/firebase-project-settings.png)
5. Click the **Service accounts** tab.
6. Click the **Generate new private key** button. A confirmation menu appears.
   ![Firebase Service Accounts](/images/channels-and-providers/push/firebase-service-accounts.png)
7. Click **Generate key** to download a JSON file containing your credentials.
   ![Firebase generate private key confirmation dialog](/images/channels-and-providers/push/confirmation-menu.png)
8. Open the downloaded JSON file and ensure it contains these fields:
   ```json
   {
     "type": "service_account",
     "project_id": "PROJECT_ID",
     "private_key_id": "PRIVATE_KEY_ID",
     "private_key": "PRIVATE_KEY",
     "client_email": "FIREBASE_ADMIN_SDK_EMAIL",
     "client_id": "CLIENT_ID",
     "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": "CLIENT_X509_CERT_URL"
   }
   ```

## Step 2: Connect FCM to Novu

Add the credentials to your FCM integration in the Novu dashboard.

1. Log in to the Novu dashboard.
2. Navigate to the **Integration Store**.
3. Click **Connect provider**.
4. Click the **Push** tab, then select **Firebase Cloud Messaging (FCM)**.
5. Open the JSON file you downloaded from Firebase in [Step 1](/platform/integrations/push/fcm#step-1-generate-your-service-account-key-from-firebase).
6. Copy the entire content of the JSON file and paste it into the **Service Account** field in the FCM integration modal.
   ![FCM integration](/images/channels-and-providers/push/fcm-integration.png)
7. Click **Create Integration** to save the integration.

## Step 3: Register a subscriber's device token

Before Novu can send a push notification to your subscriber, you must associate their device's unique push token with their Novu subscriber profile.

You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from "@novu/api";
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",});

    async function run() {
      const result = await novu.subscribers.credentials.update({
        providerId: ChatOrPushProviderEnum.Fcm,
        credentials: {
          deviceTokens: [
            "token1",
            "token2",
          ],
        },
      }, "subscriberId");
    }
    run();
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "fcm",
      "credentials": {
        "deviceTokens" : [
          "token1",
          "token2"
        ]
      },
      "integrationIdentifier": "string"
    }'
    ```
  </Tab>
</Tabs>

<Callout type="info">Novu automatically removes invalid device tokens from a subscribers' profile and then sends the failure details to the `MESSAGE_FAILED` webhook.</Callout>

## Step 4: Send a notification

Now you're ready to send a push notification. You can trigger a notification to a subscriber who has a registered device token.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // Your payload data
  },
});
```

## Using multiple FCM integrations

If you have multiple active FCM integrations, then you can specify which integration to associate the tokens with by providing the `integrationIdentifier`.

You can find this identifier in your Novu dashboard on the integration's settings page.

![Integration identifier](/images/channels-and-providers/push/integrationidentifier.png)

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.subscribers.credentials.update(
  {
    providerId: "fcm",
    // Use integrationIdentifier to store device tokens for a specific integration
    integrationIdentifier: "string",
    credentials: {
      deviceTokens: [
        "token1",
        "token2"
      ]
    },
  },
  "subscriberId"
);
```

## Using overrides to customize notifications

Novu lets you customize the behavior of push notifications by using the overrides field when triggering workflows. Overrides give you full control over message content and delivery parameters that aren’t configurable from the Novu workflow editor.

To learn more about how overrides work across all channels, see the [Trigger Overrides](/platform/integrations/trigger-overrides) documentation.

### Override FCM field

Overrides let you send platform-specific data that is not available in the workflow editor. The overrides field supports:

* `apns` overrides
* `android` overrides
* `webpush` overrides
* `fcmOptions` overrides

| Override field | Type / Interface | Link                                                                                                                                                                                         |
| -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| android        | AndroidConfig    | [https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.androidconfig](https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.androidconfig) |
| apns           | ApnsConfig       | [https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.apnsconfig](https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.apnsconfig)       |
| webPush        | WebpushConfig    | [https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.webpushconfig](https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.webpushconfig) |
| fcmOptions     | FcmOptions       | [https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.fcmoptions](https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.fcmoptions)       |

You can use these fields to customize how notifications are sent to Android, iOS via APNS, or web clients.

```typescript
await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    fcm: {
      // For a data-only notification (silent push)
      type: 'data',
      data: {
        custom_key: 'custom_value',
      },
      // Platform-specific overrides
      android: {
        // See FCM AndroidConfig options
      },
      apns: {
        // See FCM ApnsConfig options
      },
      webPush: {
        // See FCM WebpushConfig options
      },
      fcmOptions: {
        // See FCM FcmOptions
      }
    },
  },
});
```

### Override FCM notification content

By default, Novu sends the FCM notification content written in the step editor workflow. However, you can override the notification content by using the `overrides` field.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    providers: {
      fcm: {
        type: "data",

        // URL of an image to be displayed in the notification.
        imageUrl: "https://domain.com/image.png",

        // If type is not set, you can use the "data" override to send notification messages with optional data payload
        data: {
          key: "value",
        },

        // Check FCM Overrides section above for these types
        android: {},
        apns: {},
        webPush: {},
        fcmOptions: {},
      },
    },
  },
});
```

<Callout>Overrides can be applied at runtime to customize or enrich notifications based on user context, device type, or workflow logic.</Callout>

## Sending notifications to FCM topics

<a href="https://firebase.google.com/docs/cloud-messaging/android/topic-messaging" target="_blank" rel="noopener noreferrer">FCM topics</a> are used to send notifications to multiple devices at once. In the `overrides`, you need to specify the [topic](/platform/concepts/topics) you want to send the notification to.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    key: "value",
  },
  overrides: {
    providers: {
      fcm: {
        topic: "topic-123",
      },
    },
  },
});
```

## Web push with relative links

Suppose you're using the Firebase (FCM) provider to send push notifications to web browsers via Novu and want users to be returned to the website after clicking the notification.

In that case, you must use the `link` property with a relative URL.

<Tabs items={['Node.js', 'Curl']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
      },
      payload: {
        key: "value",
      },
      overrides: {
        providers: {
          fcm: {
            webPush: {
              fcmOptions: {
                link: "/foo",
              },
            },
          },
        },
      },
    });
    ```
  </Tab>

  <Tab value="Curl">
    ```bash
    curl --location --request POST 'https://url.to.our.selfhosted.novu' \
        --header 'Authorization: ApiKey KEY' \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "name": "workflow-name",
            "to": {
                "subscriberId": "subscriberId"
            },
            "overrides": {
              "fcm": {
                "webPush": {
                  "fcm_options": {
                    "link": "/foo"
                  }
                }
              }
            }
          }'
    ```
  </Tab>
</Tabs>

## Frequently asked questions

<Accordions type="multiple">
  <Accordion title="FCM cost">As per Firebase <a href="https://firebase.google.com/pricing" target="_blank" rel="noopener noreferrer">pricing</a>, **Cloud Messaging** product is free to use. If other Firebase products are used, then the cost are charged per the product.</Accordion>

  <Accordion title="The registration token is not a valid FCM registration token">
    You might come across an error such as: `Sending message failed due to "The registration token is not a valid FCM registration token"`. This error happens because of an invalid or stale token. The fix for this is:

    1. Remove the old tokens.
    2. Generate a new token.
    3. Save the new token into user subscribers.
  </Accordion>

  <Accordion title="FCM notifications sent successfully with no error but push notification is not received in device">Try to generate a new token after clearing device cache and retry with this fresh token.</Accordion>
  <Accordion title="Sending message failed due to 'Requested entity was not found'">This error occurs when your token is no longer valid. To fix this, generate a new token and use it.</Accordion>
  <Accordion title="Subscriber does not have a configured channel error">This error occurs if the FCM integration is active, but the subscriber is missing from the FCM credentials (deviceTokens). The credentials (deviceTokens) for the subscriber needs to be set.</Accordion>
  <Accordion title="How to send desktop notifications using FCM">Desktop notifications for websites can be sent using FCM webpush.</Accordion>
</Accordions>


# OneSignal (/platform/integrations/push/onesignal)

Learn how to use the OneSignal provider to send push notifications using Novu

This guide walks you through the entire process of configuring and using <a href="https://onesignal.com/" target="_blank" rel="noopener noreferrer">OneSignal</a> with Novu, from getting your credentials to sending your first notification.

OneSignal supports sending messages via both <a href="https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server" target="_blank" rel="noopener noreferrer">Apple Push Notification Service</a> (APNs) and <a href="https://firebase.google.com/docs/cloud-messaging" target="_blank" rel="noopener noreferrer">Firebase Cloud Messaging</a> (FCM).

## Configure Onesignal with Novu

Before you can send push notifications via OneSignal from Novu, you need to connect your OneSignal credentials.

### Step 1: Get your OneSignal credentials

To configure the OneSignal integration, you need an active account that has credentials for APNS, FCM, or both, and have access to two values from OneSignal app's settings:

* App ID
* App API Key

Follow <a href="https://developer.apple.com/help/account/keys/create-a-private-key" target="_blank" rel="noopener noreferrer">this OneSignal guide</a> to see how to access your OneSignal `App ID` and `App API key`.

### Step 2: Connect Onesignal to Novu

Next, add these keys to your OneSignal integration in the Novu dashboard.

1. Log in to the Novu dashboard.
2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect provider**.
4. Click the **Push** tab.
5. Select **OneSignal**.
6. In the OneSignal integration form, paste your **App ID** and **App API Key** into the corresponding fields.
   ![Onesignal Integration in Novu](/images/channels-and-providers/push/onesignal/onesignal-integration.png)
7. Click **Create Integration**.

## Using Onesignal with Novu

Once your integration is configured, you can start sending push notifications by registering your subscribers' `player_id` tokens and triggering a workflow.

### Step 1: Add subscriber device token

When you <a href="https://documentation.onesignal.com/docs/onboarding-with-onesignal#step-1-setup-onesignal-sdk" target="_blank" rel="noopener noreferrer">set up the OneSignal SDK</a> in your application, your users are automatically assigned a unique OneSignal <a href="https://documentation.onesignal.com/docs/users#player-id" target="_blank" rel="noopener noreferrer">`player_id`</a>. This ID is used to target the user for push notifications.

To target a OneSignal user from Novu, you must register their `player_id` as the `deviceToken` for their Novu subscriber profile.

You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.OneSignal,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "string",
        credentials: {
          deviceTokens: [
            "token1",
            "token2",
            "token3"
          ],
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "one-signal",
      "deviceTokens": ["token1", "token2", "token3"],
      "integrationIdentifier": "string"
    }'
    ```
  </Tab>
</Tabs>

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/create-a-workflow) and trigger it. Novu sends the notification to all devices (player IDs) associated with the subscriber.

The example below demonstrates, how to [trigger a workflow](/platform/sdks/server/typescript) using Novu’s SDK.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // Your payload data
  },
});
```

## Using overrides to customize notifications

Novu provides an `overrides` field that lets you send additional OneSignal-specific message fields. You can use this to control how messages are displayed or to attach custom payloads.

The overrides field supports all OneSignal Create Notification parameters. Here is an example:

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    abc: 'def', // If the notification is a data notification, the payload will be sent as the data
  },
  overrides: {
    subtitle: 'This is subtitle value',
    mutableContent: 'Mutable content value',
    // for android notification categories
    channelId: 'category_id',
    // for ios notification categories
    categoryId: 'Category id',
    // same value is used for all sizes and browsers
    icon: 'https://image.com/icon.png',
    // used for both android and ios
    sound: 'sound file url',
  },
});
```

## Using external user ID

By default, Novu uses `player_id` to send notifications, but you can select the `External ID` option in the OneSignal integration settings in Novu. If `External ID` option is selected, then `deviceTokens` stored in subscriber credentials for the OneSignal provider, are used as external user IDs.

By default, Novu uses player IDs to send notifications. If your OneSignal integration uses external user IDs, then you can switch this behavior in the OneSignal integration settings in Novu.

![Select external id option](/images/channels-and-providers/push/onesignal/select-external-id-option.gif)

Once enabled, the `deviceTokens` stored in subscriber credentials are treated as external user IDs instead of player IDs.


# Push Webhook (/platform/integrations/push/push-webhook)

Learn how to use the Push Webhook provider to send  notifications using Novu

This guide walks you through the entire process of configuring and using Push Webhook with Novu.

The Push Webhook provider is different from other push providers because it does not depend on a third-party service. Instead, Novu sends push notifications directly to a webhook URL that you control. This approach is ideal if you want full control over how notifications are processed, routed, or stored in your system.

## Configure Push Webhook with Novu

To configure Push Webhook, you must provide an endpoint URL for Novu to call and a secret HMAC key to verify the request's authenticity.

### Step 1: Get your webhook URL and secret key

Before connecting to Novu, you need two things:

* **Webhook URL**: This is your own API endpoint that will receive the `POST` request from Novu. For quick testing, you can use a service like [webhook.site](https://webhook.site/).
* **Secret HMAC Key:** This is a self-generated secret string. Novu will use it to encrypt the payload using the `HMAC SHA256` algorithm and send the hash in the `x-novu-signature` header. This lets you verify that the request is genuinely from Novu. See [how to generate a HMAC key](/platform/inbox/prepare-for-production#2-generate-hmac-hash-on-the-server-side).

<Callout>Your webhook URL endpoint must be able to accept `POST` requests.</Callout>

### Step 2: Connect Push Webhook to Novu

Next, add these keys to your Push Webhook integration in the Novu dashboard:

1. Log in to the Novu dashboard.
2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect Provider**.
4. In the **Push** tab, select **Push Webhook**.
5. In the integration form, fill in the following fields:

* **Webhook URL:** The endpoint URL that you prepared in Step 1.
* **Secret HMAC Key:** The secret key used to sign webhook calls.
  ![Push Webhook Integration in Novu](/images/channels-and-providers/push/push-webhook/push-webhook-integration.png)

6. Click **Create Integration**.

## Using Push Webhook with Novu

Once configured, you must register a device token for your subscriber and trigger a workflow.

### Step 1: Add subscriber device token

This step is mandatory. Unlike other push providers that generate a unique token, for the Push Webhook, you must provide your own identifier.

Any random string can be used as a device token. This token is included in the webhook payload sent to your endpoint, allowing you to identify which user or device the notification is for.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.PushWebhook,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "push-webhook-MnGLxp8uy",
        credentials: {
          deviceTokens: ["token1", "token2", "token3"],
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab title="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "push-webhook",
      "deviceTokens": ['ANY_RANDOM_STRING'],
      "integrationIdentifier": "push-webhook-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/create-a-workflow) and trigger it. Novu sends the notification payload to the webhook URL that you configured.

The example below demonstrates a simple trigger using Novu’s SDK.

```jsx
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // This payload data will be included
    // in the webhook request
    custom_message: "This is custom message from payload.",
  },  
});
```

## Payload sent by Novu to webhook URL

When you trigger a workflow, Novu sends a `POST` request to your webhook URL with a JSON body similar to the one below.

The payload includes:

* The `title` and `content` from your workflow editor.
* The `target` (the device token you set).
* Your `overrides`.
* The full payload from your trigger.
* The subscriber's profile.

```json
{
  "target": ["subscriber-token-for-push-webhook-provider"],
  "title": "Push Webhook message title",
  "content": "push Webhook content body",
  "overrides": {
    "data": {
      "custom_message": "this is custom message from payload push webhook demo"
    }
  },
  "payload": {
    "custom_message": "this is custom message from payload push webhook demo",
    "__source": "test-workflow",
    "subscriber": {
      // subscriber fields
      "_id": "65c0d71c0959a38e8857b131",
      "_organizationId": "organizationId",
      "_environmentId": "environmentId",
      "firstName": "Pawan",
      "lastName": "Jain",
      "phone": "+123456789",
      "subscriberId": "push-webhook-demo-subscriber-id",
      "email": "pawan+push+web+hook+demo@domain.com",
      "channels": [
        {
          "credentials": {
            "deviceTokens": ["subscriber-token-for-push-webhook-provider"]
          },
          "_integrationId": "integrationId",
          "providerId": "push-webhook"
        }
      ],
      "data": {
        // custom data field of subscriber
        "isDeveloper": "true"
      },
      "deleted": false,
      "createdAt": "2024-02-05T12:39:56.379Z",
      "updatedAt": "2024-02-05T12:54:08.684Z",
      "__v": 0,
      "id": "65c0d71c0959a38e8857b131"
    },
    "step": {
      // digest variables
      "digest": false,
      "events": [],
      "total_count": 0
    }
  }
}
```

## Checking authenticity

If you provided a secret HMAC key during configuration, then Novu will include a `x-novu-signature` header in the request. You can use this header to verify that the request is from Novu and not a malicious third party.

Here is an example of how to validate the hash:

```typescript
import crypto from 'crypto';

// secret key added in step 3
const secretKey = 'YOUR_HMAC_SECRET_KEY';

// function to handle webhook url route request
async function acceptNovuPushWebHookRequest(request, response) {
  const payloadSentByNovu = request.body;
  const hmacHashSentByNovu = request.headers['x-novu-signature'];

  const actualHashValue = crypto
    .createHmac('sha256', secretKey)
    .update(payloadSentByNovu, 'utf-8')
    .digest('hex');

  if (hmacHashSentByNovu === actualHashValue) {
    // handle the notification
    console.log('Request sent by Novu');
  } else {
    throw new Error('Not a valid request');
  }
}
```


# Pusher Beams (/platform/integrations/push/pusher-beams)

Learn how to use the Pusher Beams provider to send push notifications using Novu

<a href="https://pusher.com/beams/" target="_blank" rel="noopener noreferrer">Pusher Beams</a> is a cross-platform push notification API service provided by Pusher.

This guide explains the process of configuring and using Pusher Beams with Novu, from getting your credentials to sending your first notification.

## How to configure Pusher Beams with Novu

Before you can send notifications, you must get your credentials from a Pusher Beams instance and add them to your Novu integration settings.

### Step 1: Get your Pusher Beams credentials

To enable Pusher Beams integration, you need to create a Pusher Beams Instance and use both `Instance ID` and `Secret Key` from the Instance [dashboard](https://dashboard.pusher.com/beams/).

1. Log in to the Pusher Beams dashboard.
2. Click **Create instance**.
3. Enter the instance name, and then click **Create**.
   ![Create instance](/images/channels-and-providers/push/pusher-beams/create-instance.png)
4. In the instance dashboard, click **Keys** from the sidebar, then copy and store your **Instance ID** and **Primary key** you will need them in [Step 2](/platform/integrations/push/pusher-beams#step-2-connect-pusher-beams-to-novu).
   ![Instance credentials](/images/channels-and-providers/push/pusher-beams/instance-credentials.png)

### Step 2: Connect Pusher Beams to Novu

Next, add these credentials to your Pusher Beams integration in the Novu dashboard.

1. Log in to the Novu dashboard.
2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect Provider**.
4. Click the **Push** tab, then select **Pusher Beams**.
5. In the Pusher Beams integration form, paste your **Instance ID** and **Secret Key** into the corresponding fields.
   ![Pusher Beams Integration in Novu](/images/channels-and-providers/push/pusher-beams/pusher-beams-integration.png)
6. Click **Create Integration**.

## Using Pusher Beams with Novu

Once your integration is configured, you can start sending push notifications by registering your subscribers' `userId` and triggering a workflow.

### Step 1: Add subscriber device token

After <a href="https://pusher.com/docs/beams/reference/all-libraries/" target="_blank" rel="noopener noreferrer">setting up the Pusher Beams SDK</a> in your application, you must associate users with their devices using Pusher Beams' <a href="https://pusher.com/docs/beams/guides/publish-to-specific-user/web/" target="_blank" rel="noopener noreferrer">Authenticated Users</a> feature. This assigns them a `userId`.

To target a Pusher Beams user from Novu, you must register this `userId` as the `deviceToken` for their Novu subscriber profile. You can retrieve this value using the <a href="https://pusher.com/docs/beams/reference/web/#getuserid" target="_blank" rel="noopener noreferrer">`getUserId()`</a> method from the Pusher Beams SDK.

You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.PusherBeams,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "pusher-beams-MnGLxp8uy",
        credentials: {
          deviceTokens: ["token1", "token2", "token3"],
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "pusher-beams",
      "deviceTokens": ['userId-from-pusher-beams'],
      "integrationIdentifier": "pusher-beams-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/create-a-workflow) and trigger it. Novu sends the notification to the `userId`'s associated with the subscriber.

The example below demonstrates a simple trigger using Novu’s SDK.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    custom_data: 'custom_data', // the payload will be sent as notification data object. Cannot contain the key "pusher"
  },
});
```


# Pushpad Push Provider (/platform/integrations/push/pushpad)

Learn how to use the Pushpad provider to send web push notifications using Novu

This guide walks you through the entire process of configuring and using <a href="https://pushpad.xyz" target="_blank" rel="noopener noreferrer">Pushpad</a> with Novu, from getting your credentials to sending your first notification.

<a href="https://pushpad.xyz" target="_blank" rel="noopener noreferrer">Pushpad</a> is a web push service that supports sending notifications to all major browsers via FCM, Mozilla autopush, Windows Push Notification Services, and APNS, with just one simple API.

## Configure Pushpad with Novu

Before you can send notifications, you need to connect your Pushpad project to Novu by getting your credentials and adding them to your integration settings.

### Step 1: Get your Pushpad credentials

To configure the Pushpad integration, you need:

* An active Pushpad account
* A Pushpad auth token (found in the [account settings](https://pushpad.xyz/access_tokens))
* Your Pushpad project ID (found in the project settings)

1. Log in to your Pushpad dashboard.
2. Click **New project** to create a project.
   ![New project](/images/channels-and-providers/push/pushpad/new-project.png)
3. Click **Settings** on the project page and record the **Project ID**. You need it to connect to Novu.
   ![Project ID](/images/channels-and-providers/push/pushpad/project-id.png)
4. Navigate to the [access token](https://pushpad.xyz/access_tokens) page.
5. Click **Add access token**.
6. Fill in the required fields to create a new access token, or use your existing token if you already have one.
   ![Add access token](/images/channels-and-providers/push/pushpad/add-token.png)
7. Copy the generated token. You need it to connect to Novu.
   ![Generate access token](/images/channels-and-providers/push/pushpad/access-token.png)

### Step 2: Connect Pushpad to Novu

Add these credentials to your Pushpad integration in the Novu dashboard.

1. Log in to the Novu dashboard.
2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect provider**.
4. Click the **Push** tab.
5. Select **Pushpad**.
6. In the Pushpad integration form, paste your access token and project ID from [Step 1](/platform/integrations/push/pushpad#step-1-get-your-pushpad-credentials) into the corresponding fields.
   ![Pushpad Integration in Novu](/images/channels-and-providers/push/pushpad/pushpad-integration.png)
7. Click **Create Integration**.

## Using Pushpad with Novu

Once your integration is configured, in other to send push notification using the PushPad provider, you must do the following:

### Step 1: Add subscriber device token

After [setting up the Pushpad SDK](https://pushpad.xyz/docs/pushpad_pro_getting_started) on your website, you must [assign a user ID (uid)](https://pushpad.xyz/docs/identifying_users) to your users' push subscriptions.

This `uid` is the identifier Novu uses to target a specific browser. For example, if you use `pushpad('uid', 'user123')`, then `user123` is the ID you must register in Novu.

You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from '@novu/api';
    import { ChatOrPushProviderEnum } from "@novu/api/models/components";

    const novu = new Novu({
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.subscribers.credentials.update(
      {
        providerId: ChatOrPushProviderEnum.PushPad,
        // Use integrationIdentifier to store device tokens for a specific integration
        integrationIdentifier: "pushpad-MnGLxp8uy",
        credentials: {
          deviceTokens: ["token1", "token2", "token3"],
        },
      },
      "subscriberId"
    );
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    -d '{
      "providerId": "pushpad",
      "deviceTokens": ['user123'],
      "integrationIdentifier": "pushpad-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/create-a-workflow) and then trigger it. Novu sends the notification to the `uid`s associated with the subscriber.

The example below demonstrates a simple trigger using Novu’s SDK.

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {},
});
```


# 46elks SMS Provider (/platform/integrations/sms/46elks)

Learn how to use the 46elks provider to send sms notifications using Novu

You can use the [46elks](https://46elks.com/) provider to send SMS messages to your customers using the Novu platform with a single API to create multi-channel experiences.

## Getting Started

To use the 46elks provider in the sms channel, you will need to create a 46elks account and add your `API Username` & `API Password` to the 46elks integration on the Novu platform.

## Creating the 46elks integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-46elks) page on Novu.
* Click the "Add a provider" button.
* Select 46elks service
* Click `Next`
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send SMS, MMS, using 46elks in Novu.


# Africa's Talking (/platform/integrations/sms/africas-talking)

Learn how to use the Africa's Talking provider to send sms notifications using Novu

You can use [Africa's Talking](https://africastalking.com/) provider to send SMS messages to your customers using the Novu platform with a single API to create multi-channel experiences.

## Getting Started

To use Africa's Talking provider in the SMS channel, the first step is to create an Africa's Talking account and add your `API Key`, `username` and `Sender's ID` to Africa's Talking integration on the Novu platform.

## Creating a username

You'll need to create an application to create a username in Africa's Talking. To do so, follow the steps below:

* [Sign up](https://account.africastalking.com/auth/register) or [Log in](https://account.africastalking.com/auth/login) to your Africa's Talking account.
* Select the team you want your app to be in.

<img alt="Select the team you want your app to be in" src="/images/channels-and-providers/sms/africas-talking/team-africa.png" width={2000} height={763} />

* If you're a new user and don't have a team yet, you'll have to do so by clicking on New Team and entering your team name. Click on Save when you're done.

<img alt="If you're a new user and don't have a team yet, you'll have to do so by clicking on New Team and entering your team name. Click on Save when you're done" src="/images/channels-and-providers/sms/africas-talking/new-team.png" width={2000} height={763} />

* On the page that appears, click on the Create App button.
* On the pop-up that appears, enter your application name, username and select a country. Then click Save. The `username` is what you will use on the Novu platform.

<img alt="Enter your application name, username and select a country" src="/images/channels-and-providers/sms/africas-talking/new app-africa-talking.png" width={2000} height={827} />

## Generating an API key

To generate a new API key, you can follow these steps:

<Callout type="info">Ensure you have created an app in your team.</Callout>

* Click on the app you created. <img alt="Click on the app you created" src="/images/channels-and-providers/sms/africas-talking/new-created-app-africa.png" width={2000} height={829} />
* On the page that appears, click on Settings(on the menu on your left). This will display a dropdown. Click on API Key from the dropdown options. <img alt="Click on API Key from the dropdown options" src="/images/channels-and-providers/sms/africas-talking/api-key-africa.png" width={2000} height={804} />
* On the page that appears, enter your password and click Generate. <img alt="Enter your password and click Generate" src="/images/channels-and-providers/sms/africas-talking/image-57.png" width={2000} height={804} />
* Copy the API Key generated and paste it into the Novu platform or record it somewhere safe for later use because you will not see it from the dashboard on subsequent visits.

<Callout type="info">
  Once you've generated your API Key, wait about 3 minutes before testing it.
</Callout>

## Getting your Sender's ID

Sender IDs allow you to brand your messages as you send them to your customers. There are two kinds of sender IDs, **shortcodes** and **alphanumerics**. The difference is that you can send and receive messages with shortcodes but only send messages with an alphanumeric.

To create a Short Code:

* On your app dashboard, click on SMS (on the menu on your left). This will display a dropdown. Click on `Shortcodes` from the dropdown options. This will also display a dropdown from which you can then click on `My Shortcodes` to view your codes. <img alt="Click on `My Shortcodes` to view your codes" src="/images/channels-and-providers/sms/africas-talking/image-58.png" width={2000} height={921} />
* If you have not created one yet, on the `Shortcodes` dropdown option, click on `Request`. On the page that appears, fill in the form and submit. <img alt="Fill in the form and submit to create shortcode" src="/images/channels-and-providers/sms/africas-talking/image-59.png" width={2000} height={969} />

## To create an Alphanumeric:

* On your app dashboard, click on SMS (on the menu on your left). This will display a dropdown. Click on `Alphanumerics` from the dropdown options. This will also display a dropdown from which you can then click on `My Alphanumerics` to view your codes.

<img alt="Click on `My Alphanumerics` to view your codes" src="/images/channels-and-providers/sms/africas-talking/image-60.png" width={2000} height={940} />

* If you have not created one yet, on the `Alphanumerics` dropdown option, click on `Request`. On the page that appears, fill in the form and submit

<img alt="Click on request, fill in the form and submit" src="/images/channels-and-providers/sms/africas-talking/image-61.png" width={2000} height={940} />

* Once you're done, add either your short code or alphanumeric to the `from` field on the Novu platform.

## Creating an Africa's Talking integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-africastalking) page on Novu.
* Click the "Add a provider" button.
* Locate **Africa's Talking** under the SMS section and click on the **Connect** button.
* Enter the `API key`.
* Fill in the `username` field.
* Fill in the `from` field. This is your registered `short code` or `alphanumeric` value.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Connect** button.

Now it is possible to send SMS notifications using Africa's Talking in Novu.


# AWS SNS SMS Provider (/platform/integrations/sms/aws-sns)

Learn how to use the AWS SNS provider to send sms notifications using Novu

You can use the [AWS SNS](https://aws.amazon.com/sns/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To integrate AWS SNS on the Novu platform, you will need to have in AWS, an IAM user who has the `sns:Publish` permission.

## Create User

To create a user, log in to AWS Console and follow these steps:

* Go to the `IAM` service page.
* Create a new user with `sns:Publish` permission, or add `sns:Publish` permission to an existing user.
* Add the `Access Key` credential to the user and copy the `Access key ID` and the `Secret access key`.

For security reasons, it is suggested that you create a new User to use with Novu.

## Create an AWS SNS integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-sns) page on Novu.
* Click the "Add a provider" button.
* Locate **Amazon SNS** and click on the **Connect** button.
* Enter your `Access Key ID`, `Secret Access key`, and `AWS region`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Save** button.
* You should now be able to send SMS notifications using **Amazon SNS** in Novu.


# Azure SMS (/platform/integrations/sms/azure)

Learn how to use the Azure SMS provider to send sms notifications using Novu

You can use the [Azure SMS](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/sms/send?tabs=windows\&pivots=platform-azcli) SMS provider to send SMS messages to the customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use Azure SMS provider in the SMS channel, the first step is to create an Azure account and grab the communication services connection string from your account dashboard.

## Creating a Azure SMS integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-azure) page on Novu.
* Click the "Add a provider" button.
* Locate **Azure Sms** under the SMS section and click on the **Next** button.
* Select Your Environment add condition (Optional).
* Click on the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `Connection string`.
* Enter the `From` value.
* Click on the **Update** button.

Now it is possible to send SMS notifications using **Azure Sms** in Novu.


# BulkSMS SMS Provider (/platform/integrations/sms/bulk-sms)

Learn how to use the BulkSMS provider to send sms notifications using Novu

You can use the [BurstSMS](https://bulksms.com/) provider to send SMS messages to the customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use BulkSMS provider in the SMS channel, the first step is to create a BulkSMS account and create an [API token](https://www.bulksms.com/account/#!/advanced-settings/api-tokens).

## Creating a BulkSMS integration with Novu

* Visit the [Integrations](https://dashboard.novu.co.co/integrations?utm_campaign=docs-sms-bulksms) page on Novu.
* Click the "Add a provider" button.
* Locate **BulkSMS** under the SMS section and click on the **Next** button.
* Select Your Environment add condition (Optional).
* Click on the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `API Token`.
* Click on the **Update** button.

Now it is possible to send SMS notifications using **BulkSMS** in Novu.


# Clickatell (/platform/integrations/sms/clickatell)

Learn how to use the Clickatell provider to send sms notifications using Novu

You can use the [Clickatell](https://www.clickatell.com/) provider to send SMS messages to your customers using the Novu Platform. Let's see how to do it:

## Setting up Clickatell

<Steps>
  <Step title="Create a Clickatell Account">
    1. [Sign up](https://www.clickatell.com/sign-up/) or [Login](https://app.clickatell.com/signin) to your Clickatell account
    2. Click on the `My Workspace`, and then click `SMS` in Channels Section

    <img alt="Click on the My Workspace, and then click SMS in Channels Section" src="/images/channels-and-providers/sms/clickatell/step_01.png" width={1920} height={1080} />
  </Step>

  <Step title="Set up SMS API">
    1. Click on the `New SMS Setup`

    <img alt="Click on the New SMS Setup" src="/images/channels-and-providers/sms/clickatell/step_02.png" width={1920} height={1080} />

    2. Select `API` then `Messaging Type` and click Next

    <img alt="Select API then Messaging Type and click Next" src="/images/channels-and-providers/sms/clickatell/step_03.png" width={1920} height={1080} />

    3. Select `Basic HTTP API` then `create a new HTTP API` and click Next

    <img alt="Select Basic HTTP API then create a new HTTP API and click Next" src="/images/channels-and-providers/sms/clickatell/step_04.png" width={1920} height={1080} />
  </Step>

  <Step title="Configure API Settings">
    1. Fill in all the required details and click Next

    <img alt="Fill in all details and click Next" src="/images/channels-and-providers/sms/clickatell/step_05.png" width={1920} height={1080} />

    2. Copy the API key and click complete

    <img alt="Copy the API key and click complete" src="/images/channels-and-providers/sms/clickatell/step_06.png" width={1920} height={1080} />
  </Step>

  <Step title="Connect Clickatell to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-clickatell) page on Novu
    2. Click the "Add a provider" button
    3. Locate **Clickatell** under the SMS section and click on the **Connect** button
    4. Enter your Clickatell API Key
    5. Click on the `Disabled` button and mark it as `Active`
    6. Click on the **Connect** button
  </Step>
</Steps>

Now it is possible to send SMS notifications using **Clickatell** in Novu.


# Clicksend (/platform/integrations/sms/clicksend)

Learn how to use the Clicsend provider to send sms notifications using Novu

You can use the [Clicksend](https://www.clicksend.com/in/) provider to send SMS messages to your customers using the Novu Platform. Let's see how to do it:

## Getting Started

To use the [Clicksend](https://www.clicksend.com/in/) provider in the SMS channel, the first step is to [create a Clicksend account](https://dashboard.clicksend.com/signup/step1) and add your API key to the Clicksend integration on the [Novu web dashboard](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-clicksend).

## Retrieving your API Key

* **Generate an API Key**: After logging into your ClickSend account, navigate to the API Keys section. This is usually located in your account settings or developer dashboard.
* **Create a New API Key**: It's recommended to create a new API key specifically for your integration with Novu. Click on the option to create a new API key, and it will be generated for you.
* **Copy the API Key**: Once your API key is created, make sure to copy it to your clipboard. You will need this key to connect ClickSend with Novu.

## Create a Clicksend integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-clicksend) page on Novu.
* Click on Add a Provider.
* Select Clicksend service.
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Enter your Clicksend Username.
* Enter your Clicksend API Key.
* Fill in the `From` field.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.

Now it is possible to send SMS notifications using **Clicksend** in Novu.


# Firetext SMS Provider (/platform/integrations/sms/firetext)

Learn how to use the firetext provider to send sms notifications using Novu

You can use the [firetext](https://www.firetext.co.uk) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Setting up Firetext

<Callout type="info">
  Firetext is only available in the UK region. Other regions may require additional verification.
</Callout>

<Steps>
  <Step title="Get your API Key">
    1. [Sign up](https://app.firetext.co.uk/signup) or [Login](https://app.firetext.co.uk/) to your firetext account
    2. Click on the `Settings` icon in the top right corner of the screen

    <img alt="Click on the Settings icon in the top right corner of the screen" src="/images/channels-and-providers/sms/firetext/step_01.png" />

    3. Click on the `API` in `My Settings` Section

    <img alt="Click on the API in My Settings Section" src="/images/channels-and-providers/sms/firetext/step_02.png" />

    4. On the API Keys page, copy the `API key`

    <img alt="On the API Keys page, copy the API key" src="/images/channels-and-providers/sms/firetext/step_03.png" />
  </Step>

  <Step title="Connect Firetext to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-firetxt) page on Novu
    2. Click the "Add a provider" button
    3. Locate **firetext** under the SMS section and click on the **Connect** button
    4. Enter your:
       * Firetext API Key
       * From field (Sender ID)
    5. Click on the `Disabled` button and mark it as `Active`
    6. Click on the **Connect** button
  </Step>
</Steps>

Now it is possible to send SMS notifications using **firetext** in Novu.


# Gupshup SMS Provider (/platform/integrations/sms/gupshup)

Learn how to use the Gupshup SMS provider to send SMS notifications using Novu

You can use the [Gupshup](https://www.gupshup.io/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Gupshup provider in the SMS channel, the first step is to create a Gupshup account and add the Account User Id and Password to the Gupshup integration on the Novu platform.

## What is User id and Password?

* `User Id` : The account number provided by the Enterprise SMS GupShup.
* `Password` : Password is provided by Gupshup for authentication of user id. The password must be the same as used to log on to the Enterprise SMS GupShup website.

## Creating a gupshup integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-gupshup) page on Novu.
* Click the **Connect** button on the top right corner of the page.
* Select SMS and locate **Gupshup** and click on the **Connect** button.
* Choose environment from top right corner in which you want to create the integration.
* Enter the `User id`.
* Enter the `Password`.
* Make sure **Active Integration** toggle is on to use this integration.
* If you want to use this integration, then mark this integration as `primary` using **Primary Integration** toggle.
* Click on the **Create Integration** button.

Now it is possible to send SMS notifications using Gupshup in Novu.

## Using Gupshup templateId

Novu has its own SMS editor for writing SMS template. To use premade Gupshup templates, providers overrides can be used.

<Callout type="info">
  Sending `customData` field in overrides to send Gupshup template will work
  only in following cases:

  * if workflow is triggered to only one subscriber
  * if workflow is triggered to multiple subscribers or topic but Gupshup
    template does not have any dynamic variables related to subscriber attributes
    like `firstName`, `lastName`, `phone`, etc as same overrides will be applied
    to all subscribers.
</Callout>

<Tabs items={['Node.Js', 'cURL']}>
  <Tab value="Node.Js">
    ```typescript
    import { Novu } from '@novu/api';

    const novu = new Novu({ secretKey: "NOVU_SECRET_KEY" });

    await novu.trigger({
      workflowId: "WORKFLOW_ID",
      to: "SUBSCRIBER_ID",
      payload: {
        key: "value",
      },
      overrides: {
        providers: {
          gupshup: {
            principalEntityId: "principal-entity-id",
            dltTemplateId: "dlt-template-id",
          },
        },
      },
    });
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl --location 'https://api.novu.co/v1/events/trigger' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
    --data '{
        "name": "workflowIdentifier",
        "to":  ["subscriberId"],
        "payload": {},
        "overrides": {
            "providers": {
                "gupshup": {
                  "principalEntityId": "principal-entity-id",
                  "dltTemplateId": "dlt-template-id"
                }
            }
        }
    }'
    ```
  </Tab>
</Tabs>


# Infobip - SMS (/platform/integrations/sms/infobip)

Learn how to use the Infobip provider to send sms notifications using Novu

You can use the [Infobip](https://www.infobip.com/developers/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Setting up Infobip

<Steps>
  <Step title="Get your API Key">
    1. [Sign up](https://www.infobip.com/signup) or [Log in](https://portal.infobip.com/login/) to your Infobip account
    2. On the [Homepage](https://portal.infobip.com/homepage/), you'll see your API key

    <img alt="See your API key on your homepage" src="/images/channels-and-providers/sms/infobip/image-63.png" />

    Alternatively, you can find your API key in the Developer Tools:

    1. Click on Developer Tools in the left sidebar
    2. Select API Keys from the dropdown menu

    <img alt="Find your API key from the developer tools" src="/images/channels-and-providers/sms/infobip/image-64.png" />

    3. Click on Generate API Key to create a new key

    <img alt="Generate your API key" src="/images/channels-and-providers/sms/infobip/image-65.png" />
  </Step>

  <Step title="Get your Base URL">
    Log in to your account and check your Homepage. You should see your base URL in this format: `xxxxx.api.infobip.com`.

    <img alt="Your base URL is on the homepage" src="/images/channels-and-providers/sms/infobip/image-66.png" />
  </Step>

  <Step title="Connect Infobip to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-infobip) page on Novu
    2. Click the "Add a provider" button
    3. Locate **Infobip** under the SMS section and click on the **Connect** button
    4. Enter your:
       * Infobip API Key
       * Base URL
    5. Click on the `Disabled` button and mark it as `Active`
    6. Click on the **Connect** button
  </Step>
</Steps>

Now you can send SMS notifications using Infobip in Novu.


# Kannel SMS Provider (/platform/integrations/sms/kannel)

Learn how to use the Kannel sms provider to send sms notifications using Novu

Before integrating Kannel with Novu, you should have Kannel set up and configured as an SMS gateway on your server. Let’s look at how you can do that:

## Setting up Kannel

1. First, you need to install Kannel on your server. You can download it from the [official-website](https://www.kannel.org/download.shtml) or use a package manager specific to your operating system (e.g., apt- get for Ubuntu, yum for CentOS, etc.).

2. Kannel's configuration is done through a file called kannel.conf. You need to edit this file to specify your SMS provider settings. Here's a basic configuration example:

   ```bash
   group = smsc
   smsc = smpp
   smsc-id = YourSMSCID
   host = SMSC_Hostname_or_IP
   port = SMSC_Port
   system-type = SMSC_System_Type
   smsc-username = YourUsername
   smsc-password = YourPassword
   max-pending-submits = 10
   allow-ip = "127.0.0.1"
   ```

   Replace the placeholders (e.g., **YourSMSCID**, **SMSC\_Hostname\_or\_IP**, **SMSC\_Port**, **SMSC\_System\_Type**, **YourUsername**, and **YourPassword**) with the actual values provided by your SMS provider.

3. You can define services that will handle incoming and outgoing SMS messages. These services specify how Kannel should process SMS requests. Here's an example of an SMS service configuration:

   ```bash
   group = sendsms-user
   username = YourUsername
   password = YourPassword
   concatenation = true
   max-messages = 3
   ```

   Adjust the settings to your needs.

4. Start Kannel with the following command:

   ```bash
   bearerbox /path/to/kannel.conf
   ```

   Make sure to replace /path/to/kannel.conf with the actual path to your Kannel configuration file.

## Creating a Kannel integration with Novu

After setting up your Kannel, follow these steps to integrate with novu:

* Visit the [Integrations Store](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-kannel) on Novu.

* Click the "Add a provider" button.

* Select Kannel service.

* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.

* Once the integration is active, you'll need to configure it. This configuration usually involves providing the necessary details for Novu to connect to your Kannel SMS gateway. These details typically include:

  * **Kannel Gateway URL or IP Address**: If your Kannel SMS gateway is hosted on your server, you should use the server's IP address or hostname.
  * **Port**: The port number through which Novu should communicate with Kannel (usually 13013, or a custom port you've configured in Kannel).
  * **Username and Password**: If you've set up authentication for your Kannel SMS gateway, provide the username and password required for authentication:

  ```bash
  group = smsc
  smsc = smpp
  smsc-id = YourSMSCID
  host = SMSC_Hostname_or_IP
  port = SMSC_Port
  smsc-username = YourUsername
  smsc-password = YourPassword
  max-pending-submits = 10
  allow-ip = "127.0.0.1"
  ```

  In this example, **YourUsername** and **YourPassword** are the credentials you'd use for authentication.

* Fill in the `From` field.

* Click on the `Update` button.

* You should now be able to send notifications using Kannel in Novu.


# Kudosity SMS Provider (/platform/integrations/sms/kudosity)

Learn how to use the Kudosity (formerly BurstSMS) provider to send sms notifications using Novu

You can use the [Kudosity (formerly BurstSMS)](https://kudosity.com/) provider to send SMS messages to the customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use Kudosity provider in the SMS channel, the first step is to create an Kudosity account and add the personal Kudosity API key and your Kudosity API Secret to the Kudosity integration on the Novu platform.

## Find the API and Secret key

To find the Kudosity API and Secret key, log into the personal Kudosity account and navigate to the API Keys section tab present at the end of the Navbar. It is suggested to create a new API and Secret key for use with Novu. Copy the newly created API and Secret key.

## Creating a Kudosity integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-burstsms) page on Novu.
* Click the "Add a provider" button.
* Locate **Kudosity (formerly BurstSMS)** under the SMS section and click on the **Next** button.
* Select Your Environment add condition (Optional)
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `API key` and `API Secret`.
* Click on the **Upload** button.
* Now it is possible to send SMS notifications using **Kudosity** in Novu.


# MessageBird (/platform/integrations/sms/messagebird)

Learn how to use the messagebird provider to send sms notifications using Novu

You can use the [MessageBird](https://www.messagebird.com) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the MessageBird provider in the SMS channel, the first step is to create a [MessageBird account](https://www.messagebird.com/en/sign-up) and then generate an `Access Key` within the developers' section section of your MessageBird account. This access key is essential for authenticating your requests to the MessageBird API.

## Creating a MessageBird integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-messagebird) page on Novu.
* Click the "Add a provider" button.
* Locate **MessageBird** under the SMS section. Click it and the **Next** button.
* Select Your Environment add condition (Optional).
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `Access Key` value.
* Enter the `From` value.
* Click on the **Update** button.

Now it is possible to send SMS notifications using **MessageBird** in Novu.


# Nexmo SMS Provider (/platform/integrations/sms/nexmo)

Learn how to use the Nexmo provider to send sms notifications using Novu

You can use the [Nexmo By Vonage](https://www.vonage.com/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Nexmo provider in the SMS channel, the first step is to create a Nexmo account and add the API key and API Secret to the Nexmo integration on the Novu platform.

## Finding the API key and secret

First, [sign up for a Vonage account](https://ui.idp.vonage.com/ui/auth/login) if you don't already have one, and make a note of your API key and secret on the [dashboard getting started page](https://dashboard.nexmo.com/getting-started-guide).

## Create a Nexmo integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-nexmo) page on Novu.
* Click the "Add a provider" button.
* Locate **Nexmo** under the SMS section and click on the **Connect** button.
* Enter the `API key` and `API Secret`.
* Enter a valid `From` email address.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Connect** button.
* Now it is possible to send SMS notifications using **Nexmo** in Novu.


# Plivo SMS Provider (/platform/integrations/sms/plivo)

Learn how to use the Plivo provider to send sms notifications using Novu

You can use the [Plivo](https://www.plivo.com/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Plivo provider in the SMS channel, the first step is to create a Plivo account and add the Account SID and Auth token to the Plivo integration on the Novu platform.

## Finding the Account SID and Auth token

[Sign up](https://console.plivo.com/accounts/register/) or [Login](https://console.plivo.com/accounts/login/) to your Plivo account, and make a note of your Account SID and Auth token on the [Plivo console page](https://console.plivo.com/dashboard/).

## Creating a Plivo integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-plivo) page on Novu.
* Click the "Add a provider" button.
* Locate **Plivo** under the SMS section and click on the **Connect** button.
* Enter the `Account SID`.
* Enter the `Auth token`.
* Fill in the `From` field.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Connect** button.

Now it is possible to send SMS notifications using **Plivo** in Novu.


# Sendchamp (/platform/integrations/sms/sendchamp)

Learn how to use the Sendchamp provider to send sms notifications using Novu

You can use the [Sendchamp](https://www.sendchamp.com/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Setting up Sendchamp

<Steps>
  <Step title="Get your API Key">
    1. [Sign up](https://my.sendchamp.com/signup) or [Login](https://my.sendchamp.com/login) to your Sendchamp account
    2. Click on the Avatar icon in the top right corner of the screen
    3. Select `API & Integrations` from the drop-down menu

    <img alt="Click on the Avatar icon in the top right corner of the screen, and then click API & Integrations" src="/images/channels-and-providers/sms/sendchamp/image-67.png" />

    Alternatively, you can access the API key from the Accounts menu:

    1. Scroll to the bottom of the sidebar and click on `Accounts`
    2. Click on `API keys & Webhooks` from the dropdown

    <img alt="Click on the API keys and webhooks to view your API key" src="/images/channels-and-providers/sms/sendchamp/image-68.png" />

    3. On the API Keys page, copy the Public access key

    <img alt="Copy your public access key" src="/images/channels-and-providers/sms/sendchamp/image-69.png" />
  </Step>

  <Step title="Set up your Sender ID">
    The Sender ID represents the sender of the message to your customers.

    To view your Sender IDs:

    1. On the sidebar menu, click on `SMS`
    2. Select `Sender ID` from the dropdown options
    3. You'll find a list of your Sender IDs

    <img alt="Click sms and select sender ID" src="/images/channels-and-providers/sms/sendchamp/image-70.png" />

    To create a new Sender ID:

    1. Click on the `Create Sender ID` button
    2. Fill in the form
    3. Click on `Add Sender ID` button

    <img alt="Click on the add sender ID button" src="/images/channels-and-providers/sms/sendchamp/image-71.png" />

    <Callout type="info">
      Wait for your Sender ID to be approved before using it as the from field on the Novu platform.
    </Callout>
  </Step>

  <Step title="Connect Sendchamp to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-sendchamp) page on Novu
    2. Click the "Add a provider" button
    3. Locate **Sendchamp** under the SMS section and click on the **Connect** button
    4. Enter your Sendchamp API Key
    5. Fill in the `From` field with your approved Sender ID
    6. Click on the `Disabled` button and mark it as `Active`
    7. Click on the **Connect** button
  </Step>
</Steps>

Now it is possible to send SMS notifications using **Sendchamp** in Novu.


# SimpleTexting (/platform/integrations/sms/simpletexting)

Learn how to use the SimpleTexting provider to send sms notifications using Novu

You can use the [SimpleTexting](https://simpletexting.com/) SMS provider to send SMS messages to the customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use SimpleTexting provider in the SMS channel, the first step is to create a SimpleTexting account and grab your `API KEY` in your settings.

## Creating a SimpleTexting integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-simpletexting) page on Novu.
* Click the "Add a provider" button.
* Locate **SimpleTexting** under the SMS section and click on the **Next** button.
* Select Your Environment add condition (Optional).
* Click on the `Create` button.
* Click on the `Disabled` button and mark it as `Active`.
* Enter the `API Key`.
* Enter the `From` value.
* Click on the **Update** button.

Now it is possible to send SMS notifications using **SimpleTexting** in Novu.


# SMS Central (/platform/integrations/sms/sms-central)

Learn how to use the SMS Central provider to send sms notifications using Novu

You can use the [SMS Central](https://www.smscentral.com.au/) provider to send SMS messages to your customers using the Novu platform with a single API to create multi-channel experiences.

## Getting Started

To use the SMS Central provider in the sms channel, you will need to create a SMS Central account and add your SMS Central `Username` & `Password` to the SMS Central integration on the Novu platform.

## Creating the SMS Central integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-smscentral) page on Novu.
* Click the "Add a provider" button.
* Select SMS Central service
* Click `Next`
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Add `Username` & `Password`
* Fill up the `From` section with the number you wish to send sms from.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Update** button.
* You should now be able to send notifications using SMS Central in Novu.


# SMS77 SMS Provider (/platform/integrations/sms/sms77)

Learn how to use the SMS77 provider to send sms notifications using Novu

It is possible to use the [SMS77](https://www.sms77.io/en) provider to send SMS messages to the customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the SMS77 provider in the SMS channel, the first step is to create an SMS77 account and add the personal API key to the SMS77 integration on the Novu platform.

### Find the API key

To find the SMS77 API key, log into the personal SMS77 account and navigate to the API Keys page by clicking on the 'Developer' tab present at the end of the sidebar. It is suggested to create a new API key for use with Novu. Copy the newly created API key.

### Creating an SMS77 integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-sms77) page on Novu.
* Click the "Add a provider" button.
* Locate **SMS77** under the SMS section and click on the **Connect** button.
* Enter the `API key`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the **Save** button.
* Now it is possible to send SMS notifications using **SMS77** in Novu.


# AWS SNS SMS Provider (/platform/integrations/sms/sns)

Learn how to use the SNS provider to send sms notifications using Novu

You can use the [SNS](https://aws.amazon.com/sns/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

Before you can use SNS as your SMS provider in the Novu platform, you'll need to set up an Amazon Web Services (AWS) account and configure the necessary settings. Here are the steps to get started:

* **Create an AWS Account**: If you don't already have an AWS account, you'll need to create one. You can sign up for an AWS account on the [AWS website](https://aws.amazon.com/).
* **Set Up Amazon SNS**: After you've created your AWS account, navigate to the AWS Management Console. In the Services menu, locate and click on "Simple Notification Service (SNS)." Follow the prompts to set up SNS for your account.
* **Configure SMS Preferences**: In your SNS dashboard, configure your SMS preferences. This includes setting up your sender ID and opting in for SMS messaging.
* **Create Access Keys**: To access SNS programmatically, you'll need to create AWS Access Keys. These keys are used to authenticate your integration with the Novu platform. Go to the [AWS Identity and Access Management console](https://signin.aws.amazon.com/) to create access keys.

## Create an SNS integration with Novu

* Visit the [Integrations](https://dashboard.novu.co/integrations?utm_campaign=docs-sms-sns) page on Novu.
* Click the "Add a provider" button.
* Choose your preferred deployment environment: `Development` or `Production`. Then Click the `Create` button.
* Enter your `Access Key ID`, `Secret Access key`, and `AWS region`.
* Click on the `Disabled` button and mark it as `Active`.
* Click on the `Update` button.
* You should now be able to send SMS notifications using **SNS** in Novu.


# Telnyx SMS Provider (/platform/integrations/sms/telnyx)

Learn how to use the Telnyx provider to send sms notifications using Novu

You can use the [Telnyx](https://telnyx.com/) provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Setting up Telnyx

<Steps>
  <Step title="Get your API Key">
    1. Log into your Telnyx account
    2. Navigate to Account Setting
    3. Go to [Keys & Credentials](https://portal.telnyx.com/#/app/api-keys)
    4. Copy your existing API key or create a new one by clicking "Create API Key"

    <Callout type="info">
      Make sure the API key's status is showing as active before using it.
    </Callout>
  </Step>

  <Step title="Get your Message Profile ID">
    1. Navigate to [Messaging](https://portal.telnyx.com/#/app/messaging) to find the profiles 2.
       Create a Telnyx Messaging Profile if you haven't already ([learn
       more](https://developers.telnyx.com/docs/v2/messaging/quickstarts/portal-setup)) 3. Go to the
       active Messaging Profile 4. Copy the profile ID
  </Step>

  <Step title="Prepare your From Address">
    <Callout type="info">
      A valid from address must be one of: - A valid phone number in +E.164 format - A short code - An
      alphanumeric sender ID that: - Is 1-11 characters long - Contains only ASCII letters, numbers,
      and spaces - Has at least one letter
    </Callout>
  </Step>

  <Step title="Connect Telnyx to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations) page on Novu
    2. Click the "Add a provider" button
    3. Locate Telnyx and click on the **Connect** button
    4. Enter your:
       * Telnyx API Key
       * Message profile ID
       * Valid From address
    5. Click on the `Disabled` button and mark it as `Active`
    6. Click on the **Save** button
  </Step>
</Steps>

Now you can send notifications using Telnyx in Novu.


# Termii SMS Provider (/platform/integrations/sms/termii)

Learn how to use the Termii provider to send sms notifications using Novu

You can use the [Termii](https://termii.com/) provider to send SMS messages to your customers using the Novu Platform with a single API to create multi-channel experiences.

## Getting Started

To use the Termii provider in the SMS channel, the first step is to create a Termii account and add your API key and Sender ID to the Termii integration on the Novu platform.

## Setting up Termii

<Steps>
  <Step title="Get your API Key">
    1. [Sign up](https://accounts.termii.com/#/register) or [Login](https://accounts.termii.com/#/login) to your Termii account
    2. Navigate to your [dashboard](https://accounts.termii.com/#/)
    3. Scroll to the bottom of the page to find your API key

    <img alt="Go to the bottom of your dashboard to find your API key" src="/images/channels-and-providers/sms/termii/image-72.png" />

    Alternatively, you can find the API key on the Settings page:

    1. Scroll to the bottom of the sidebar (on the left) and click on settings
    2. Click on `API Token` from the dropdown to view your API key

    <img alt="Select API Token from the dropdown to see your API key" src="/images/channels-and-providers/sms/termii/image-73.png" />
  </Step>

  <Step title="Set up your Sender ID">
    Sender IDs allow you to brand your messages as you send them to your customers.

    To view your Sender IDs:

    1. On the sidebar menu, click on `Rental`
    2. Select `SMS Sender IDs` from the dropdown options
    3. You'll find a list of your Sender IDs on the page

    <img alt="Go to Rental on the sidebar to find your sender ID" src="/images/channels-and-providers/sms/termii/image-74.png" />

    To create a new Sender ID:

    1. Click on the `Make a new request` button
    2. Fill in the form
    3. Click on `Save`

    <img alt="Fill in the make a new request form to create a sender ID" src="/images/channels-and-providers/sms/termii/image-75.png" />
  </Step>

  <Step title="Connect Termii to Novu">
    1. Visit the [Integrations](https://dashboard.novu.co/integrations) page on Novu
    2. Click the "Add a provider" button
    3. Locate **Termii** under the SMS section and click on the **Connect** button
    4. Enter your Termii API Key
    5. Fill in the `From` field with your Sender ID
    6. Click on the Disabled button and mark it as Active
    7. Click on the **Connect** button
  </Step>
</Steps>

Now it is possible to send SMS notifications using **Termii** in Novu.


# Twilio SMS Provider (/platform/integrations/sms/twilio)

Learn how to use the Twilio provider to send sms notifications using Novu

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

You can utilize the [Twilio](https://www.twilio.com/) API to communicate with your customers using SMS messaging. Let's look at how you can do that:

## Setting up Twilio

<Steps>
  <Step title="Create a Twilio Account">
    1. Go to [Twilio](https://www.twilio.com/) and create an account, starting with their free trial.
    2. You'll be asked to verify your email and your phone number. Get them verified.
  </Step>

  <Step title="Get a Twilio Phone Number">
    1. Once verified, you'll get an option to 'get a Twilio phone number' from your Twilio console.
    2. Click on it to get your Twilio phone number.

    <Callout type="info">
      When first using Twilio there should be an option to get a Twilio phone number in the main
      console. Otherwise, you may have to
      [Buy](https://console.twilio.com/us1/develop/phone-numbers/manage/search?frameUrl=%2Fconsole%2Fphone-numbers%2Fsearch%3Fx-target-region%3Dus1\&currentFrameUrl=%2Fconsole%2Fphone-numbers%2Fsearch%3FisoCountry%3DUS%26searchTerm%3D%26searchFilter%3Dleft%26searchType%3Dnumber%26x-target-region%3Dus1%26__override_layout__%3Dembed%26bifrost%3Dtrue)
      a number to begin using it. For first-time users, utilize the free number provided.
    </Callout>

    For more detailed instructions, follow one of their many [Tutorials](https://www.twilio.com/docs/usage/requests-to-twilio) within their docs.
  </Step>

  <Step title="Understand the Key Components">
    Irrespective of the language you use, the process requires:

    1. Account SID and Auth token loaded into the code using secure environment variables
    2. A Twilio client object that takes the SID and Token as variables
    3. A message object containing:

       * Your Twilio phone number
       * The recipient's phone number
       * The SMS message body
  </Step>
</Steps>

## Creating a Twilio integration with Novu

<Steps>
  <Step title="Connect Twilio to Novu">
    1. Visit the [Integrations Store](https://dashboard.novu.co/integrations) on Novu
    2. Click the "Add a provider" button
    3. Locate **Twilio** and click on the `Disabled` button and mark it as `Active`
    4. Click on the **Connect** button
  </Step>

  <Step title="Configure Twilio Credentials">
    1. Go to your [Console](https://console.twilio.com/) on Twilio and access the Account Info section
    2. Enter your:
       * `Account SID`
       * `Auth Token`
       * `Twilio Phone Number`
    3. Click on the **Save** button
  </Step>
</Steps>

## Sending WhatsApp message

To send WhatsApp messages with Twilio integration, prefix the phone number of the subscriber with `whatsapp:` as shown below:

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```ts
    import { Novu } from "@novu/api";

    const novu = new Novu({ 
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
        phone: "whatsapp:+14155238886",
      },
      payload: {},
    });
    ```
  </Tab>
</Tabs>

### Sending WhatsApp template message

To send WhatsApp template messages with Twilio integration, you can use the `template` field in the `overrides` object.

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```typescript
    import { Novu } from "@novu/api";

    const novu = new Novu({ 
      secretKey: "<NOVU_SECRET_KEY>",
      // Required if using EU region
      // serverURL: "https://eu.api.novu.co",
    });

    await novu.trigger({
      workflowId: "workflowId",
      to: {
        subscriberId: "subscriberId",
        phone: "whatsapp:+14155238886",
      },
      payload: {},
      overrides: {
        providers: {
          twilio: {
            "_passthrough": {
              "body": {
                // example contentSid
                "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                // example contentVariables
                "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
              }
            }
          }
        }
      }
    });
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Read more about [sending a Message with the Twilio API for
  WhatsApp](https://www.twilio.com/docs/whatsapp/tutorial).
</Callout>


# NovuProvider (/platform/sdks/react/hooks/novu-provider)

Learn how to use the NovuProvider component to set up the Novu context in your React application

The `NovuProvider` is the top-level component that provides the [Novu instance](/platform/inbox/headless-mode) to the rest of the hooks through the context.
Usually, it's placed somewhere in the root of your application, which makes the hooks accessible throughout the application.

## Props

<TypeTable
  type={{
  subscriberId: {
    type: "string",
    description: "The unique identifier of the subscriber",
    typeDescription: "Required",
  },
  applicationIdentifier: {
    type: "string",
    description: "Your application identifier from Novu",
    typeDescription: "Required",
  },
  subscriberHash: {
    type: "string",
    description: "HMAC encryption hash for the subscriber",
  },
  context: {
    type: "object",
    description: "Defines contextual attributes (for example, tenant, app, team) for filtering and personalizing notifications.",
  },
  contextHash: {
    type: "string", 
    description: "The HMAC-SHA256 hash of the context object. Required if context is provided and HMAC is enabled." 
  },
  apiUrl: {
    type: "string",
    description: "Custom backend URL for self-hosted instances",
  },
  socketUrl: {
    type: "string",
    description: "Custom socket URL for self-hosted instances",
  },
  children: {
    type: "ReactNode",
    description:
      "The child components that will have access to the Novu context",
    typeDescription: "Required",
  },
}}
/>

## Example Usage

<Tabs items={['US', 'EU', 'Using Context', 'HMAC Encryption']}>
  <Tab value="US">
    ```tsx
    import { NovuProvider } from '@novu/react';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab value="EU">
    ```tsx
    import { NovuProvider } from '@novu/react';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
          apiUrl="https://eu.api.novu.co"
          socketUrl="wss://eu.socket.novu.co"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab value="Using Context">
    <Callout type="info"> Learn how to use Context for filtering and personalization in the [Inbox withContext](/platform/inbox/configuration/inbox-with-context) guide.</Callout>

    ```tsx
    import { NovuProvider, useNovu } from '@novu/react';

    function App() {
      return (
      <NovuProvider
        applicationIdentifier="APPLICATION_IDENTIFIER"
        subscriber="SUBSCRIBER_ID"
        context={{
          tenant: { id: "org-123" }
        }}
      >
        <App />
      </NovuProvider>
      );
    }

    // In child components
    const MyComponent = () => {
      const novu = useNovu();
      console.log(novu.context);
      // Logs: { tenant: { id: "org-123" } }
    };
    ```
  </Tab>

  <Tab value="HMAC Encryption">
    <Callout type="info">
      Read more about [HMAC Encryption](/platform/inbox/prepare-for-production#secure-your-inbox-with-hmac-encryption).
    </Callout>

    ```tsx
    import { NovuProvider } from '@novu/react';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriberHash="SUBSCRIBER_HASH_HMAC_ENCRYPTION"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>
</Tabs>


# React hooks for subscription management (/platform/sdks/react/hooks/subscription)

Learn how to use the useSubscriptions, useCreateSubscription, and other hooks to manage subscriptions in Novu.

import { TypeTable } from 'fumadocs-ui/components/type-table';

The `@novu/react` package provides a set of Subscription hooks for managing topic subscriptions without using the prebuilt Subscription components.

These hooks let you build fully custom experiences by working directly with the subscription data model.

<Callout type="info">If you prefer to use the default Subscription components, refer to the [Subscription components documentation](/platform/subscription/quickstart).</Callout>

## `useSubscriptions`

Fetches all subscriptions associated with a specific topic for the current subscriber.

### Hook parameters

<TypeTable
  type={{
  topicKey: {
    type: "string",
    description: "The unique key of the topic to fetch subscriptions for.",
    required: true
  },
  onSuccess: {
    type: "(data: TopicSubscription[]) => void",
    description: "Callback function called when subscriptions are successfully fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

### Return value

<TypeTable
  type={{
  subscriptions: {
    type: "TopicSubscription[]",
    description: "Array of subscription objects for the topic",
    default: "[]"
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the request failed",
  },
  isLoading: {
    type: "boolean",
    description: "True during the initial load",
  },
  isFetching: {
    type: "boolean",
    description: "True while any request is in flight (initial load or refetch)",
  },
  refetch: {
    type: "() => Promise<void>",
    description: "Function to manually trigger a refetch of the list",
  },
}}
/>

### Example usage

This example fetches all subscriptions for a given topic and exposes them for rendering once loading completes.

```tsx
import { useSubscriptions } from "@novu/react";

const { subscriptions, isLoading } = useSubscriptions({
  topicKey: "project-123",
});
```

## `useSubscription`

Fetches a specific subscription instance.

### Hook parameters

<TypeTable
  type={{
  topicKey: {
    type: "string",
    description: "The unique key of the topic.",
    required: true
  },
  identifier: {
    type: "string",
    description: "The unique identifier of the specific subscription instance.",
    required: false
  },
  onSuccess: {
    type: "(data: TopicSubscription | null) => void",
    description: "Callback function called when the subscription is fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

### Return value

<TypeTable
  type={{
  subscription: {
    type: "TopicSubscription | null",
    description: "The specific subscription object",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the request failed",
  },
  isLoading: {
    type: "boolean",
    description: "True during the initial load",
  },
  refetch: {
    type: "() => Promise<void>",
    description: "Function to manually trigger a refetch",
  },
}}
/>

### Example usage

This example shows how to retrieve a specific subscription by its identifier to access its preferences.

```tsx
import { useSubscription } from "@novu/react";

const { subscription, isLoading } = useSubscription({
  topicKey: "project-123",
  identifier: "user-preference-1",
});
```

## `useCreateSubscription`

Creates a new subscription to a topic for the current subscriber.

### Return value

<TypeTable
  type={{
  create: {
    type: "(args: CreateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>",
    description: "Function to create a new subscription.",
  },
  isCreating: {
    type: "boolean",
    description: "True while the create request is in progress",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the last create request failed",
  },
}}
/>

### Example usage

This example demonstrates how to trigger the creation of a new subscription for a topic.

```tsx
import { useCreateSubscription } from "@novu/react";

const { create, isCreating } = useCreateSubscription();

await create({
  topicKey: "project-123",
  identifier: "project-updates",
});
```

## `useUpdateSubscription`

Updates an existing subscription's properties or preferences list.

### Return value

<TypeTable
  type={{
  update: {
    type: "(args: UpdateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>",
    description: "Function to update an existing subscription.",
  },
  isUpdating: {
    type: "boolean",
    description: "True while the update request is in progress",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the last update request failed",
  },
}}
/>

### Example usage

This example shows how to update the preferences of an existing subscription, such as toggling a specific workflow.

```tsx
import { useUpdateSubscription } from "@novu/react";

const { update, isUpdating } = useUpdateSubscription();

const handleToggle = async () => {
  await update({
    topicKey: "project-123",
    subscriptionId: "sub-id-123",
    preferences: [{ workflowId: "workflow-one", enabled: false }]
  });
};
```

## `useRemoveSubscription`

Unsubscribes the current user from a topic by removing the subscription instance.

### Return value

<TypeTable
  type={{
  remove: {
    type: "(args: { subscriptionId: string; topicKey: string }) => Promise<{ error?: NovuError }>",
    description: "Function to delete the subscription.",
  },
  isRemoving: {
    type: "boolean",
    description: "True while the delete request is in progress",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the last remove request failed",
  },
}}
/>

### Example usage

This example renders an unsubscribe button that removes the subscription when clicked.

```tsx
import { useRemoveSubscription } from "@novu/react";

function UnsubscribeButton({ subscriptionId }) {
  const { remove, isRemoving } = useRemoveSubscription();

  return (
    <button
      onClick={() =>
        remove({
          subscriptionId,
          topicKey: "project-123",
        })
      }
      disabled={isRemoving}
    >
      {isRemoving ? "Removing..." : "Unsubscribe"}
    </button>
  );
}
```


# useCounts Hook (/platform/sdks/react/hooks/use-counts)

Learn how to use the useCounts hook to fetch notification counts in your React application

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

The `useCounts` hook provides a way to fetch various notification counts, including unread, unseen, total counts, or filtered by severity. This hook is useful for displaying notification badges and indicators in your application.

## Hook parameters

<TypeTable
  type={{
  filters: {
    type: "NotificationFilter[]",
    description: "Array of filters to apply when fetching counts",
    typeDescription: "Required",
    required: true,
  },
  onSuccess: {
    type: "(data: Count[]) => void",
    description:
      "Callback function called when counts are successfully fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

## Return value

```typescript
type Count = {
  count: number;
  filter: NotificationFilter;
};

type UseCountsResult = {
  counts?: Count[];
  error?: NovuError;
  isLoading: boolean;
  isFetching: boolean;
  refetch: () => Promise<void>;
};
```

## Example usage

Here's how to use the `useCounts` hook to fetch and display various notification counts, including unread, unseen, and counts based on severity.

```tsx
import { useCounts } from "@novu/react";

function BellButton() {
  const { counts } = useCounts({ 
    filters: [
      { read: false }, // Unread notifications
      { seen: false }  // Unseen notifications
      { severity: SeverityLevelEnum.HIGH } // High severity notifications
    ] 
  });
  
  const unreadCount = counts?.[0]?.count ?? 0;
  const unseenCount = counts?.[1]?.count ?? 0;
  const highSeverityCount = counts?.[2]?.count ?? 0;


  return (
    <button>
      <BellIcon />
      {/* Example: Show a badge for high severity, otherwise show the unread count */}
      {highSeverityCount > 0 ? (
        <span className="badge-high-severity">{highSeverityCount}</span>
      ) : unreadCount > 0 ? (
        <span className="badge">{unreadCount}</span>
      ) : null}
    </button>
  );
}
```

## Real-time counts updates

The counts are automatically updated in real-time when notifications state (read, seen, archived, snoozed) changes or when new notifications arrive.


# useNotifications Model - React (/platform/sdks/react/hooks/use-notifications)

API reference for the useNotifications hook return types and data models in the React SDK

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

The `useNotifications` hook provides a way to fetch and manage notifications in your application. It includes support for pagination, filtering, and real-time updates.

## Hook Parameters

<TypeTable
  name="UseNotificationsProps"
  type={{
"tags": {
  "description": "",
  "type": "string[]"
},
"data": {
  "description": "",
  "type": "Record<string, unknown>"
},
"read": {
  "description": "",
  "type": "boolean"
},
"archived": {
  "description": "",
  "type": "boolean"
},
"snoozed": {
  "description": "",
  "type": "boolean"
},
"seen": {
  "description": "",
  "type": "boolean"
},
"severity": {
  "description": "",
  "type": "SeverityLevelEnum | SeverityLevelEnum[]"
},
"createdGte": {
  "description": "",
  "type": "number"
},
"createdLte": {
  "description": "",
  "type": "number"
},
"limit": {
  "description": "",
  "type": "number"
},
"onSuccess": {
  "description": "",
  "type": "((data: Notification[]) => void)"
},
"onError": {
  "description": "",
  "type": "((error: NovuError) => void)"
}
}}
/>

## Return Value

<TypeTable
  name="UseNotificationsResult"
  type={{
"notifications": {
  "description": "",
  "type": "Notification[]"
},
"error": {
  "description": "",
  "type": "NovuError"
},
"isLoading": {
  "description": "",
  "type": "boolean"
},
"isFetching": {
  "description": "",
  "type": "boolean"
},
"hasMore": {
  "description": "",
  "type": "boolean"
},
"readAll": {
  "description": "",
  "type": "() => Promise<{ data?: void | undefined; error?: NovuError | undefined; }>"
},
"seenAll": {
  "description": "",
  "type": "() => Promise<{ data?: void | undefined; error?: NovuError | undefined; }>"
},
"archiveAll": {
  "description": "",
  "type": "() => Promise<{ data?: void | undefined; error?: NovuError | undefined; }>"
},
"archiveAllRead": {
  "description": "",
  "type": "() => Promise<{ data?: void | undefined; error?: NovuError | undefined; }>"
},
"refetch": {
  "description": "",
  "type": "() => Promise<void>"
},
"fetchMore": {
  "description": "",
  "type": "() => Promise<void>"
}
}}
/>

## Notification Type

The Notification type from @novu/react includes many properties. Here are the most commonly used ones:

<TypeTable
  name="NotificationType"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"transactionId": {
  "description": "",
  "type": "string"
},
"subject": {
  "description": "",
  "type": "string"
},
"body": {
  "description": "",
  "type": "string"
},
"to": {
  "description": "",
  "type": "Subscriber"
},
"isRead": {
  "description": "",
  "type": "boolean"
},
"isSeen": {
  "description": "",
  "type": "boolean"
},
"isArchived": {
  "description": "",
  "type": "boolean"
},
"isSnoozed": {
  "description": "",
  "type": "boolean"
},
"snoozedUntil": {
  "description": "",
  "type": "string | null"
},
"deliveredAt": {
  "description": "",
  "type": "string[]"
},
"createdAt": {
  "description": "",
  "type": "string"
},
"readAt": {
  "description": "",
  "type": "string | null"
},
"firstSeenAt": {
  "description": "",
  "type": "string | null"
},
"archivedAt": {
  "description": "",
  "type": "string | null"
},
"avatar": {
  "description": "",
  "type": "string"
},
"primaryAction": {
  "description": "",
  "type": "Action"
},
"secondaryAction": {
  "description": "",
  "type": "Action"
},
"channelType": {
  "description": "",
  "type": "ChannelType"
},
"tags": {
  "description": "",
  "type": "string[] | undefined"
},
"redirect": {
  "description": "",
  "type": "Redirect | undefined"
},
"data": {
  "description": "",
  "type": "NotificationData"
},
"workflow": {
  "description": "",
  "type": "Workflow"
},
"severity": {
  "description": "",
  "type": "SeverityLevelEnum"
},
"read": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unread": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"seen": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"archive": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unarchive": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"delete": {
  "description": "",
  "type": "() => Result<void, NovuError>"
},
"snooze": {
  "description": "",
  "type": "(snoozeUntil: string) => Result<Notification, NovuError>"
},
"unsnooze": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"completePrimary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"completeSecondary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"revertPrimary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"revertSecondary": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"on": {
  "description": "",
  "type": "<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => () => void"
},
"off": {
  "description": "",
  "type": "<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => void"
}
}}
/>

## Example Usage

Here's how to use the `useNotifications` hook to fetch and display notifications:

```tsx
import { useNotifications } from "@novu/react";

function NotificationsList() {
  const { notifications, hasMore, isLoading, error, fetchMore } =
    useNotifications();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div className="space-y-4">
      {notifications?.map((notification) => (
        <div key={notification.id} className="p-4 border rounded-lg">
          <h3 className="font-medium">{notification.subject}</h3>
          <p>{notification.body}</p>
          <div className="flex justify-between text-sm text-gray-500 mt-2">
            <span>{new Date(notification.createdAt).toLocaleString()}</span>
            <span>{notification.isRead ? "Read" : "Unread"}</span>
          </div>
        </div>
      ))}
      {hasMore && (
        <button
          onClick={fetchMore}
          className="w-full p-2 bg-blue-50 text-blue-600 rounded-md"
        >
          Load More
        </button>
      )}
    </div>
  );
}
```

### With Filtering

You can filter notifications by various properties:

* `read` - Filter notifications by read status
* `seen` - Filter notifications by seen status
* `tags` - Filter notifications by tags. If multiple tags are provided, Novu evaluates them using `OR` logic, meaning a notification is included if it contains at least one of the specified tags.
* `data` - Filter notifications by data attributes (key-value pairs).
* `severity` - Filter notifications by severity
* `limit` - Fetch notifications per page
* `createdGte` - Fetch notifications created after the given date (in milliseconds)
* `createdLte` - Fetch notifications created before the given date (in milliseconds)

```tsx
import { useNotifications } from "@novu/react";
import dayjs from "dayjs";

const now = dayjs();
// convert to milliseconds
const startDate = now.subtract(60, "days").valueOf();
const endDate = now.valueOf();  

function FilteredNotifications() {
  const { notifications, isLoading } = useNotifications({
    read: false, // Only unread notifications
    seen: false, // Only unseen notifications
    tags: ["important", "urgent"], // Only notifications with these tags (OR logic applied)
    // data attributes
    data: {
      type: "login",
      userName: "John Doe",
    },
    severity: SeverityLevelEnum.HIGH, // Only high severity notifications
    limit: 20, // Fetch 20 notifications per page
    createdGte: startDate, // Fetch notifications created in the last 60 days
    createdLte: endDate,
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div className="space-y-4">
      {notifications?.map((notification) => (
        <div key={notification.id} className="p-4 border rounded-lg">
          <h3 className="font-medium">{notification.subject}</h3>
          <p>{notification.body}</p>
        </div>
      ))}
    </div>
  );
}
```

### With Infinite Scroll

You can implement infinite scroll using the `fetchMore` function:

```tsx
import { useEffect, useRef } from "react";
import { useNotifications } from "@novu/react";

function InfiniteNotificationsList() {
  const { notifications, hasMore, isLoading, fetchMore } = useNotifications();
  const observerTarget = useRef(null);

  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0].isIntersecting && hasMore && !isLoading) {
          fetchMore();
        }
      },
      { threshold: 0.5 },
    );

    if (observerTarget.current) {
      observer.observe(observerTarget.current);
    }

    return () => observer.disconnect();
  }, [hasMore, isLoading, fetchMore]);

  if (!notifications) return <div>Loading...</div>;

  return (
    <div className="space-y-4">
      {notifications.map((notification) => (
        <div key={notification.id} className="p-4 border rounded-lg">
          <h3 className="font-medium">{notification.subject}</h3>
          <p>{notification.body}</p>
        </div>
      ))}
      {hasMore && <div ref={observerTarget} className="h-10" />}
    </div>
  );
}
```

### Using Notification Actions

The hook provides several actions to manage notifications:

```tsx
import { useNotifications } from "@novu/react";

function NotificationManager() {
  const { notifications, readAll, seenAll, archiveAll, archiveAllRead, isLoading } =
    useNotifications();

  const handleReadAll = async () => {
    const { error } = await readAll();
    if (error) {
      console.error("Failed to mark all as read:", error);
    }
  };

  const handleArchiveAll = async () => {
    const { error } = await archiveAll();
    if (error) {
      console.error("Failed to archive all:", error);
    }
  };

  const handleSeenAll = async () => {
    const { error } = await seenAll();
    if (error) {
      console.error("Failed to mark all as seen:", error);
    }
  };

  const handleArchiveAllRead = async () => {
    const { error } = await archiveAllRead();
    if (error) {
      console.error("Failed to archive read notifications:", error);
    }
  };

  return (
    <div>
      <div className="flex gap-2 mb-4">
        <button
          onClick={handleReadAll}
          className="px-3 py-1 bg-blue-500 text-white rounded-md"
          disabled={isLoading}
        >
          Mark All as Read
        </button>
        <button
          onClick={handleSeenAll}
          className="px-3 py-1 bg-green-500 text-white rounded-md"
          disabled={isLoading}
        >
          Mark All as Seen
        </button>
        <button
          onClick={handleArchiveAll}
          className="px-3 py-1 bg-gray-500 text-white rounded-md"
          disabled={isLoading}
        >
          Archive All
        </button>
        <button
          onClick={handleArchiveAllRead}
          className="px-3 py-1 bg-gray-500 text-white rounded-md"
          disabled={isLoading}
        >
          Archive Read
        </button>
      </div>

      <div className="space-y-4">
        {notifications?.map((notification) => (
          <div key={notification.id} className="p-4 border rounded-lg">
            <h3 className="font-medium">{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Real-time notifications updates

The notifications list is automatically updated in real-time when new notifications arrive or when notifications state (read, seen, archived, snoozed) changes.


# Novu React useNovu Hook (/platform/sdks/react/hooks/use-novu)

Learn how to use the useNovu hook to access the Novu client instance in your React application

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

The `useNovu` hook provides direct access to the [Novu client instance](/platform/inbox/headless-mode) from anywhere in your application. This hook must be used within a component that is wrapped by the `NovuProvider`.

## Return Value

<TypeTable
  type={{
  novu: {
    type: "Novu",
    description:
      "The Novu client instance that provides access to all Novu API methods",
  },
}}
/>

## Example usage

Here's how to use the `useNovu` hook to interact with the Novu client:

```tsx
import { useNovu } from "@novu/react";

function NotificationActions() {
  const novu = useNovu();

  const markAllAsRead = async () => {
    try {
      await novu.notifications.readAll();
      console.log("All notifications marked as read");
    } catch (error) {
      console.error("Failed to mark all as read:", error);
    }
  };

  const archiveAllRead = async () => {
    try {
      await novu.notifications.archiveAllRead();
      console.log("All read notifications archived");
    } catch (error) {
      console.error("Failed to archive read notifications:", error);
    }
  };

  return (
    <div className="flex gap-2">
      <button
        onClick={markAllAsRead}
        className="px-3 py-1 bg-blue-500 text-white rounded-md"
      >
        Mark All as Read
      </button>
      <button
        onClick={archiveAllRead}
        className="px-3 py-1 bg-gray-500 text-white rounded-md"
      >
        Archive All Read
      </button>
    </div>
  );
}
```

### Managing individual notifications

The Novu client provides methods for managing individual notifications:

```tsx
import type { Notification as INotification } from "@novu/react";
import { useNovu } from "@novu/react";

function NotificationItem({ notification }: { notification: INotification }) {
  const novu = useNovu();

  const markAsRead = async () => {
    try {
      await novu.notifications.read({ notificationId: notification.id });
      console.log("Notification marked as read");
    } catch (error) {
      console.error("Failed to mark as read:", error);
    }
  };

  const markAsUnread = async () => {
    try {
      await novu.notifications.unread({ notificationId: notification.id });
      console.log("Notification marked as unread");
    } catch (error) {
      console.error("Failed to mark as unread:", error);
    }
  };

  const archive = async () => {
    try {
      await novu.notifications.archive({ notificationId: notification.id });
      console.log("Notification archived");
    } catch (error) {
      console.error("Failed to archive:", error);
    }
  };

  return (
    <div className="p-4 border rounded-lg">
      <h3 className="font-medium">{notification.subject}</h3>
      <p>{notification.body}</p>
      <div className="flex gap-2 mt-2">
        <button
          onClick={markAsRead}
          className="px-2 py-1 text-sm bg-blue-50 text-blue-600 rounded"
          disabled={notification.isRead}
        >
          Mark as Read
        </button>
        <button
          onClick={markAsUnread}
          className="px-2 py-1 text-sm bg-blue-50 text-blue-600 rounded"
          disabled={!notification.isRead}
        >
          Mark as Unread
        </button>
        <button
          onClick={archive}
          className="px-2 py-1 text-sm bg-gray-50 text-gray-600 rounded"
          disabled={notification.isArchived}
        >
          Archive
        </button>
      </div>
    </div>
  );
}
```

### Updating single workflow's channel preferences

Workflow's channel preferences can be updated using `novu.preferences.update` method.

```tsx
import { useNovu } from '@novu/react';

function UpdateSinglePreferences() {
  const { novu } = useNovu();

  const updatePreferences = async () => {
    await novu.preferences.update({
      workflowId: 'workflow_id',
      channels: {
        email: false,
        sms: true,
      },
    });
  };

  return <Button title="Update Single Preferences" onPress={updatePreferences} />;
}
```

### Updating multiple workflow's channel preferences

Using `novu.preferences.bulkUpdate` multiple workflow's channel preferences can be updated at once.

```tsx
import { useNovu } from "@novu/react";

function UpdateMultiplePreferences() {
  const novu = useNovu();

  const updateBulkPreferences = async () => {
    try {
      await novu.preferences.bulkUpdate([
      {
        workflowId: "workflowId_1",
        channels: {
          email: true,
          in_app: false,
        },
      },
      {
        workflowId: "workflowId_2",
        channels: {
          email: true,
          in_app: false,
        },
      },
    ]);
    } catch (error) {
      console.error("Failed to update preferences:", error);
    }
  };

  return (
    <button onClick={updateBulkPreferences}>Update Bulk Preferences</button>
  );
}
```

### Listening to real-time events

The Novu client allows you to listen for real-time events:

```tsx
import { useNovu } from "@novu/react";
import { useEffect } from "react";
import type { Notification as INotification } from "@novu/react";

function NotificationListener() {
  const novu = useNovu();

  useEffect(() => {
    // Handler for new notifications
    const handleNewNotification = ({ result }: { result: INotification }) => {
      console.log("New notification:", result.subject);
      // You can use a toast library to show notifications
      // toast({
      //   title: result.subject,
      //   description: result.body,
      // });
    };

    // Handler for unread count changes
    const handleUnreadCountChanged = ({ result }: { result: number }) => {
      // Update favicon or title to show unread count
      document.title = result > 0 ? `(${result}) My App` : "My App";
    };

    // Subscribe to events
    novu.on("notifications.notification_received", handleNewNotification);
    novu.on("notifications.unread_count_changed", handleUnreadCountChanged);

    // Cleanup function
    return () => {
      novu.off("notifications.notification_received", handleNewNotification);
      novu.off("notifications.unread_count_changed", handleUnreadCountChanged);
    };
  }, [novu]);

  return null; // This component doesn't render anything
}
```

<Callout type="info">
  The Novu client instance provides access to all the functionality available in the [Headless API](/platform/sdks/javascript). For a complete list of methods and events, refer to the API documentation.
</Callout>


# Novu React usePreferences Hook (/platform/sdks/react/hooks/use-preferences)

Learn how to use the usePreferences hook to manage notification preferences in your React application

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

The `usePreferences` hook provides a way to fetch and manage notification preferences for the current subscriber. This includes both global preferences and workflow-specific preferences.

## Hook parameters

<TypeTable
  type={{
  filter: {
    type: "{ tags?: string[]; severity?: SeverityLevelEnum[]}",
    description: "Filter preferences by tags and severity",
  },
  onSuccess: {
    type: "(data: Preference[]) => void",
    description:
      "Callback function called when preferences are successfully fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

## Return value

<TypeTable
  type={{
  preferences: {
    type: "Preference[] | undefined",
    description: "Array of preference objects",
    typeDescription: "undefined if data is not yet loaded",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the request failed",
    typeDescription: "undefined if no error occurred",
  },
  isLoading: {
    type: "boolean",
    description: "True during the initial load, false otherwise",
    default: "true",
  },
  isFetching: {
    type: "boolean",
    description:
      "True during any loading state (initial or refetch), false otherwise",
    default: "true",
  },
  refetch: {
    type: "() => Promise<void>",
    description: "Function to manually trigger a refetch of the preferences",
  },
}}
/>

## Preference type

The Preference type from `@novu/react` includes these properties:

<TypeTable
  type={{
  level: {
    type: "PreferenceLevel",
    description: "Level of the preference (global or template)",
  },
  enabled: {
    type: "boolean",
    description: "Whether notifications are enabled for this preference",
  },
  channels: {
    type: "{ email?: boolean; sms?: boolean; in_app?: boolean; chat?: boolean; push?: boolean; }",
    description: "Channel-specific preferences",
  },
  workflow: {
    type: "{ id: string; name: string; critical: boolean; }",
    description: "Information about the associated workflow",
    typeDescription: "Only available for template-level preferences",
  },
}}
/>

## Example usage

Here's how to use the `usePreferences` hook to display and manage notification preferences:

```tsx
import type { Preference, ChannelType } from "@novu/react";
import { usePreferences } from "@novu/react";

function PreferencesList() {
  const { preferences, isLoading, error, refetch } = usePreferences();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  const updatePreference = async (
    preference: Preference,
    channelType: string,
    enabled: boolean,
  ) => {
    try {
      await preference.update({
        channels: {
          [channelType]: enabled,
        },
      });

      // Refresh preferences
      refetch();
    } catch (error) {
      console.error("Failed to update preference:", error);
    }
  };

  return (
    <div className="space-y-4">
      {preferences?.map((preference) => (
        <div
          key={preference.workflow?.id || "global"}
          className="p-4 border rounded-lg"
        >
          <h3 className="font-medium">
            {preference.workflow?.name || "Global Preferences"}
            {preference.workflow?.critical && (
              <span className="ml-2 text-xs bg-red-100 text-red-800 px-2 py-1 rounded">
                Critical
              </span>
            )}
          </h3>

          <div className="mt-2 space-y-2">
            {Object.entries(preference.channels).map(([channel, enabled]) => (
              <div key={channel} className="flex items-center justify-between">
                <span className="capitalize">{channel.replace("_", " ")}</span>
                <label className="relative inline-flex items-center cursor-pointer">
                  <input
                    type="checkbox"
                    checked={enabled}
                    disabled={preference.workflow?.critical}
                    onChange={(e) =>
                      updatePreference(preference, channel, e.target.checked)
                    }
                    className="sr-only peer"
                  />
                  <div className="w-11 h-6 bg-gray-200 peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-blue-300 rounded-full peer peer-checked:after:translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-5 after:w-5 after:transition-all peer-checked:bg-blue-600 peer-disabled:opacity-50 peer-disabled:cursor-not-allowed"></div>
                </label>
              </div>
            ))}
          </div>
        </div>
      ))}
    </div>
  );
}
```

### With filtering

You can filter preferences by tags or severity:

```tsx
import { NovuProvider, usePreferences, SeverityLevelEnum } from "@novu/react";

export default function Novu() {

  function FilteredPreferences() {
    const { preferences, isLoading } = usePreferences({
      filter: {
        tags: ["important", "marketing"],
        severity: [SeverityLevelEnum.HIGH],
      },
    });

    if (isLoading) return <div>Loading...</div>;

    return (
      <div className="space-y-4">
        <h2 className="text-xl font-bold">High severity marketing preferences</h2>
        {preferences?.map((preference) => (
          <div
            key={preference.workflow?.id || "global"}
            className="p-4 border rounded-lg"
          >
            <h3 className="font-medium">
              {preference.workflow?.name || "Global Preferences"}
            </h3>
            {/* Preference controls */}
          </div>
        ))}
      </div>
    );
  }

  return (
  <NovuProvider
    applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
    subscriber="YOUR_SUBSCRIBER_ID"
  >
    <FilteredPreferences />
  </NovuProvider>
);
}
```

### With channel groups

You can organize preferences by channel type:

```tsx
import type { Preference, ChannelType } from "@novu/react";
import { usePreferences } from "@novu/react";

function ChannelPreferences() {
  const { preferences, isLoading, refetch } = usePreferences();

  if (isLoading) return <div>Loading...</div>;

  const updatePreference = async (
    preference: Preference,
    channelType: string,
    enabled: boolean,
  ) => {
    try {
      await preference.update({
        channels: {
          [channelType]: enabled,
        },
      });
      refetch();
    } catch (error) {
      console.error("Failed to update preference:", error);
    }
  };

  // Group preferences by channel
  const channels = ["email", "sms", "in_app", "push", "chat"];

  return (
    <div className="space-y-8">
      {channels.map((channel) => (
        <div key={channel} className="border-t pt-4">
          <h2 className="text-xl font-medium capitalize mb-4">
            {channel.replace("_", " ")} Notifications
          </h2>
          <div className="space-y-2">
            {preferences
              ?.filter((pref) => channel in pref.channels)
              .map((preference) => (
                <div
                  key={preference.workflow?.id || "global"}
                  className="flex items-center justify-between p-2 hover:bg-gray-50 rounded"
                >
                  <span>
                    {preference.workflow?.name || "Global Preferences"}
                  </span>
                  <label className="relative inline-flex items-center cursor-pointer">
                    <input
                      type="checkbox"
                      checked={
                        preference.channels[
                          channel as keyof typeof preference.channels
                        ]
                      }
                      disabled={preference.workflow?.critical}
                      onChange={(e) =>
                        updatePreference(preference, channel, e.target.checked)
                      }
                      className="sr-only peer"
                    />
                    <div className="w-11 h-6 bg-gray-200 rounded-full peer peer-checked:after:translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-5 after:w-5 after:transition-all peer-checked:bg-blue-600 peer-disabled:opacity-50 peer-disabled:cursor-not-allowed"></div>
                  </label>
                </div>
              ))}
          </div>
        </div>
      ))}
    </div>
  );
}
```

<Callout type="info">
  Changes to preferences are automatically synchronized with the server and will
  affect future notifications immediately.
</Callout>


# Novu React useSchedule Hook (/platform/sdks/react/hooks/use-schedule)

Learn how to use the useSchedule hook to manage subscriber notification schedules in your React application

import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

Schedules define when notifications should be delivered by setting availability hours across days of the week. The `useSchedule` hook provides a way to fetch, display, and update the notification schedule for the current subscriber.

## Hook parameters

<TypeTable
  type={{
  onSuccess: {
    type: "(data: Schedule) => void",
    description:
      "Callback function called when the schedule is successfully fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

## Return value

<TypeTable
  type={{
  schedule: {
    type: "Schedule | undefined",
    description: "The subscriber's current schedule object",
    typeDescription: "undefined if data is not yet loaded",
  },
  error: {
    type: "NovuError | undefined",
    description: "Error object if the request failed",
  },
  isLoading: {
    type: "boolean",
    description: "True during the initial load, false otherwise",
    default: "true",
  },
  isFetching: {
    type: "boolean",
    description:
      "True while any request is in flight (initial load or refetch), false otherwise",
    default: "true",
  },
  refetch: {
    type: "() => Promise<void>",
    description: "Function to manually trigger a refetch of the schedule",
  },
}}
/>

## Schedule type

The `Schedule` type from `@novu/react` includes these properties:

<TypeTable
  type={{
  isEnabled: {
    type: "boolean",
    description: "Global flag to enable or disable the entire schedule.",
  },
  weeklySchedule: {
    type: "object",
    description: "An object containing the schedule for each day of the week (for example, monday, tuesday). Each key holds a DaySchedule object.",
  },
}}
/>

### Schedule object structure.

Each `DaySchedule` object within `weeklySchedule` has the following structure:

<TypeTable
  type={{
  isEnabled: {
    type: "boolean",
    description: "Flag to enable or disable the schedule for this specific day.",
  },
  hours: {
    type: "Array<{ start: string; end: string; }>",
    description: "An array of time ranges for when notifications are allowed. Multiple ranges per day are supported (for example, 9-12 AM and 2-5 PM).",
  },
}}
/>

## Updating the schedule

The hook also allows updating the subscriber’s schedule via `schedule.update`:

```tsx
const handleClick = async () => {
  await schedule?.update({
    isEnabled: true,
    weeklySchedule: {
      monday: {
        isEnabled: true,
        hours: [{ start: '08:00 AM', end: '18:00 PM' }],
      },
    }
  })
};
```

## Example usage

Here's how to use the `useSchedule` hook to display and update a subscriber's notification schedule. The `schedule.update()` method creates a schedule if one doesn't exist or updates the existing one.

```tsx
import { useSchedule } from "@novu/react";

function ScheduleManager() {
  const { schedule, isLoading, error, refetch } = useSchedule();

  if (isLoading) return <div>Loading schedule...</div>;
  if (error) return <div>Error: {error.message}</div>;

  const handleUpdateSchedule = async () => {
    await schedule?.update({
      isEnabled: true,
      weeklySchedule: {
        monday: {
          isEnabled: true,
          hours: [
            { start: '09:00 AM', end: '12:00 PM' },
            { start: '02:00 PM', end: '05:00 PM' },
          ],
        },
        tuesday: {
          isEnabled: true,
          hours: [{ start: '09:00 AM', end: '05:00 PM' }],
        },
        // Other days can be left undefined or explicitly disabled
        wednesday: {
          isEnabled: false,
          hours: [],
        },
      },
    });    
  };

  return (
    <div className="p-4 border rounded-lg">
      <h3 className="font-medium">My Notification Schedule</h3>
      <p>
        Schedule Enabled: <strong>{schedule?.isEnabled ? 'Yes' : 'No'}</strong>
      </p>
      
      <div className="mt-2">
        <h4 className="font-medium">Monday Hours:</h4>
        {schedule?.weeklySchedule?.monday?.isEnabled ? (
          <ul className="list-disc pl-5">
            {schedule.weeklySchedule.monday.hours.map((range, index) => (
              <li key={index}>{`${range.start} - ${range.end}`}</li>
            ))}
          </ul>
        ) : (
          <p>Not scheduled</p>
        )}
      </div>

      <button
        onClick={handleUpdateSchedule}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
      >
        Set Default Work Hours
      </button>
    </div>
  );
}
```


# Novu React Native NovuProvider Hook (/platform/sdks/react-native/hooks/novu-provider)

Learn how to use the NovuProvider component to set up the Novu context in your React Native application

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `NovuProvider` is the top-level component that provides the [Novu instance](/platform/inbox/headless-mode) to the rest of the hooks through the context.
Usually, it's placed somewhere in the root of your application, which makes the hooks accessible throughout the application.

## Props

| Prop                  | Type      | Required | Description                                                    |
| --------------------- | --------- | -------- | -------------------------------------------------------------- |
| subscriberId          | string    | Yes      | The unique identifier of the subscriber                        |
| applicationIdentifier | string    | Yes      | Your application identifier from Novu                          |
| subscriberHash        | string    | No       | HMAC encryption hash for the subscriber                        |
| apiUrl                | string    | No       | Custom api url for self-hosted instances                       |
| socketUrl             | string    | No       | Custom socket URL for self-hosted instances                    |
| children              | ReactNode | Yes      | The child components that will have access to the Novu context |

## Example Usage

<Tabs items={['US', 'EU', 'HMAC Encryption']}>
  <Tab>
    ```tsx
    import { NovuProvider } from '@novu/react-native';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { NovuProvider } from '@novu/react-native';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
          apiUrl="https://eu.api.novu.co"
          socketUrl="wss://eu.socket.novu.co"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    <Callout type="info">
      Read more about [HMAC Encryption](/platform/inbox/prepare-for-production#secure-your-inbox-with-hmac-encryption).
    </Callout>

    ```tsx
    import { NovuProvider } from '@novu/react-native';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
          subscriberHash="SUBSCRIBER_HASH_HMAC_ENCRYPTION"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>
</Tabs>


# Novu React Native useCounts Hook (/platform/sdks/react-native/hooks/use-counts)

Learn how to use the useCounts hook to fetch notification counts in your React Native application

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `useCounts` hook provides a way to fetch various notification counts, including unread, unseen, and total counts. This hook is useful for displaying notification badges and indicators in your application.

## Hook Parameters

| Parameter | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| storeId   | string | No       | Filter counts by a specific store ID      |
| query     | object | No       | Additional query parameters for filtering |

## Return Value

```typescript
type CountsReturn = {
  data: {
    unreadCount: number;
    unseenCount: number;
    total: number;
  };
  isLoading: boolean;
  error: Error | null;
  refetch: () => void;
};
```

## Example Usage

Here's how to use the `useCounts` hook to fetch and display notification counts:

```tsx
import { View, Text, ActivityIndicator } from 'react-native';
import { useCounts } from '@novu/react-native';

function NotificationBadge() {
  const { data, isLoading, error } = useCounts();

  if (isLoading) return <ActivityIndicator />;
  if (error) return <Text>Error: {error.message}</Text>;

  return (
    <View>
      <Text>Unread: {data?.unreadCount}</Text>
      <Text>Unseen: {data?.unseenCount}</Text>
      <Text>Total: {data?.total}</Text>
    </View>
  );
}
```

### With Store ID

You can filter counts for a specific store:

```tsx
import { View, Text, ActivityIndicator } from 'react-native';
function StoreNotifications({ storeId }) {
  const { data, isLoading } = useCounts({
    storeId: storeId,
  });

  if (isLoading) return <ActivityIndicator />;

  return (
    <View>
      <Text>Store Notifications: {data?.total}</Text>
      <Text>Unread: {data?.unreadCount}</Text>
    </View>
  );
}
```

### With Query Filters

You can also apply additional filters using the query parameter:

```tsx
import { View, Text, ActivityIndicator } from 'react-native';
function FilteredNotifications() {
  const { data, isLoading } = useCounts({
    query: {
      templates: ['welcome-template', 'order-update'],
      emails: ['user@example.com'],
    },
  });

  if (isLoading) return <ActivityIndicator />;

  return (
    <View>
      <Text>Filtered Notifications: {data?.total}</Text>
      <Text>Unread: {data?.unreadCount}</Text>
    </View>
  );
}
```

<Callout type="info">
  `refetch` function can be used to refetch updated counts after notifications are marked as read/unread/archived etc.
</Callout>


# useNotifications - React Native (/platform/sdks/react-native/hooks/use-notifications)

Learn how to use the useNotifications hook to fetch and manage notifications in your React Native application

The `useNotifications` hook provides a way to fetch and manage notifications in your React Native application. It includes support for pagination, and filtering.

## Hook Parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| storeId   | string | No       | Filter notifications by a specific store ID |
| query     | object | No       | Additional query parameters for filtering   |

## Return Value

```typescript
type NotificationReturn = {
  notifications: {
    id: string;
    content: string;
    createdAt: Date;
    read: boolean;
    seen: boolean;
    // ... other notification fields
  }[];
  hasMore: boolean;
  isLoading: boolean;
  error: Error | null;
  loadMore: () => void;
  refetch: () => void;
};
```

## Example Usage

Here's how to use the `useNotifications` hook to fetch and display notifications:

```tsx
import { useNotifications } from '@novu/react-native';
import { View, Text, ActivityIndicator, FlatList } from 'react-native';

function NotificationsList() {
  const { notifications, hasMore, isLoading, error, loadMore } = useNotifications();

  if (isLoading) return <ActivityIndicator />;
  if (error) return <Text>Error: {error.message}</Text>;

  return (
    <FlatList
      data={notifications}
      keyExtractor={(item) => item.id}
      renderItem={({ item: notification }) => (
        <View>
          <Text>{notification.content}</Text>
          <Text>{new Date(notification.createdAt).toLocaleString()}</Text>
          <Text>{notification.read ? 'Read' : 'Unread'}</Text>
        </View>
      )}
      onEndReached={hasMore ? loadMore : undefined}
      onEndReachedThreshold={0.5}
      ListFooterComponent={hasMore ? <ActivityIndicator /> : null}
    />
  );
}
```

### With Pull to Refresh

You can implement pull-to-refresh using the `refetch` function:

```tsx
import { useNotifications } from '@novu/react-native';
import { RefreshControl, FlatList, View, Text, ActivityIndicator } from 'react-native';

function RefreshableNotificationsList() {
  const { notifications, isLoading, refetch } = useNotifications();

  return (
    <FlatList
      data={notifications}
      keyExtractor={(item) => item.id}
      renderItem={({ item: notification }) => (
        <View>
          <Text>{notification.content}</Text>
          <Text>{new Date(notification.createdAt).toLocaleString()}</Text>
        </View>
      )}
      refreshControl={<RefreshControl refreshing={isLoading} onRefresh={refetch} />}
    />
  );
}
```

### With Filters

You can apply filters using the query parameter:

```tsx
import { RefreshControl, FlatList, View, Text, ActivityIndicator } from 'react-native';

function FilteredNotifications() {
  const { notifications, isLoading } = useNotifications({
    query: {
      templates: ['welcome-template', 'order-update'],
      emails: ['user@example.com'],
    },
  });

  if (isLoading) return <ActivityIndicator />;

  return (
    <FlatList
      data={notifications}
      keyExtractor={(item) => item.id}
      renderItem={({ item: notification }) => (
        <View>
          <Text>{notification.content}</Text>
        </View>
      )}
    />
  );
}
```


# Novu React Native useNovu Hook (/platform/sdks/react-native/hooks/use-novu)

Learn how to use the useNovu hook to access the Novu client instance in your React Native application

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `useNovu` hook provides access to the [Novu client instance](/platform/inbox/headless-mode) from anywhere in your React Native application. This hook must be used within a component that is wrapped by the `NovuProvider`.

## Return Value

```typescript
type NovuReturn = {
  novu: Novu;
  isLoading: boolean;
  error: Error | null;
};
```

## Example Usage

Here's how to use the `useNovu` hook to interact with the Novu client:

```tsx
import { useNovu } from '@novu/react-native';
import { View, Button, ActivityIndicator } from 'react-native';

function NotificationActions() {
  const novu = useNovu();

  if (isLoading) return <ActivityIndicator />;

  const markAllAsRead = async () => {
    await novu.notifications.readAll();
  };

  const archiveAllRead = async () => {
    await novu.notifications.archiveAllRead();
  };

  return (
    <View>
      <Button title="Mark All as Read" onPress={markAllAsRead} />
      <Button title="Archive All Read" onPress={archiveAllRead} />
    </View>
  );
}
```

### Accessing Notification Methods

The Novu client provides methods for managing notifications:

```tsx
import { View, Text, Button } from 'react-native';
import { useNovu } from '@novu/react-native';

function NotificationItem({ notification }) {
  const { novu } = useNovu();

  const markAsRead = async () => {
    await novu.notifications.read(notification.id);
  };

  const archive = async () => {
    await novu.notifications.archive(notification.id);
  };

  return (
    <View>
      <Text>{notification.content}</Text>
      <Button title="Mark as Read" onPress={markAsRead} />
      <Button title="Archive" onPress={archive} />
    </View>
  );
}
```

### Updating single workflow's channel preferences

Workflow's channel preferences can be updated using `novu.preferences.update` method.

```tsx
import { Button } from 'react-native';
import { useNovu } from '@novu/react-native';

function PreferencesManager() {
  const novu = useNovu();

  const updatePreferences = async () => {
    await novu.preferences.update({
      workflowId: 'workflow_id',
      channels: {
        email: false,
        sms: true,
      },
    });
  };

  return <Button title="Update SinglePreferences" onPress={updatePreferences} />;
}
```

### Updating multiple workflow's channel preferences

Using `novu.preferences.bulkUpdate` method multiple workflow's channel preferences can be updated at once.

```tsx
import { Button } from 'react-native';
import { useNovu } from "@novu/react-native";

function UpdateMultiplePreferences() {
  const novu = useNovu();

  const updateBulkPreferences = async () => {
    try {
      await novu.preferences.bulkUpdate([
      {
        workflowId: "workflowId_1",
        channels: {
          email: true,
          in_app: false,
        },
      },
      {
        workflowId: "workflowId_2",
        channels: {
          email: true,
          in_app: false,
        },
      },
    ]);
    } catch (error) {
      console.error("Failed to update preferences:", error);
    }
  };

  return <Button title="Update Multiple Preferences" onPress={updateBulkPreferences} />;
}
```

### Listening for new notifications

```tsx
import { useNovu } from '@novu/react-native';

const NotificationToast = () => {
  const novu = useNovu();

  useEffect(() => {
    const listener = ({ result: notification }) => {
      // Show a toast notification
    };

    novu.on('notifications.notification_received', listener);

    return () => {
      novu.off('notifications.notification_received', listener);
    };
  }, [novu]);

  return null;
};
```

<Callout type="info">
  The Novu client instance provides access to all the functionality available in the [Headless
  API](/platform/inbox/headless-mode).
</Callout>


# Novu React Native usePreferences Hook (/platform/sdks/react-native/hooks/use-preferences)

Learn how to use the usePreferences hook to manage notification preferences in your React Native application

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `usePreferences` hook provides a way to fetch and manage notification preferences for the current subscriber. This includes both global preferences and workflow-specific preferences.

## Return Value

```typescript
type PreferencesReturn = {
  preferences: Array<{
    template: {
      _id: string;
      name: string;
      critical: boolean;
    };
    channels: {
      email?: boolean;
      sms?: boolean;
      in_app?: boolean;
      chat?: boolean;
      push?: boolean;
    };
  }>;
  isLoading: boolean;
  error: Error | null;
  updatePreference: (params: {
    templateId: string;
    channelType: string;
    enabled: boolean;
  }) => Promise<void>;
};
```

## Example Usage

Here's how to use the `usePreferences` hook to display and manage notification preferences:

```tsx
import { usePreferences } from '@novu/react-native';
import { View, Text, Switch, ActivityIndicator } from 'react-native';

function PreferencesList() {
  const { preferences, isLoading, error, updatePreference } = usePreferences();

  if (isLoading) return <ActivityIndicator />;
  if (error) return <Text>Error: {error.message}</Text>;

  return (
    <View>
      {preferences.map((preference) => (
        <View key={preference.template._id}>
          <Text style={styles.heading}>{preference.template.name}</Text>

          <View style={styles.row}>
            <Text>Email Notifications</Text>
            <Switch
              value={preference.channels.email}
              onValueChange={(enabled) => {
                updatePreference({
                  templateId: preference.template._id,
                  channelType: 'email',
                  enabled,
                });
              }}
            />
          </View>

          <View style={styles.row}>
            <Text>SMS Notifications</Text>
            <Switch
              value={preference.channels.sms}
              onValueChange={(enabled) => {
                updatePreference({
                  templateId: preference.template._id,
                  channelType: 'sms',
                  enabled,
                });
              }}
            />
          </View>
        </View>
      ))}
    </View>
  );
}

const styles = {
  heading: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 10,
  },
  row: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    alignItems: 'center',
    paddingVertical: 8,
  },
};
```

### With Channel Groups

You can organize preferences by channel type:

```tsx
import { View, Text, Switch } from 'react-native';
function ChannelPreferences() {
  const { preferences, updatePreference } = usePreferences();

  const emailPreferences = preferences.filter((pref) => pref.channels.email !== undefined);

  return (
    <View>
      <Text style={styles.heading}>Email Preferences</Text>
      {emailPreferences.map((preference) => (
        <View key={preference.template._id} style={styles.row}>
          <Text>{preference.template.name}</Text>
          <Switch
            value={preference.channels.email}
            onValueChange={(enabled) => {
              updatePreference({
                templateId: preference.template._id,
                channelType: 'email',
                enabled,
              });
            }}
          />
        </View>
      ))}
    </View>
  );
}
```

### With Critical Workflows

Some workflows might be marked as critical, meaning they cannot be disabled:

```tsx
import { View, Text, Switch } from 'react-native';

function CriticalPreferences() {
  const { preferences, updatePreference } = usePreferences();

  return (
    <View>
      {preferences.map((preference) => (
        <View key={preference.template._id}>
          <Text style={styles.heading}>{preference.template.name}</Text>
          {preference.template.critical ? (
            <Text style={styles.critical}>Critical - Cannot be disabled</Text>
          ) : (
            <View style={styles.row}>
              <Text>Enable Notifications</Text>
              <Switch
                value={preference.channels.email}
                onValueChange={(enabled) => {
                  updatePreference({
                    templateId: preference.template._id,
                    channelType: 'email',
                    enabled,
                  });
                }}
              />
            </View>
          )}
        </View>
      ))}
    </View>
  );
}

const styles = {
  critical: {
    color: 'red',
    fontStyle: 'italic',
  },
};
```

<Callout type="info">
  Changes to preferences are automatically synchronized with the server and will affect future
  notifications immediately.
</Callout>


# Novu React Native useSchedule Hook (/platform/sdks/react-native/hooks/use-schedule)

Learn how to use the useSchedule hook to manage notification delivery schedules in your React Native application

The `useSchedule` hook provides a way to fetch and manage the notification schedule for the current subscriber. It allows you to retrieve the existing schedule and update it with new availability settings directly from your React Native app.

## Return Value

```tsx
type ScheduleReturn = {
  schedule?: {
    isEnabled: boolean;
    weeklySchedule: {
      monday?: DaySchedule;
      tuesday?: DaySchedule;
      wednesday?: DaySchedule;
      thursday?: DaySchedule;
      friday?: DaySchedule;
      saturday?: DaySchedule;
      sunday?: DaySchedule;
    };
    update: (params: Partial<Schedule>) => Promise<void>;
  };
  isLoading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
};

type DaySchedule = {
  isEnabled: boolean;
  hours: Array<{ start: string; end:string; }>;
};
```

## Example usage

Here's how to use the `useSchedule` hook in a React Native component to display and update a subscriber's notification schedule. The `schedule.update()` method will create a schedule if one doesn't exist or update the existing one.

```tsx
import { useSchedule } from '@novu/react-native';
import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator } from 'react-native';

function ScheduleManager() {
  const { schedule, isLoading, error, refetch } = useSchedule();

  if (isLoading) {
    return <ActivityIndicator size="large" style={styles.loader} />;
  }
  
  if (error) {
    return <Text style={styles.errorText}>Error: {error.message}</Text>;
  }

  const handleUpdateSchedule = async () => {
    await schedule?.update({
      isEnabled: true,
      weeklySchedule: {
        monday: {
          isEnabled: true,
          hours: [{ start: '09:00 AM', end: '05:00 PM' }],
        },
        // Disable Wednesday
        wednesday: {
          isEnabled: false,
          hours: [],
        },
      },
    });
  };

  return (
    <View style={styles.container}>
      <Text style={styles.heading}>My Notification Schedule</Text>
      <Text style={styles.text}>
        Schedule Enabled: 
        <Text style={styles.boldText}> {schedule?.isEnabled ? 'Yes' : 'No'}</Text>
      </Text>
      
      <View style={styles.dayContainer}>
        <Text style={styles.subHeading}>Monday Hours:</Text>
        {schedule?.weeklySchedule?.monday?.isEnabled ? (
          schedule.weeklySchedule.monday.hours.map((range, index) => (
            <Text key={index} style={styles.text}>{`• ${range.start} - ${range.end}`}</Text>
          ))
        ) : (
          <Text style={styles.text}>Not scheduled</Text>
        )}
      </View>

      <TouchableOpacity
        onPress={handleUpdateSchedule}
        style={styles.button}
      >
        <Text style={styles.buttonText}>Set Work Hours</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 16,
    backgroundColor: '#FFFFFF',
  },
  loader: {
    marginTop: 20,
  },
  errorText: {
    color: 'red',
    textAlign: 'center',
  },
  heading: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 12,
  },
  subHeading: {
    fontSize: 16,
    fontWeight: 'bold',
    marginBottom: 4,
  },
  text: {
    fontSize: 16,
    marginBottom: 4,
  },
  boldText: {
    fontWeight: 'bold',
  },
  dayContainer: {
    marginTop: 12,
  },
  button: {
    marginTop: 16,
    backgroundColor: '#007BFF',
    padding: 12,
    borderRadius: 8,
    alignItems: 'center',
  },
  buttonText: {
    color: '#FFFFFF',
    fontSize: 16,
    fontWeight: 'bold',
  },
});

export default ScheduleManager;
```

<Callout type="info"> Changes to schedules are automatically synchronized with the server and will affect notification delivery times immediately. </Callout>


# How to configure Delay Step (/platform/workflow/add-and-configure-steps/configure-action-steps/delay)

Learn how to use delay step to pause workflow execution.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

After adding a Delay step to a workflow, it pauses workflow execution for a specified duration or until a scheduled time, then resumes execution with the next step. You can add a Delay step anywhere in a workflow, before or after any other step to control when subsequent steps run.

This page focuses on how to configure the Delay step for your use case.

<Callout>To learn when to use Delay step in a workflow, refer to the [Delay step overview](/platform/workflow/add-and-configure-steps#delay).</Callout>

## Delivery behavior and scheduling

Delay supports delivery-aware execution:

* Notifications sent after a delay can respect a subscriber’s delivery schedule.
* Notifications are delivered using the subscriber’s time zone if a `timezone` attribute is set.
* If no time zone is available, UTC is used.

<Callout type="info">
  Changing the step content after triggering the workflow with delay step will affect the existing pending delayed notification content.
</Callout>

## Adding a delay step

You can add a delay step anywhere in a workflow, before or after any other step. When the workflow reaches the delay step, execution pauses for the configured duration and then resumes with the next step.

## Delay types

Delay types are used to define how long the workflow execution should be delayed before proceeding. These delay types are:

### Fixed delay

A fixed delay pauses workflow execution for a static duration. Use this when the delay length is known in advance and does not change.

You can specify fixed delays in seconds, minutes, hours, days, weeks, or months.

![Fixed delay example](/images/workflows/add-and-configure-steps/action-steps/delay/fixed-delay.gif)

### Scheduled delay

A scheduled delay pauses workflow execution until a specific date and time, based on the subscriber’s time zone.

You can configure scheduled delays to resume execution:

* **Minute**: Resume at a specific minute.
* **Hour**: Resume at a specific hour and minute.
* **Day**: Resume at a specific time of day.
* **Week**: Resume on specific days of the week at a given time.
* **Month**: Resume on specific days of the month at a given time.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/S5vdsvJDNxA" title="Learn how to use Scheduled delay in Novu workflow" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen />

In the example above, the scheduled delay pauses workflow execution until the current day at either 10:00 AM or 11:00 AM, at 23, 24, or 25 minutes past the hour, based on the subscriber’s time zone.

### Dynamic delay

A dynamic delay, also called a variable-based delay, determines the delay duration using a variable from the event payload. This allows the delay to change per workflow execution.

The variable can be defined in one of the following formats:

* **ISO-8601 timestamp**: Example: `2027-01-01T12:00:00Z`. This value should be for future date and time.
* **Duration object**: Example: `{ "amount": 30, "unit": "minutes" }`. This value should be for future date and time. Here *amount* is the number of units to delay and *unit* is the time unit. *unit* can be **seconds**, **minutes**, **hours**, **days**, **weeks**, or **months**.

![Dynamic delay example](/images/workflows/add-and-configure-steps/action-steps/delay/dynamic-delay.png)

In this example, the `delayTill` variable is used to pause the workflow until the future date and time specified in the `delayTill` variable.

<Tabs items={['ISO Date', "Duration object"]}>
  <Tab value="ISO Date">
    ```json
    {
      "delayTill": "2027-01-01T12:00:00Z"
    }
    ```
  </Tab>

  <Tab value="Duration object">
    ```json
    {
      "delayTill": {
        "amount": 30,
        "unit": "minutes"
      }
    }
    ```
  </Tab>
</Tabs>

If a dynamic delay using an ISO date is added as the first step in a workflow, it effectively schedules the workflow execution to start at the specified time.

## Extend to subscriber’s schedule

When enabled, delayed execution respects the [subscriber’s delivery schedule](/platform/inbox/features/schedule).

If the delay completes outside the subscriber’s available delivery window, execution resumes during the next available time slot. This option is disabled by default.

## FAQs

### If delay step fails, will the workflow continue to the next step?

No, workflow execution will stop immediately if the delay step fails due to an error. Common errors are:

* Invalid ISO date format.
* Invalid duration object format.
* Past datetime is specified.


# How to configure Digest Step (/platform/workflow/add-and-configure-steps/configure-action-steps/digest)

Batch multiple workflow trigger events into a single execution using configurable digest windows and grouping rules.

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

After adding a Digest step to a workflow, Novu batches multiple trigger events and executes downstream steps only once per digest window, instead of once per event.

This page focuses on how to configure the Digest step to fit your use case.

<Callout>To learn when to use the Digest step in a workflow, refer to the [Digest step overview](/platform/workflow/add-and-configure-steps#digest).</Callout>

![Configure digest](/images/workflows/add-and-configure-steps/action-steps/digest/configure-digest.gif)

## Group events by

By default, Digest groups events by `subscriberId`, ensuring that each subscriber receives their own digest.

You can optionally add one additional aggregation key to further group events within a subscriber’s digest. This gives you finer control over how events are batched.

The aggregation key must come from the event payload defined in your [payload schema](/platform/workflow/configure-workflow#payload-schema). For example, if multiple users like different posts, you may want each subscriber to receive separate digests per post by grouping on `payload.postId`.

## Digest window

The Digest window defines how long events are collected before the workflow continues. You can configure the digest window as **Regular** or **Scheduled**.

### Regular digest

This allows you to set the amount of time to digest events for. Once the defined time has elapsed, the digested events are sent.

![Regular digest](/images/workflows/add-and-configure-steps/action-steps/digest/regular-digest.gif)

#### Control digest duration

You can configure the digest duration from the **Digest events for** field:

* Seconds
* Minutes
* Hours
* Days
* Weeks
* Months

<Callout type="info"> Maximum digest duration varies based on your plan. For more information, refer to the [limits](/platform/developer/limits) documentation.</Callout>

#### Control when to start digest

You can also control when digesting begins by selecting any of the following options from the **Start digest** field:

* **Immediately**: Start collecting events as soon as the first event arrives.

* **When events repeat**: Check whether a similar notification was sent recently.
  * If yes, start a digest.
  * If not, deliver the notification immediately and skip digesting.

**Available presets:**

* When events repeat within 5 minutes.
* When events repeat within 30 minutes.
* Custom.

This behavior is useful when you want the first notification delivered instantly, while batching subsequent events that occur close together.

### Scheduled digest

A scheduled digest collects events and delivers them at fixed calendar intervals instead of relative durations.

You can schedule delivery:

* Every minute
* Every hour
* Daily
* Weekly
* Monthly

![Scheduled digest](/images/workflows/add-and-configure-steps/action-steps/digest/scheduled-digest.png)

<Callout type="info">
  Scheduled digests are delivered in the subscriber’s time zone.
</Callout>

## Extend to subscriber’s schedule

When enabled, digest delivery respects the subscriber’s delivery schedule.

If the digest window ends outside the subscriber’s available hours, the notification is delayed until the next available time slot. This option is disabled by default.

## FAQs

<Accordions type="multiple">
  <Accordion title="If scheduled digest is set for 9:00 AM daily then will the digest be sent at 9:00 AM every day without any event triggered?">
    Yes, if scheduled digest is set for 9:00 AM daily then the digest will be sent at 9:00 AM every day without any event triggered.
  </Accordion>

  <Accordion title="What is the difference between Regular and Scheduled Digest set to 1 Hour?">
    Both digests are the same in this case.
  </Accordion>

  <Accordion title="If digest step fails, will the workflow continue to the next step?">
    No, workflow execution will stop immediately if the digest step fails due to an error.
  </Accordion>
</Accordions>


# How to configure HTTP Step (/platform/workflow/add-and-configure-steps/configure-action-steps/http-step)

Learn how to use HTTP step to make external HTTP requests.

The HTTP step is an Action step that allows workflows to call external APIs during execution. This provides a native way to interact with systems outside Novu directly from your workflows. It is useful for tasks such as enriching data, enabling conditional branching based on external responses, or communicating with internal delivery systems.

This guide explains how to add and configure an HTTP step for your specific needs.

<Callout type="info">
  This feature is currently in public beta, please contact us at [support@novu.co](mailto:support@novu.co) to enable it for your organization.
</Callout>

## Adding an HTTP step

You can add an HTTP step anywhere within a workflow. When workflow execution reaches this step, the workflow will perform the configured request and the response can be used by steps that follow.

![Injecting workflow context](/images/workflows/add-and-configure-steps/action-steps/http-step/add-http-step.gif)

## Configuring the request

You can configure the HTTP request using the following properties:

* **Method**: Select the standard HTTP method such as `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
* **URL**: Provide the destination endpoint for the request. A placeholder URL is included by default to help you test the behavior quickly.
* **Headers**: Define any required HTTP headers. These can be input as key-value pairs.
* **Body**: Provide the request payload. As with headers, you can use key-value pairs.
* **Response Schema**: Define the response schema for the API response. It is similar to defining the payload schema for the workflow. Response schema validation can also be enforced at the HTTP step level.

### Injecting workflow context

The HTTP step supports LiquidJS across all configuration fields, including the `URL`, `Headers`, and `Body`. This allows you to dynamically inject variables from the workflow context into your API request. You can use data from the subscriber, the event payload, or results from previous steps.

![Injecting workflow context](/images/workflows/add-and-configure-steps/action-steps/http-step/configuring-the-request.gif)

## Testing the HTTP request

You can test your configured HTTP request directly from the step editor without running a full workflow. This helps you verify the configuration and observe the API behavior.

Test executions performed in the step editor do not create workflow activity logs. Any validation or preview errors are surfaced directly on the step preview pane so you can resolve them before finalizing the configuration.

![Testing the HTTP request](/images/workflows/add-and-configure-steps/action-steps/http-step/testing-endpoint.gif)

## Consuming the API response

When the HTTP request succeeds, the API response is stored in the step results. You can access these results in subsequent steps or condition rules using the `{{steps.step_id.responseFieldName}}` variable.

When consuming these response values in the channel step editors or in step conditions, you will see available response fields in variable autocomplete.

The example below determines whether to send an email using the `shouldSendEmail` field from the HTTP response in the email step condition. It uses the `{{steps.http-request-step.shouldSendEmail}}` variable, where `http-request-step` is the step id and `shouldSendEmail` is the response field name.

![Consuming the API response](/images/workflows/add-and-configure-steps/action-steps/http-step/using-response-in-step-conditions.gif)

Similarly, you can use the response fields in the email step content to personalize the email content.

## Error handling and failure behavior

The HTTP step treats the following scenarios as failures:

* Non-2xx HTTP response status codes.
* Network timeouts.
* Network errors.

You can control what happens when a step fails. The workflow can be configured to either **continue** or **stop** execution if the HTTP request encounters an error.

![Continuing or stopping workflow execution](/images/workflows/add-and-configure-steps/action-steps/http-step/continue-on-failure.png)

## Securing HTTP requests

With each API request, novu send `novu-signature` header. This header is a HMAC signature of the request body and the timestamp. You can verify the authenticity of the request by verifying the HMAC signature. Below example shows how to verify the HMAC signature in a Next.js API route. Here, Novu secret key is used to generate the HMAC signature. You can copy the secret key from the [Novu API Keys](https://dashboard.novu.co/api-keys) page.

```typescript title="api/novu-http-step-request/route.ts"
import { NextRequest, NextResponse } from "next/server";
import { createHmac, timingSafeEqual } from "node:crypto";

const novuSecretKey = process.env.NOVU_SECRET_KEY as string;

export async function POST(req: NextRequest) {
  const headers = Object.fromEntries(req.headers.entries());
  let body = {};
  try {
    body = await req.json();
  } catch {
    // GET requests usually don't have a body
  }

  const parts = headers["novu-signature"].split(",");
  const timestampPart = parts.find((p) => p.startsWith("t="));
  const signaturePart = parts.find((p) => p.startsWith("v1="));

  const timestamp = Number(timestampPart?.split("=")[1]);
  const providedSignature = signaturePart?.split("=")[1];


  // Verify the timestamp is not stale
  const currentTimestampTime = Date.now();
  const fiveMinutes = 5 * 60 * 1000;
  const providedTimestamp = timestamp;
  // If the timestamp is stale, return a 401 error
  if (currentTimestampTime - providedTimestamp > fiveMinutes) {
    return NextResponse.json({ error: "stale request" }, { status: 401 });
  }

  const generatedSignature = createHmac("sha256", novuSecretKey)
    .update(`${timestamp}.${JSON.stringify(body)}`)
    .digest("hex");

  // Verify the signature
  const providedBuf = Buffer.from(providedSignature, "hex");
  const generatedBuf = Buffer.from(generatedSignature, "hex");
  const valid =
    providedBuf.length === generatedBuf.length &&
    timingSafeEqual(generatedBuf, providedBuf);

  // If the signature is not valid, return a 401 error
  if (!valid) {
    return NextResponse.json({ error: "Not authorized" }, { status: 401 });
  }

  return NextResponse.json({ message: "Authorized" }, { status: 200 });
}
```

## Use cases

The HTTP step can be utilized in several ways within your workflows:

### Data enrichment during workflow runs

You might need additional subscriber or event data before sending a notification. An HTTP step can call your internal CRM or user database to fetch extra context, which can then be injected into the notification content using the step results namespace.

### Conditional branching based on external systems

You can use the HTTP step to check a condition in an external service. For example, you can query an API to determine if a user has an active premium subscription, and then use the response in a subsequent condition step to send a different type of notification based on their status.

### Internal delivery systems

If you have an internal system that requires a payload when certain events happen, you can trigger an HTTP step to ping that system with the relevant workflow context without needing to expose it to end users.


# How to configure Throttle Step (/platform/workflow/add-and-configure-steps/configure-action-steps/throttle)

Learn how to use the Throttle step in Novu workflows to control notification frequency.

After adding a Throttle step to a workflow, it limits the number of times a workflow is allowed to continue within a specified time window b. Once the execution limit is reached, the workflow stops at the Throttle step and downstream steps are skipped.

This page focuses on how to configure the Throttle step.

<Callout>To learn when to use the Throttle step in a workflow, refer to the [Throttle step overview](/platform/workflow/add-and-configure-steps#throttle).</Callout>

![Throttle panel](/images/workflows/add-and-configure-steps/action-steps/throttle/throttle-panel.png)

## Throttle window

The Throttle window defines the time period in which executions are counted. Within this window, only the specified number of executions are allowed.

In the Throttle step properties panel, you will find the options to set your Throttle Window. You can choose between the fixed or dynamic window.

![Throttle window](/images/workflows/add-and-configure-steps/action-steps/throttle/throttle-window.gif)

### Fixed window

In fixed window, the time frame is predefined in the workflow editor from the **Throttle for** field. You can set a fixed duration of the time window. The time can be set in minutes, hours, or days. The minimum duration is one minute.

You can use this mode when the time window for throttling is constant and known in advance.

### Dynamic window

In dynamic window, the time frame is determined by data sent in the trigger payload. In the **Dynamic window key** field you need to specify the key in the trigger payload that contains the dynamic window configuration. For example, `payload.throttleUntil` or `payload.customWindow`.

The value for the dynamic window key can be provided in one of two formats:

* **ISO-8601 Timestamp (string)**:
  This format throttles executions until a specific future date and time. Any new triggers before this timestamp will be evaluated against the throttle limit.

  ```json
  {
    "throttleUntil": "2025-10-31T23:59:59Z"
  }
  ```
* **Duration object**: This format throttles executions for a duration relative to the time of the first trigger. It follows the same structure as the fixed window configuration.

  ```json
  {
    "customWindow": { "amount": 30, "unit": "minutes" }
  }
  ```

Use this mode when the throttle duration or end time needs to be flexible and defined at the time of the trigger. For example, throttle billing alerts until the end of the current billing cycle.

## Execution threshold

You can define the maximum number of workflow executions allowed within the specified time window in the **Execution threshold** field. This defaults to 1. This applies to both fixed and dynamic throttle window.

## Group throttling

By default, all throttling is grouped by the `subscriberId`. The **Group throttling by** field allows you to add a second aggregation key based on a variable from your trigger `payload`. This is useful for creating more throttling rules.

For example, if you want to send a notification for each project a user belongs to, but no more than once a week per project. You can set **Throttle for** to 7 days and **Group throttling by** to `payload.projectId`. This ensures the user receives one alert for Project A and one for Project B within the same week, instead of just one alert total.


# Personalize workflows and templates in Novu using context (/platform/workflow/advanced-features/contexts/contexts-in-workflows)

Use contexts in Novu to personalize notification templates, control workflow logic, and customize the Inbox component.

Contexts let you personalize how notifications are rendered and delivered by making contextual data available inside template editors, step conditions, and the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> component.

## How to use context

Once a context is created either through the Novu dashboard or API, its data becomes available for use in your templates editors, step conditions, and for customizing the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> component.

### Using context data in the template editor

Use the `{{context}}` Handlebars helper to access context data in any template editor. The context key you provide while creating the context (for example, tenant, region) becomes the accessor.

For example, if a context with this data is created:

```json
{
  "context": {
    "tenant": {
      "id": "acme-corp",
      "data": {
        "name": "Acme Corporation",
        "plan": "enterprise"
      } 
    }
  }
}
```

You can access the `name` and `plan` in your in-app, email, SMS, or push template like this:

```html
<p>Welcome, new user from {{context.tenant.data.name}}!</p>
<p>Your account is on the {{context.tenant.data.plan}} plan.</p>
```

Or

```text
Welcome, new user from {{context.tenant.data.name}}!
Your account is on the {{context.tenant.data.plan}} plan.
```

![Using context data in the template editor](/images/workflows/contexts/context.gif)

<Callout>Refer to the Inbox documentation, to learn how to use context in the <Method href="/platform/inbox/configuration/inbox-with-context">{`<Inbox />`}</Method> component. </Callout>

### Using context in step conditions

You can use context variables in the **Step conditions** tab of a workflow step to add conditional logic to your notifications. For example, only send a "Feature X is now enabled" email if `context.tenant.data.plan` is `enterprise`.
![Context step conditions](/images/workflows/context-step-conditions.png)

To learn how contexts are structured or how to define them, refer to the [Managing Contexts](/platform/workflow/advanced-features/contexts/manage-contexts) documentation.

## Viewing and debugging contexts

Once you start using contexts in your workflows, Novu provides full observability so you can monitor and debug your context usage after a workflow has been triggered.

### Searching for workflow runs

You can filter your workflow runs to find all executions associated with a specific context.

1. Navigate to the **Activity Feed** in your Novu dashboard.
2. Select the **Workflow Runs** tab.
3. In the search bar, click **Context** and enter the context `type` and `id` using the format `type:id`.

![Searching for workflow runs](/images/workflows/search-context-activityfeed.png)

### Verifying the resolved context

To confirm that Novu received and processed your context data correctly, you can inspect the API traces for a specific run.

1. From the **Activity Feed**, select the relevant workflow run from the list in the **Requests** tab.
2. In the workflow run details, go to the **API Traces** tab.

Here, you will see the full context object that was resolved and attached to that specific workflow execution.

![Verifying the resolved context](/images/workflows/resolved-context.png)


# Workflow Context (/platform/workflow/advanced-features/contexts)

Learn what Contexts are in Novu, how they differ from payloads, and how they help you organize and personalize notifications across workflows.

*Contexts* are flexible, user-defined data objects that help you organize and personalize your notifications. They let you attach metadata, such as tenant, region, or app details, and enable contextual behavior to workflows, notifications, and other entities across Novu.

![Contexts](/images/inbox/Contexts.png)

In simple terms, a context acts like an extended version of the payload. While the payload exists only for the duration of a single workflow execution, contexts are persistent and can be reused across multiple workflows or API calls. This makes them ideal for multi-tenant environments, dynamic branding, and use cases where notifications depend on shared or reusable data.

## How context works

Context solves the common problem of sending differentiated notifications to the same subscriber without creating duplicate subscriber records or complex workarounds.

For example, if you have a single subscriber entity, `john@acme.com`, who uses two different applications you offer: "Notion Email" and "Notion Calendar". You want to send notifications specific to each application.

Without context, you might have to create two different subscribers or use workarounds with subscriber ID prefixes to differentiate the notifications.

```javascript
// Problem: How does Novu know which app is sending the notification?

// Notion Email notification
await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'john@acme.com' },
  payload: { title: 'You have 1 new email' }
});

// Notion Calendar notification  
await novu.trigger({  
  workflowId: "workflowId",
  to: 'john@acme.com',
  payload: { title: 'You have a new meeting invite' }
});
```

However, with context, you can provide this metadata directly in the trigger. This allows you to use a single workflow and subscriber entity, while dynamically changing content or logic based on the context.

```javascript
// Solution: Pass an 'app' context to differentiate triggers.

// Notion Email notification
await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'john@acme.com' },
  payload: { title: 'You have 1 new email' },
  context: {
    app: 'notion-email',
    branding: {
      logo: "url_for_email_logo.png"
    }
  }
});

// Notion Calendar notification  
await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'john@acme.com' },
  payload: { title: 'You have a new meeting invite' },
  context: {
    app: 'notion-calendar',
    branding: {
      logo: "url_for_calendar_logo.png"
    }
  }
});
```

Here are some ways that you can use contexts:

* **Multi-tenancy and app routing**: Use a tenant or app context to dynamically alter notification content, branding, or logic for different customers or applications from a single workflow.
* **A/B testing**: Pass a campaign identifier in a context (for example, campaign: 'new-welcome-email-v2'). Use this in a condition step to split users into different notification paths and measure which performs better.
* **Data residency and compliance**: Use a region context to tag notifications with their origin. This can help in applying data retention policies or filtering data for compliance audits.


# How to manage contexts in Novu (/platform/workflow/advanced-features/contexts/manage-contexts)

Learn how to create, update, and delete contexts in Novu using the dashboard, or API.

Novu lets you manage contexts through the Novu dashboard, or the Novu API. This lets you create, view, update, and delete context entities to suit your application's needs.

<Callout type="warn">You can pass a maximum of five contexts per workflow trigger and the serialized `data` object for each context is limited to 64KB.</Callout>

## Context object schema

When defining contexts, Novu supports multiple formats per key-value pair that let you store and reference metadata relevant to your workflows and templates.

Each context consists of:

* A `type` (for example, tenant, app, or region).
* An `id` that uniquely identifies the specific context instance.
* An optional `data` object that holds additional properties available to your templates.

Supported data formats include:

```typescript
await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'user123' },
  payload: { userName: 'John' },
  context: {
    // Simple string format
    tenant: 'acme-corp', 
    
    // Rich object format (ID only)
    app: { id: 'jira' },                    
    
    // Rich object format (ID + data)
    region: {                               
      id: 'us-east',
      data: {
        name: 'US East',
        timezone: 'America/New_York',
        currency: 'USD'
      }
    }
  }
});
```

## Create a Context

You can create a new context via the Novu dashboard or API when you want to register reusable metadata. After creation, this context becomes available to all workflows and templates within your environment.

### Create a context via dashboard

Use the dashboard to manually define contexts that represent key business entities.

1. Log in to the Novu dashboard
2. Click **Contexts** on the sidebar.
3. Click **Create context**.
   ![create context](/images/workflows/contexts/create-context.png)
4. Complete the following fields:
   * **Identifier**: A unique identifier within that type (for example, acme-corp).
   * **Context type**: A category such as tenant, app, or region.
   * **Custom data (JSON)**: An optional JSON object that contains metadata, such as branding, plan, or region details.
5. Click **Create context** to save the context.
   ![create context](/images/workflows/contexts/create-contexts.png)

### Create a context via API

Novu provides an API to create a context. If a context with the same `type:id` combination already exists, then the request will fail.

```bash
POST /v2/contexts
{
  "type": "tenant",
  "id": "acme-corp",
  "data": {
    "name": "Acme Corporation",
    "plan": "enterprise"
  }
}
```

### Create a context via API (Just-in-time)

Contexts can also be created automatically when you trigger a workflow that includes a new context object. If the specified `type:id` doesn’t exist, then Novu automatically creates it before running the workflow.

```jsx
await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: 'user@example.com' },
  payload: { userName: 'John' },
  context: {
    tenant: 'acme-corp',   // Created automatically if it doesn’t exist
    app: 'jira'
  }
});
```

If a matching context already exists, Novu reuses it as-is without modifying any stored data. This behavior ensures consistency and avoids accidental changes to shared metadata.

## Update a context

You can update a context’s data payload at any time. The context `type` and `id` remain immutable. However, to change an existing context’s data, you must explicitly update it through the dashboard or API.

#### Update a context via dashboard

1. Log in to the Novu dashboard.
2. Click **Contexts** on the sidebar.
3. Click on the context you wish to edit from the context list on the Context page.
4. Modify its data object in the UI.
5. Click **Save changes**.

### Update a context via API

Novu provides an API to update an existing context. The `data` object is replaced entirely during updates (not merged). Include all fields you want to retain.

```bash
PATCH /v2/contexts/tenant/acme-corp
{
  "data": {
    "plan": "premium",
    "region": "us-east"
  }
}
```

## Retrieve a single context

You can retrieve a context to verify its data, confirm its creation, or inspect the metadata it holds.

### Retrieve a context via dashboard

1. Log in to the Novu dashboard
2. Click **Contexts** on the sidebar to view the list of all existing contexts.
3. Click any context entry to see its details.

### Retrieve a context via API

Novu provides an API to retrieve a single, specific context by providing its `type` and `id` in the URL.

```bash
GET /v2/contexts/:type/:id
```

Here is an example:

```bash
GET /v2/contexts/tenant/acme-corp
```

## List or search for contexts

You can list all contexts in your environment or search for specific ones by context type or ID.

### List or search for contexts via dashboard

1. Log in to the Novu dashboard
2. Click **Contexts** on the sidebar to view all contexts.
3. Use the search bar to filter by context type or ID.

### List or search for contexts via API

Novu provides an API that lists or searches available contexts. Use pagination and search parameters to retrieve subsets efficiently.

```bash
GET /v2/contexts
GET /v2/contexts?search=acme
```

## Delete a context

Delete a context if it’s no longer needed. This action permanently removes the context from your Novu environment.

<Callout type="warn"> Deleting a context cannot be undone. Ensure the context is no longer required by any active or historical workflows you might need to analyze. </Callout>

### Delete a context via dashboard

1. Log in to the Novu dashboard.
2. Click **Contexts** on the sidebar.
3. Click the context or the **...** icon on the row you want to remove.
4. A confirmation menu will appear.
   ![Delete](/images/workflows/contexts/delete.png)
5. Select **Delete context** to confirm removal.
   ![Delete context](/images/workflows/contexts/delete-context.png)

### Delete a context via API

Novu provides an API that you can use to delete a context. Once deleted, the context will no longer be available for use in new workflow executions.

```bash
DELETE /v2/contexts/:type/:id
```

Here is an example:

```bash
DELETE /v2/contexts/tenant/acme-corp
```


# Mailgun Email Activity Tracking Setup (/platform/integrations/email/activity-tracking/manual-configuration/mailgun)

A step-by-step guide to manually add specific event webhooks in Mailgun for Novu activity tracking.

By default, Mailgun API keys have the required permissions for Novu to auto-configure webhooks when email activity tracking is enabled in the Novu dashboard. In most cases, you won’t need to do any manual setup. However, you might want to track specific Mailgun events the Novu supports.

This guide explains how to manually add new webhooks for specific events directly from your Mailgun dashboard.

## Step 1: Get your webhook URL from Novu

First, you need the unique webhook URL from your Novu dashboard that will receive events from Mailgun.

1. Log in to the Novu dashboard.

2. Navigate to the **Integration Store** page in Novu and then select your **Mailgun** integration.

3. Enable the **Email Activity Tracking** toggle.
   This generates an Inbound Webhook URL unique to your integration.

4. Copy the URL, you’ll use it in the Mailgun dashboard if you want to add specific events manually.
   ![Mailgun Inbound Webhook URL](/images/channels-and-providers/email/activity-tracking/mailgun.png)

## Step 2: Add an event webhook in Mailgun

Next, log in to your Mailgun account to create a new webhook for the specific event you want to track.

1. Log in to your Mailgun account.
2. Navigate to **Send** section in the left sidebar, and then select **Webhooks**.
3. Click **Add webhook**.
   ![Add Mailgun webhook](/images/channels-and-providers/email/activity-tracking/add-mailgun-webhook.png)
4. A menu will appear. Configure the webhook with the following settings:
   * **Event type:** Select the event you want to track from the dropdown menu.
   * **URL:** Paste the **Inbound Webhook URL** you copied from Novu.
5. Click **Create Webhook**.
   ![Create Mailgun Webhook](/images/channels-and-providers/email/activity-tracking/create-mailgun-webhook.png)

## Step 3: Add additional events (Optional)

Your new webhook for the selected event is now active. To track other events, you must repeat the process in **Step 2** for each one. We recommend adding webhooks for all events that Novu supports:

* Delivered messages
* Opens
* Clicks
* Unsubscribes
* Spam complaints
* Permanent failures

Once configured, Mailgun will begin sending real-time data for these events to Novu, which you can monitor in your **Activity Feed**.


# Resend Email Activity Tracking Setup (/platform/integrations/email/activity-tracking/manual-configuration/resend)

A step-by-step guide to manually configure Resend event webhooks for Novu activity tracking.

Resend does not currently support auto-configuration of webhooks through their API. To track events in Novu, you’ll need to set up the webhook manually in your Resend dashboard.

## Step 1: Get your webhook URL from Novu

First, you need the unique webhook URL from your Novu dashboard that will receive events from Resend.

1. Navigate to the **Integration Store** page in Novu and select your **Resend** integration.
2. Enable the **Email Activity Tracking** toggle.
3. A unique Inbound Webhook URL will be displayed. Click the **copy** icon to copy it.
   ![Copy Webhook URL from Novu](/images/channels-and-providers/email/activity-tracking/inbound-webhook-resend.png)

## Step 2: Create the webhook in Resend

Next, log in to your Resend dashboard to create the webhook.

1. From the sidebar menu of your Resend dashboard, click on **Webhooks**.
2. On the webhooks page, click **Add webhook**.
   ![Add webhook](/images/channels-and-providers/email/activity-tracking/resend-webhook.png)
3. In the menu that appears, configure the following:
   * **Endpoint URL:** Paste the **Inbound Webhook URL** you copied from Novu.
   * **Events to send:** Select **Email** to subscribe to all email events.
     ![Add webhook](/images/channels-and-providers/email/activity-tracking/add-webhook-resend.png)
4. Click **Add** to create the webhook.

Your Resend account will now forward email events to Novu, where they will appear in the Activity Feed and the execution details in the event logs.

## Step 3: Add the signing secret (Recommended)

For a more secure and authenticated connection, you should add the webhook's signing secret back into Novu. This step is optional but highly recommended.

1. After creating the webhook in Resend, you will get **Signing Secret**. Copy this secret.
   ![Signing secret](/images/channels-and-providers/email/activity-tracking/signing-secret-resend.png)
2. Return to your Resend integration settings in Novu.
3. Under the **Email Activity Tracking** section, paste the secret into the **Inbound Webhook Signing Key** field.
   ![Inbound Signing Key](/images/channels-and-providers/email/activity-tracking/inbound-signing-key-resend.png)
4. Click **Save Changes**.


# SendGrid Email Activity Tracking Setup (/platform/integrations/email/activity-tracking/manual-configuration/sendgrid)

A step-by-step guide to manually configure SendGrid event webhooks for Novu activity tracking.

If the API key used in your Novu SendGrid integration does not have the required permissions, the automatic setup will fail with an `access forbidden` error. This indicates that Novu lacks the permissions needed to configure the webhook on your behalf.

This guide will walk you through resolving this issue.

## Step 1: Update SendGrid API key permissions

First, you need to update your API key in your SendGrid account to grant the necessary permissions.

1. Log in to your SendGrid account.
2. Under **Settings**, click **API Keys**.
3. Choose whether to edit an existing key or create a new one:
   * To create a new API key, click **Create API Key**.
   * To update an existing key, click the settings icon next to it and select **Edit API Key**.
     ![Edit existing key or creating a new one](/images/channels-and-providers/email/activity-tracking/sendgrid-api.png)
4. Set the key permissions to either:
   * **Full Access**, or
   * Custom Access with at least the following enabled:
     * **Mail Send**
     * **Mail Settings**
       ![Custom access](/images/channels-and-providers/email/activity-tracking/custom-access.png)
5. If you created a new key, return to the Novu dashboard and update your SendGrid integration settings with the new API key.

## Step 2: Enable activity tracking in Novu

Once your API key has the correct permissions, return to your Novu dashboard to complete the setup.

1. Navigate to the **Integrations** page and select your **SendGrid** integration.
2. Click the **Email Activity Tracking** toggle to enable it.

With the updated permissions, Novu should now successfully auto-configure the webhook for you. You should see a green checkmark indicating that the webhook is active. If you see this, your setup is complete.

![Enable activity tracking in Novu](/images/channels-and-providers/email/activity-tracking/enable-activity-tracking.gif)

## Step 3: Manual configuration (only if auto-configuration fails)

If the automatic configuration fails for any reason, or if you prefer to set it up manually, follow these steps.

### Part 1: Configure the webhook in SendGrid

1. In your Novu SendGrid integration settings, enable the **Email Activity Tracking** toggle to reveal the **Inbound Webhook URL**
2. Copy the this Inbound Webhook URL.
3. Log in to the SendGrid dashboard.
4. Go to the Settings page, and click **Mail Settings**.
5. Click on **Event Webhook**.
6. Click **Create new webhook**
   ![Create new SendGrid webhook](/images/channels-and-providers/email/activity-tracking/sendgrid-webhook.png)
7. Give the webhook a friendly name.
8. Paste the Inbound Webhook URL copied from Novu into the **Post URL** field.
9. Under **Actions to be posted**, select the events Novu supports that you want to track
   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/add-new-event-webhook.png)
10. Under Singnature Verification, enable **Enable Signed Event Webhook**
11. Click **Save**

### Part 2: Add the signing key to Novu (Recommended)

For enhanced security, you should add a signing key to verify that webhooks are coming from SendGrid.

1. Log in to the SendGrid dashboard.
2. Go to the Settings page, and click **Mail Settings**.
3. Click the settings icon next to the webhhok a menu will appear.
4. Click **Edit**.
   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/edit-sendgrid-webhook.png)
5. Enable **Signed Webhook Verification** if is hasn't been enabled. A **Verification Key** will be displayed.
6. Copy the verification key.
   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/sendgrid-verification-key.png)
7. Return to your Novu SendGrid integration settings.
8. Paste the key you just copied from SendGrid into the **Inbound Webhook Signing Key** field.
   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/inbound-signing-key-sendgrid.png)
9. Click **Save**.

Your SendGrid integration is now manually configured to send activity data to Novu.


# SES Activity Tracking Setup (/platform/integrations/email/activity-tracking/manual-configuration/ses)

A step-by-step guide to manually configure Amazon SES with Novu for email activity tracking.

Amazon SES requires a manual configuration flow to enable Email Activity Tracking in Novu. This process involves creating an IAM user, setting up an SNS topic, subscribing Novu’s webhook, and linking SES configuration sets with the SNS topic.

Setting up Amazon SES for activity tracking is a multi-step process because it requires configuring several AWS services (IAM, SNS, and SES) to work together. This guide provides a complete, step-by-step walkthrough.

## Step 1: Create an IAM User

First, you need to create a dedicated IAM user in AWS that Novu will use to interact with SES.

1. Log in to your AWS Console and navigate to the **IAM** service.
2. In the sidebar under **Access Management**, click **Users**.
   ![Create user](/images/channels-and-providers/email/activity-tracking/ses/create-user.png)
3. Click **Create user**, enter a name for the user, then click **Next**.
   ![Add user details](/images/channels-and-providers/email/activity-tracking/ses/user-details.png)
4. On the permissions page, select **Attach policies directly**.
5. In the search box, find and select the **`AmazonSESFullAccess`** policy. Click **Next**.
   ![Permissions](/images/channels-and-providers/email/activity-tracking/ses/permissions.png)
6. Click **Next**, review the details, then click **Create user**. You will be redirected to the user list, where the new user will appear.
   ![Create user](/images/channels-and-providers/email/activity-tracking/ses/create-user.gif)

## Step 2: Generate access keys

1. Click on the user you just created.
2. On the user’s page, click **Create access key**.
   ![Create access key](/images/channels-and-providers/email/activity-tracking/ses/create-access-key.png)
3. Under **Access key best practices & alternatives**, select **Application running on an AWS compute service** or the right use case for you.
4. Check the confirmation box and click **Next**.
5. Add a description tag, then click **Create access key**.
6. (Optional) On the **Retrieve access keys** page, you will see the **Access key** and **Secret access key** click **Download .csv file**. This file contains these access keys, you'll need in the next step.
7. Click **Done**.
   ![Access keys](/images/channels-and-providers/email/activity-tracking/ses/access-keys.png)

## Step 3: Set up the SES integration in Novu

Now, use the keys you just downloaded to connect your SES account to Novu.

1. In the Novu dashboard, go to the Integration Store.
2. Click **Connect provider** and select **SES**.
3. Under **Delivery Provider Credentials**, open the .csv file you downloaded in [Step 2](/platform/integrations/email/activity-tracking/manual-configuration/ses#step-2-generate-access-keys).
4. Copy the **Access key** into the **Access key ID** field.
5. Copy the **Secret access key** into the **Secret access key** field.
   ![Access keys field](/images/channels-and-providers/email/activity-tracking/ses/ses-integration.png)
6. Fill in the remaining required fields, then click **Create integration**.

## Step 4: Create an SNS Topic

Next, you'll set up an SNS (Simple Notification Service) topic to receive events from SES.

1. In the AWS console, search for SNS (Simple Notification Service), this will open the SNS dashboard.
   ![search for SNS](/images/channels-and-providers/email/activity-tracking/ses/sns.png)
2. In the sidebar, click **Topics**.
   ![Topics](/images/channels-and-providers/email/activity-tracking/ses/create-topic.png)
3. Click **Create topic**
4. Select the **Standard** option.
   ![Create topic](/images/channels-and-providers/email/activity-tracking/ses/sns-standard.png)
5. Enter a topic name, then scroll down and click **Create topic**.

## Step 5: Subscribe Novu’s webhook to the SNS topic

1. On the topic's page, click **Create subscription**.
   ![Create subscription](/images/channels-and-providers/email/activity-tracking/ses/subscription.png)
2. In another browser tab, return to your **SES integration settings in Novu**. Enable the **Email Activity Tracking** toggle.
3. Copy the **Inbound Webhook URL** it provides.
   ![Inbound Webhook URL](/images/channels-and-providers/email/activity-tracking/ses/ses-inbound-webhook.png)
4. Go back to your AWS SNS subscription page.
   * For **Protocol**, select **HTTPS**.
   * For **Endpoint**, paste the **Inbound Webhook URL** you copied from Novu.
     ![AWS SNS subscription page](/images/channels-and-providers/email/activity-tracking/ses/create-subscription.png)
5. Click **Create subscription**
6. In the sidebar, click **Subscriptions** to confirm that the subscription status is “Confirmed.”
   ![Subscription confirmed](/images/channels-and-providers/email/activity-tracking/ses/subscription-confirmed.png)

## Step 6: Create SES Configuration set

Create a Configuration set in SES to tie everything together.

1. In the AWS console, search for SES (Simple Email Service). This opens the Amazon SES dashboard.
2. In the sidebar, under Configuration section, click **Configuration sets**
3. Click **Create set**.
   ![Create set](/images/channels-and-providers/email/activity-tracking/ses/create-set.png)
4. Enter a configuration set name, then click **Create set**.
   ![Set name](/images/channels-and-providers/email/activity-tracking/ses/set-name.png)
5. Copy the **Configuration set name**.
6. Go back to your SES integration settings in Novu.
7. Paste the name into the **Configuration Set Name** field under the **Email Activity Tracking** section.
   ![Set name Novu](/images/channels-and-providers/email/activity-tracking/ses/set-name-novu.png)
8. Click **Save changes**.

## Step 7: Add event destination

1. Return to the Configuration set page in your **AWS SES dashboard** and click on the set you just created.
2. Click the **Event destinations** tab and then **Add event destination**.
   ![Add destination](/images/channels-and-providers/email/activity-tracking/ses/add-destination.png)
3. Select all available **Event types** and click **Next**.
   ![Event types](/images/channels-and-providers/email/activity-tracking/ses/event-types.png)
4. For the destination, select **Amazon SNS topic** and then enter a destination name.
5. Under SNS topic, select the topic you created in [Step 4](/platform/integrations/email/activity-tracking/manual-configuration/ses#step-4-create-an-sns-topic).
   ![SNS topic](/images/channels-and-providers/email/activity-tracking/ses/sns-topic.png)
6. Click **Next**, review the details, and then click **Add destination**.
   ![SNS topic](/images/channels-and-providers/email/activity-tracking/ses/review-destination-details.png)

Your Amazon SES integration is now fully configured for activity tracking. Events will begin appearing in your Novu **Activity Feed** as you send notifications.

## Troubleshooting

### Email address is not verified

If you get "MessageRejected: Email address is not verified" error when you trigger a workflow in Novu. This error means that the sender email address you are trying to use has not been verified in SES.

To fix this:

1. Go to the SES console.
2. In the sidebar, click **Account dashboard**.
   ![Account destination](/images/channels-and-providers/email/activity-tracking/ses/account-dashboard.png)
3. Click **View Get set up page** and follow the steps in the **Get set up page** to verify your email address and sending domain.