file: ./content/docs/api-reference/overview.mdx
# Overview

In this page you can learn about how to work with Novu's API
        
<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}`.


file: ./content/docs/api-reference/rate-limiting.mdx
# 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     | Business | Enterprise | Endpoints                                                      |
| ------------- | ------ | ------- | -------- | ---------- | -------------------------------------------------------------- |
| Events        | 60 RPS | 240 RPS | 600 RPS  | 6K RPS     | Trigger                                                        |
| Configuration | 20 RPS | 80 RPS  | 200 RPS  | 2k RPS     | Subscribers, Topics, Tenants                                   |
| Global        | 30 RPS | 120 RPS | 300 RPS  | 3K RPS     | All other 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.


file: ./content/docs/community/add-a-new-provider.mdx
# 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](/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)


file: ./content/docs/community/changelog.mdx
# 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://roadmap.novu.co/changelog">
    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>


file: ./content/docs/community/code-of-conduct.mdx
# 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](http://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).


file: ./content/docs/community/feature-flags.mdx
# 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>


file: ./content/docs/community/get-involved.mdx
# 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. 🫂


file: ./content/docs/community/overview.mdx
# Community Overview

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/project-differences)

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


file: ./content/docs/community/project-differences.mdx
# Self-Hosted and Novu Cloud

Understand the difference between Self-Hosted and Novu Cloud
        
## Better together

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 Self-Hosted and make them accessible and consumable by all teams and businesses. Most simply, the 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 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 Self-Hosted capabilities.

| CAPABILITY                                         | SELF-HOSTED             | NOVU CLOUD |
| -------------------------------------------------- | ----------------------- | ---------- |
| Activity feed retention                            | Infratructure dependent | ✅          |
| Block-based email editor                           | ✅                       | ✅          |
| Channels supported: Email, In-app, SMS, Chat, Push | ✅                       | ✅          |
| Code-based Framework workflows                     | ✅                       | ✅          |
| Custom  environments                               | ❌                       | ✅          |
| Digest                                             | ✅                       | ✅          |
| GUI-based workflows                                | ✅                       | ✅          |
| Max workflows                                      | Infratructure dependent | Custom     |
| Provider integrations                              | Infratructure dependent | Unlimited  |
| Subscribers                                        | Infratructure dependent | Unlimited  |
| **INBOX**                                          |                         |            |
| Bell component                                     | ✅                       | ✅          |
| Inbox component                                    | ✅                       | ✅          |
| Inbox content component                            | ✅                       | ✅          |
| Notifications component                            | ✅                       | ✅          |
| Remove Novu branding                               | ❌                       | ✅          |
| Snooze                                             | ❌                       | ✅          |
| User preferences component                         | ✅                       | ✅          |
| **ACCOUNT ADMINISTRATION AND SECURITY**            |                         |            |
| Built-In authentication                            | ❌                       | ✅          |
| Custom SAML SSO, OIDC enterprise providers         | ❌                       | ✅          |
| Max team members                                   | 1                       | Custom     |
| Multi-Factor Authentication (MFA)                  | ❌                       | ✅          |
| Role-Based Access Control (RBAC)                   | ❌                       | Q3 2025    |
| Standard SAML authentication (Google, Github)      | ❌                       | ✅          |
| **COMPLIANCE**                                     |                         |            |
| 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


file: ./content/docs/community/roadmap.mdx
# 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>


file: ./content/docs/community/run-in-local-machine.mdx
# Run Novu 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:node** - Runs the `@novu/node` package in watch mode
* **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_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>


file: ./content/docs/framework/chat-channel.mdx
# Chat

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',
  };
});
```


file: ./content/docs/framework/controls.mdx
# 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.
* **[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`


file: ./content/docs/framework/custom.mdx
# Custom Step

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


file: ./content/docs/framework/delay.mdx
# Delay Action

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


file: ./content/docs/framework/digest.mdx
# Digest Action

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


file: ./content/docs/framework/email-channel.mdx
# Email

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',
  };
});
```


file: ./content/docs/framework/endpoint.mdx
# Bridge Endpoint

undefined
        
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>


file: ./content/docs/framework/in-app-channel.mdx
# In-App

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/overview).

```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,
    },
  };
});
```


file: ./content/docs/framework/introduction.mdx
# Overview

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/react/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'],
  }
);
```


file: ./content/docs/framework/overview.mdx
# Introduction

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>


file: ./content/docs/framework/payload.mdx
# Payload

undefined
        
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 { 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:

```tsx
novu.trigger('comment-on-post', {
  to: 'subscriber_id',
  payload: {
    post_id: 1234,
    author_name: 'John Doe',
    comment: 'Looks good!',
  },
});
```


file: ./content/docs/framework/push-channel.mdx
# Push

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',
  };
});
```


file: ./content/docs/framework/skip.mdx
# Skip Function

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 in-app step if the in-app notification has been read
      skip: () => inAppNotification.read === true,
    }
  );
});
```


file: ./content/docs/framework/sms-channel.mdx
# SMS

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',
  };
});
```


file: ./content/docs/framework/studio.mdx
# 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>


file: ./content/docs/framework/tags.mdx
# 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/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.


file: ./content/docs/guides/inngest.mdx
# 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.


file: ./content/docs/guides/overview.mdx
# Overview

undefined
        
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>


file: ./content/docs/guides/triggerdotdev.mdx
# Trigger.dev

Learn how to integrate Novu with Trigger.dev to send notifications from background jobs. This guide covers setting up both services, managing subscribers, triggering notifications, and includes practical examples for AI content generation and video processing workflows.
        
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>


file: ./content/docs/platform/how-novu-works.mdx
# 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/react/components/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/react/components/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.

### 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/react/components/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/overview)

### 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/react/components/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.


file: ./content/docs/platform/overview.mdx
# Overview

undefined
        
import { OverviewPage } from '@/components/pages/overview-page';

<OverviewPage />


file: ./content/docs/platform/what-is-novu.mdx
# 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/react/components/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/overview) 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

<Cards>
  <Card>
    Order confirmations and shipping updates for e-commerce.
  </Card>

  <Card>
    Password reset emails and authentication alerts for SaaS platforms.
  </Card>

  <Card>
    Payment failure or subscription renewal reminders.
  </Card>
</Cards>

### In-app notification feeds

<Cards>
  <Card>
    Show unread notifications directly in the app using Novu’s Inbox component.
  </Card>

  <Card>
    Customize the notification UI with hooks and headless components.
  </Card>

  <Card>
    Deliver updates, such as mentions, comments, or system alerts.
  </Card>
</Cards>

### Digest and summary notifications

<Cards>
  <Card>
    “10 people liked your post” (similar to Facebook).
  </Card>

  <Card>
    A weekly report summarizing account activity.
  </Card>

  <Card>
    A daily task reminder for productivity apps.
  </Card>
</Cards>

### Multi-step notification workflows

<Cards>
  <Card>
    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.
  </Card>

  <Card>
    Delay and schedule notifications using Novu’s workflow automation.
  </Card>
</Cards>

### Multi-channel notification delivery

<Cards>
  <Card>
    Notify VIP customers via SMS while sending regular users an email.
  </Card>

  <Card>
    Route system alerts to Slack or Microsoft Teams for internal teams.
  </Card>

  <Card>
    Let's users to opt-in to specific channels (e.g., receive marketing updates via email but urgent alerts via push notifications).
  </Card>
</Cards>

### Customizable notification management

<Cards>
  <Card>
    Let users enable/disable notification channels (email, SMS, push).
  </Card>

  <Card>
    Offer per-event notification settings (e.g., only notify me when tagged in a comment).
  </Card>

  <Card>
    Manage user preferences with Novu’s built-in preference center.
  </Card>
</Cards>

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


file: ./content/docs/api-reference/events/broadcast-event-to-all.mdx
# Broadcast event to all

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/events/trigger/broadcast","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/events/bulk-trigger-event.mdx
# Bulk trigger event

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/events/trigger/bulk","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/events/cancel-triggered-event.mdx
# Cancel triggered event

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/events/trigger/{transactionId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/events/trigger-event.mdx
# Trigger event

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.
Additional information can be passed according the body interface below.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/events/trigger","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/create-an-integration.mdx
# Create an integration

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/delete-an-integration.mdx
# Delete an integration

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Delete an integration by its unique key identifier **integrationId**.
This action is irreversible.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations/{integrationId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/integration-schema.mdx
# Integration schema

undefined
        
### 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 the integration communicates (e.g., email, SMS).",
  "type": "Channel"
},
"credentials": {
  "description": "The credentials required for the integration to function, including API keys and other sensitive information.",
  "type": "CredentialsDto"
},
"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"
}
}}
/>

### 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"
}
```


file: ./content/docs/api-reference/integrations/integration-schema.model.mdx
# Integration schema

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

\---type-table---
../api-types.ts#Integration
\---end---

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

\---type-table---
../api-types.ts#Credentials
\---end---

### 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"
}
```


file: ./content/docs/api-reference/integrations/list-active-integrations.mdx
# List active integrations

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List all the active integrations created in the organization

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations/active","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/list-all-integrations.mdx
# List all integrations

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List all the channels integrations created in the organization

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/update-an-integration.mdx
# Update an integration

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update an integration by its unique key identifier **integrationId**.
Each provider supports different credentials, check the provider documentation for more details.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations/{integrationId}","method":"put"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/integrations/update-integration-as-primary.mdx
# Update integration as primary

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/integrations/{integrationId}/set-primary","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/messages/delete-a-message.mdx
# Delete a message

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Delete a message entity from the Novu platform by **messageId**.
This action is irreversible. **messageId** is required and of mongodbId type.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/messages/{messageId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/messages/delete-messages-by-transactionid.mdx
# Delete messages by transactionId

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/messages/transaction/{transactionId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/messages/list-all-messages.mdx
# List all messages

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List all messages for the current environment.
This API supports filtering by **channel**, **subscriberId**, and **transactionId**.
This API returns a paginated list of messages.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/messages","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/messages/message-schema.mdx
# Message schema

undefined
        
### 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"
},
"environmentId": {
  "description": "Environment ID where the message is sent",
  "type": "string"
},
"messageTemplateId": {
  "description": "Message template ID",
  "type": "string"
},
"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[]"
},
"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": "MessageResponseDtoPayload"
},
"overrides": {
  "description": "Provider specific overrides used when triggering the notification",
  "type": "MessageResponseDtoOverrides"
}
}}
/>

### 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/overview) 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"
}
}}
/>


file: ./content/docs/api-reference/messages/message-schema.model.mdx
# Message schema

undefined
        
### Message

Message is a single notification that is sent to a subscriber. Each channel step in the workflow generates a message.

\---type-table---
../api-types.ts#Message
\---end---

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

\---type-table---
../api-types.ts#Workflow
\---end---

### Actor

Actor is the user who is skipped from sending the notification when workflow is triggered to a [topic](/platform/concepts/topics).

\---type-table---
../api-types.ts#Actor
\---end---

### MessageCTA

MessageCTA is a call to action that is displayed in the [Inbox](/platform/inbox/overview) message. It can be used to redirect the user to a specific URL when the message is clicked.

\---type-table---
../api-types.ts#MessageCTA
\---end---


file: ./content/docs/api-reference/notifications/list-all-events.mdx
# List all events

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List all notification events (triggered events) for the current environment.
This API supports filtering by **channels**, **templates**, **emails**, **subscriberIds**, **transactionId**, **topicKey**.
Checkout all available filters in the query section.
This API returns event triggers, to list each channel notifications, check messages APIs.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/notifications","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/notifications/notification-event-schema.mdx
# Notification event schema

undefined
        
### 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": "StepTypeEnum[]"
},
"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": "ActivityNotificationResponseDtoPayload"
},
"tags": {
  "description": "Tags associated with the notification",
  "type": "string[]"
},
"controls": {
  "description": "Controls associated with the notification",
  "type": "Controls"
},
"to": {
  "description": "To field for subscriber definition",
  "type": "ActivityNotificationResponseDtoTo"
},
"topics": {
  "description": "Topics of the notification",
  "type": "ActivityTopicDto[]"
}
}}
/>

### 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"
}
```


file: ./content/docs/api-reference/notifications/notification-event-schema.model.mdx
# Notification event schema

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

\---type-table---
../api-types.ts#Notification
\---end---

### Workflow

Workflow contains the details of the workflow that was triggered.

\---type-table---
../api-types.ts#Workflow
\---end---

### 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"
}
```


file: ./content/docs/api-reference/notifications/retrieve-an-event.mdx
# Retrieve an event

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/notifications/{notificationId}","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/bulk-create-subscribers.mdx
# Bulk create subscribers

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Using this endpoint multiple subscribers can be created at once. The bulk API is limited to 500 subscribers per request.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/bulk","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/create-a-subscriber.mdx
# Create a subscriber

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/delete-a-subscriber.mdx
# Delete a subscriber

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Deletes a subscriber entity from the Novu platform along with associated messages, preferences, and topic subscriptions.
**subscriberId** is a required field.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/delete-provider-credentials.mdx
# Delete provider credentials

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials/{providerId}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/retrieve-a-subscriber.mdx
# Retrieve a subscriber

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve a subscriber by its unique key identifier **subscriberId**.
**subscriberId** field is required.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/retrieve-subscriber-notifications.mdx
# Retrieve subscriber notifications

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve subscriber in-app (inbox) notifications by its unique key identifier **subscriberId**.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/notifications/feed","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/retrieve-subscriber-preferences.mdx
# Retrieve subscriber preferences

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve subscriber channel preferences by its unique key identifier **subscriberId**.
This API returns all five channels preferences for all workflows and global preferences.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}/preferences","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/retrieve-subscriber-subscriptions.mdx
# Retrieve subscriber subscriptions

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve subscriber's topic subscriptions by its unique key identifier **subscriberId**.
Checkout all available filters in the query section.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}/subscriptions","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/retrieve-unseen-notifications-count.mdx
# Retrieve unseen notifications count

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve unseen in-app (inbox) notifications count for a subscriber by its unique key identifier **subscriberId**.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/notifications/unseen","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/search-subscribers.mdx
# Search subscribers

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/subscriber-schema.mdx
# Subscriber schema

undefined
        
### 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"
},
"lastName": {
  "description": "The last name of the subscriber.",
  "type": "string"
},
"email": {
  "description": "The email address of the subscriber.",
  "type": "string"
},
"phone": {
  "description": "The phone number of the subscriber.",
  "type": "string"
},
"avatar": {
  "description": "The URL of the subscriber's avatar image.",
  "type": "string"
},
"locale": {
  "description": "The locale setting of the subscriber, indicating their preferred language or region.",
  "type": "string"
},
"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"
},
"lastOnlineAt": {
  "description": "The timestamp indicating when the subscriber was last online, in ISO 8601 format.",
  "type": "string"
},
"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"
},
"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"
}
}}
/>


file: ./content/docs/api-reference/subscribers/subscriber-schema.model.mdx
# Subscriber schema

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

\---type-table---
../api-types.ts#Subscriber
\---end---

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

\---type-table---
../api-types.ts#ChannelSettings
\---end---

### Credentials

Credentials like deviceTokens, webhookUrl, etc for a specific integration. `providerId` could be chat channel providerId or push channel providerId.

\---type-table---
../api-types.ts#Credentials
\---end---


file: ./content/docs/api-reference/subscribers/update-a-subscriber.mdx
# Update a subscriber

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update a subscriber by its unique key identifier **subscriberId**.
**subscriberId** is a required field, rest other fields are optional

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}","method":"patch"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-all-notifications-state.mdx
# Update all notifications state

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update all subscriber in-app (inbox) notifications state such as read, unread, seen or unseen by **subscriberId**.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/mark-all","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-notification-action-status.mdx
# Update notification action status

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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**

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/{messageId}/actions/{type}","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-notifications-state.mdx
# Update notifications state

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/messages/mark-as","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-provider-credentials.mdx
# Update provider credentials

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update credentials for a provider such as slack and push tokens.
**providerId** is required field. This API appends the **deviceTokens** to the existing ones.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials","method":"put"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-subscriber-online-status.mdx
# Update subscriber online status

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update the subscriber online status by its unique key identifier **subscriberId**

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/online-status","method":"patch"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/update-subscriber-preferences.mdx
# Update subscriber preferences

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/subscribers/{subscriberId}/preferences","method":"patch"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/subscribers/upsert-provider-credentials.mdx
# Upsert provider credentials

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update credentials for a provider such as **slack** and **FCM**.
**providerId** is required field. This API replaces the existing deviceTokens with the provided ones.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/subscribers/{subscriberId}/credentials","method":"patch"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/check-topic-subscriber.mdx
# Check topic subscriber

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Check if a subscriber belongs to a certain topic

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v1/topics/{topicKey}/subscribers/{externalSubscriberId}","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/create-a-topic.mdx
# Create a topic

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Creates a new topic if it does not exist, or updates an existing topic if it already exists

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/create-topic-subscriptions.mdx
# Create topic subscriptions

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"post"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/delete-a-topic.mdx
# Delete a topic

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Delete a topic by its unique key identifier **topicKey**.
This action is irreversible and will remove all subscriptions to the topic.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/delete-topic-subscriptions.mdx
# Delete topic subscriptions

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Delete subscriptions for subscriberIds for a topic.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"delete"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/list-all-topics.mdx
# List all topics

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

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.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/list-topic-subscriptions.mdx
# List topic subscriptions

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List all subscriptions of subscribers for a topic.
Checkout all available filters in the query section.

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}/subscriptions","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/retrieve-a-topic.mdx
# Retrieve a topic

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieve a topic by its unique key identifier **topicKey**

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}","method":"get"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/api-reference/topics/topic-schema.mdx
# Topic schema

undefined
        
### 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"
},
"createdAt": {
  "description": "The date and time the subscription was created",
  "type": "string"
},
"topic": {
  "description": "Topic information",
  "type": "TopicResponseDto"
},
"subscriber": {
  "description": "Subscriber information",
  "type": "SubscriberDto"
}
}}
/>

### 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"
},
"lastName": {
  "description": "The last name of the subscriber.",
  "type": "string"
},
"email": {
  "description": "The email address of the subscriber.",
  "type": "string"
},
"phone": {
  "description": "The phone number of the subscriber.",
  "type": "string"
},
"avatar": {
  "description": "The URL of the subscriber's avatar image.",
  "type": "string"
},
"locale": {
  "description": "The locale setting of the subscriber, indicating their preferred language or region.",
  "type": "string"
},
"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"
},
"lastOnlineAt": {
  "description": "The timestamp indicating when the subscriber was last online, in ISO 8601 format.",
  "type": "string"
},
"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"
},
"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"
}
}}
/>


file: ./content/docs/api-reference/topics/topic-schema.model.mdx
# Topic schema

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

\---type-table---
../api-types.ts#Topic
\---end---

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

\---type-table---
../api-types.ts#TopicSubscription
\---end---

### Subscriber

Subscriber is a user who can receive notifications. Read more about subscribers on [subscribers concept page](/platform/concepts/subscribers).

\---type-table---
../api-types.ts#Subscriber
\---end---


file: ./content/docs/api-reference/topics/update-a-topic.mdx
# Update a topic

undefined
        
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Update a topic name by its unique key identifier **topicKey**

<APIPage document={"https://spec.speakeasy.com/novu/novu/json-development-with-code-samples"} operations={[{"path":"/v2/topics/{topicKey}","method":"patch"}]} webhooks={[]} hasHead={false} />


file: ./content/docs/community/self-hosting-novu/data-migrations.mdx
# 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-name.tmah3.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
```


file: ./content/docs/community/self-hosting-novu/deploy-with-docker.mdx
# 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/)
* [Git](https://git-scm.com/downloads)

## Quick Start

### Get the code

Clone the Novu repo and enter the docker directory:

```bash
# Get the code
git clone --depth 1 https://github.com/novuhq/novu

# Go to the docker community folder
cd novu/docker/community

# Copy the example env file
cp .env.example .env
```

### Configure Environment

#### Local Deployment

To run Novu in local machine, default configuration can be used. Start Novu with:

```bash title="novu/docker/community"
docker-compose up

## if above command is not working, use docker compose
docker compose up
```

Now visit [http://localhost:4000](http://localhost:4000/) to start using Novu.

#### 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 -f docker-compose.yml up
```

Access your dashboard at [http://vps-ip-address:4000](http://vps-ip-address:4000/).

## Securing Your Setup

While we provide example secrets for getting started, you should NEVER deploy your Novu setup using the defaults provided.

Update the `.env` file with your own secrets.

### 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/node
```

### Initialize the SDK

Configure the SDK with your self-hosted backend URL:

```typescript
import { Novu } from '@novu/node';

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({ 
  name : '<WORKFLOW_TRIGGER_IDENTIFIER>', 
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  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/node';

const config = {
  backendUrl: '<REPLACE_WITH_SELF_HOSTED_BACKEND_URL>',
};

const novu = new Novu('<API_KEY>', config);

await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  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
```


file: ./content/docs/community/self-hosting-novu/overview.mdx
# Overview

Self-hosting Novu provides full control and flexibility over your notification infrastructure, with specific system requirements for optimal performance across VMs, Redis, MongoDB, and S3 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.

## System requirements overview

### Hosting Novu services on separate VMs

For optimal performance, we recommend hosting Novu's core services across multiple virtual machines (VMs).

* **Novu services:**
  * 3 VMs per service
  * Each VM: 2 vCPUs and 4GB of RAM
* **Redis:**
  * 2 Redis clusters (one dedicated to queues with Append-Only Log (AOL) enabled)
  * Minimum: 8GB RAM per cluster
* **MongoDB:**
  * 1 MongoDB cluster (M20 or higher on MongoDB Atlas)
* **Storage:**
  * 10GB of S3 storage

### Hosting all Novu services on a single VM

If resources are limited or simplicity is a priority, Novu services can be hosted on a single VM.

* **All services:** 36 vCPUs and 64GB of RAM
* **Storage:** 10GB of S3 storage

### Redis requirements

* **Redis Clusters:** 2 (one for queues with AOL enabled)
* **Memory:** 8GB RAM per cluster
* **AOL:** Active Append-Only Log (AOL) for data persistence and to prevent job loss during outages.

### MongoDB requirements

* **MongoDB cluster:** M20 or higher (recommended) on MongoDB Atlas.

### Storage requirements

* **S3 storage:** Minimum 10GB for file storage.

<Callout type="info">
  The above specifications are general recommendations. Adjust them based on your system load, usage
  patterns, and scale of operations.
</Callout>

<Callout type="warn">
  Self-hosting Novu does not support GitHub login. To access your account, please use the email and
  password associated with your Novu account.
</Callout>


file: ./content/docs/community/self-hosting-novu/telemetry.mdx
# 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.


file: ./content/docs/community/self-hosting-novu/v0-to-v2-migration.mdx
# Migrating from v0 Web UI to v2 Dashboard

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 (Not available)

Layout management is not available yet in v2, and we are planning on introducing more reusable components in the future iterations.

### 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/project-differences).

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


file: ./content/docs/framework/content/react-email.mdx
# 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>


file: ./content/docs/framework/content/remix-react-email.mdx
# 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>


file: ./content/docs/framework/content/svelte-email.mdx
# 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>


file: ./content/docs/framework/content/vue-email.mdx
# 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/).


file: ./content/docs/framework/quickstart/express.mdx
# 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](/platform/concepts/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 />


file: ./content/docs/framework/quickstart/h3.mdx
# 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](/platform/concepts/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 other than `4000` port, restart the `npx novu dev` command with the 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 />


file: ./content/docs/framework/quickstart/lambda.mdx
# AWS 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](/platform/concepts/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 />


file: ./content/docs/framework/quickstart/nestjs.mdx
# 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](/platform/concepts/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).


file: ./content/docs/framework/quickstart/nextjs.mdx
# Next.js

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](/platform/concepts/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 />


file: ./content/docs/framework/quickstart/nuxt.mdx
# 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](/platform/concepts/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 />


file: ./content/docs/framework/quickstart/remix.mdx
# 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](/platform/concepts/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 />


file: ./content/docs/framework/quickstart/svelte.mdx
# SvelteKit

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](/platform/concepts/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 />


file: ./content/docs/framework/schema/class-validator.mdx
# 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...


file: ./content/docs/framework/schema/json-schema.mdx
# 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/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/)


file: ./content/docs/framework/schema/zod.mdx
# 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.

## Add Zod to your project

<Steps>
  <Step title="Install Zod Packages">
    ```bash
    npm install zod
    ```
  </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...


file: ./content/docs/framework/deployment/actions.mdx
# GitHub Actions

undefined
        
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
```


file: ./content/docs/framework/deployment/cli.mdx
# CLI

undefined
        
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`


file: ./content/docs/framework/deployment/production.mdx
# Production Deployment Guide

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](/platform/concepts/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.


file: ./content/docs/framework/deployment/syncing.mdx
# Syncing

undefined
        
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>


file: ./content/docs/framework/typescript/client.mdx
# 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,
  ],
});
```


file: ./content/docs/framework/typescript/overview.mdx
# 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>


file: ./content/docs/framework/typescript/workflow.mdx
# 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](/platform/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>


file: ./content/docs/guides/webhooks/clerk.mdx
# 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/overview">
          <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>


file: ./content/docs/guides/webhooks/segment.mdx
# 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.


file: ./content/docs/guides/webhooks/stripe.mdx
# 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: "sucess", 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/overview">
          <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>


file: ./content/docs/platform/account/authentication.mdx
# Authentication

Novu supports advanced user authentication capabilities like OAuth, SSO, MFA and more, providing enterprise customers with a robust, secure, and user-friendly authentication solution.
        
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>


file: ./content/docs/platform/account/billing.mdx
# 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 do I purchase the business or enterprise tier?">
    Business or enterprise tier subscriptions 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>


file: ./content/docs/platform/account/manage-members.mdx
# Manage organization 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/additional-resources/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>


file: ./content/docs/platform/account/roles-and-permissions.mdx
# 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             | 📖         | 📖         | 📖        | 📖        |


file: ./content/docs/platform/account/sso.mdx
# SAML 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).


file: ./content/docs/platform/additional-resources/errors.mdx
# Common 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.


file: ./content/docs/platform/additional-resources/glossary.mdx
# 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.


file: ./content/docs/platform/additional-resources/legacy-documentation.mdx
# v0.x Documentation

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


file: ./content/docs/platform/additional-resources/limits.mdx
# Limits

System limits for Novu
        
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

This document outlines the default limits for workflows and steps within workflows for new accounts. These limits are designed to ensure optimal performance and resource allocation. Users requiring custom limits can contact support for further assistance.

***

## Workflow Limits

**Maximum Number of Workflows**: 100 All accounts are set to a maximum of 100 workflows. This limit ensures efficient resource management and system performance.

## Step Limits

**Maximum Number of Steps per Workflow**: Each new workflow is limited to 20 steps. This safeguard ensures workflows remain manageable and performant.

## Custom Limits

If you need to increase the limits for workflows or steps, you can contact [support](mailto:support@novu.co) to discuss your needs. Custom limits may be granted based on usage requirements and system capacity.

***

## FAQs

<Accordions>
  <Accordion title="What happens if I exceed the default workflow or step limit?">
    Exceeding the default limit may result in restricted functionality or errors. Contact support to request a custom limit.
  </Accordion>

  <Accordion title="Can I increase the step limit for specific workflows only?">
    Yes, custom step limits can be applied to individual workflows upon request.
  </Accordion>

  <Accordion title="Is there a cost associated with custom limits?">
    Custom limits may incur additional costs depending on the resources required. Support will provide details during the approval process.
  </Accordion>
</Accordions>


file: ./content/docs/platform/additional-resources/security.mdx
# Security and Compliance

Common questions about security, compliance, privacy policy, and terms and conditions
        
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

<Accordions>
  <Accordion title="What should I do if I have regulatory or security issues with PII?">
    We regularly work with big companies and are happy to help and support you with guidance, and various compliances including reports to ease your security and legal team. If you have concerns about PII, you can use our OS version, Novu Hybrid-Cloud enterprise plan, or reach out to us at [sales@novu.co](mailto:sales@novu.co), [support@novu.co](mailto:support@novu.co), or Discord.
  </Accordion>

  <Accordion title="I need my data to reside in the EU, can it be done?">
    Yes, as part of our GDPR compliance we have our cloud version available on both EU (Frankfurt), as
    well as US (Virginia).
  </Accordion>

  <Accordion title="Are you GDPR compliant?">
    Yes, you can see the complete compliance report on our [security page](https://trust.novu.co/).
    Novu also decided to take the extra step and provide separate data residency in both the EU and
    the US.
  </Accordion>

  <Accordion title="I created my account in the EU/US, can I switch to the other one?">
    Not exactly, to keep data residency intact we cannot simply copy or move data between data
    warehouses across US and EU. However if you have the need please contact us at [sales@novu.co](mailto:sales@novu.co)
  </Accordion>

  <Accordion title="Are you SOC 2 compliant?">
    Yes, Novu Cloud is SOC 2 Type II compliant, we have made sure to do penetration tests, security
    training, evidence collection, and SDL. You can see live control updated on our [security
    page](https://trust.novu.co/), and ask for our security report as well at [sales@novu.co](mailto:sales@novu.co).
  </Accordion>

  <Accordion title="Are you ISO 27001 compliant?">
    Yes, Novu Cloud is ISO27001 compliant, we have made sure to go through both Stage 1 and Stage 2
    audits, and fully define ISMS requirements. From entirely creating our organization processes,
    defining organization risk assessment policies, and building organization Incident Response &
    Disaster Recovery plans.
  </Accordion>

  <Accordion title="Where is my data stored?">
    Based on the selected solution there are a couple of options. On the OS option based on where you
    choose to store it :) As to the Novu Cloud solution, you can choose the EU (Frankfurt) or the US
    (Virginia). In case you are working on the Novu Hybrid-Cloud solution we will help you deploy your
    data inside your select network.
  </Accordion>

  <Accordion title="For how long user data is stored?">
    By default, data is stored using the following TTL values:

    * Notifications (for 1 month)
    * Jobs (for 1 month)
    * Message (for in-app messages - 12 months, for all other messages - 1 month)
    * Execution details (for 1 month)
    * Subscribers, workflows, feeds, layouts (not deleted automatically, can be deleted by the user at any time)

    If you want to delete any specific data or information, reach out to us at [support@novu.co](mailto:support@novu.co)
  </Accordion>

  <Accordion title="How to report any vulnerability or security issue?">
    We are equally committed to our users and their data's security. We highly appreciate it if someone shares security vulnerabilities with us. Feel free to use the [github issue](https://github.com/novuhq/novu/security/advisories/new) or email us at [security@novu.co](mailto:security@novu.co).
  </Accordion>
</Accordions>


file: ./content/docs/platform/concepts/endpoint.mdx
# Framework Endpoint

Learn how to customize and extend any aspect of the Novu platform using the Framework SDK powered bridge endpoint.
        
Novu was built for endless extensibility. Although not required for majority of your notification usecases, you can customize and extend any aspect of the Novu platform using the Framework SDK powered bridge endpoint.

## Overview

The framework endpoint is a Restful API path that runs on your server and environment and can be used for multiple usecases including:

* Automating workflow creation using GitOps
* Adding custom components to your emails and other channels
* Hydrating resources including subscribers, topics and tenants directly from your database
* Executing custom logic before, during and after a workflow is executed
* Connect to 3rd-party services such as OpenAI, Stripe, Salesforce and more.
* Implement custom delivery providers with internal systems

## How it works

<img src="/images/novu-works.png" alt="How Novu works" className="rounded-lg border" />

### Build phase

When [building new workflows](/platform/workflow/overview), you will be using the [Novu Framework SDK](/framework/typescript/overview) to define the workflows and their steps directly in your IDE. The local workflows can be previewed and tested using our [Local Studio](/framework/studio) companion app.

### Sync phase

A sync is needed once a notification workflow code is created or updated. We offer multiple sync methods including CI/CD integrations and a custom CLI tool.

During a sync, the workflows defined using the Novu Framework SDK will be pushed to our cloud service and will be persisted in our database.
Once synced, you will be able to view the workflows in the workflows Page on the Dashboard. All the controls created using JSON Schema or Zod will be transformed into UI elements that can be modified without changing the source code. Read more about controls [here](/framework/controls).

### Execution phase

Once a workflow is synced, the workflow engine will make API requests to the bridge endpoint to execute individual workflow steps.
After the fan-out is complete, the bridge endpoint will be triggered with the relevant execution context and will respond with the compiled content and metadata needed to deliver the notification.

## Get Started

To get started with the framework endpoint, visit the Getting Started page relevant to your tech-stack:

<Cards>
  <Card title="Next.js" href="/framework/quickstart/nextjs" />

  <Card title="Express.js" href="/framework/quickstart/express" />

  <Card title="Remix" href="/framework/quickstart/remix" />

  <Card title="NestJS" href="/framework/quickstart/nestjs" />

  <Card title="Svelte" href="/framework/quickstart/svelte" />

  <Card title="Nuxt" href="/framework/quickstart/nuxt" />

  <Card title="H3" href="/framework/quickstart/h3" />

  <Card title="Lambda" href="/framework/quickstart/lambda" />
</Cards>

<Callout type="info" className="mt-4">
  The Framework SDK is currently only supported in Typescript for JS based run-times.
</Callout>


file: ./content/docs/platform/concepts/environments.mdx
# Environments

Understanding and managing environments in Novu
        
Novu uses environments to separate your development and production workflows. When you create an account, you'll get two default environments: `Development` and `Production`.

## Development Environment

Use the development environment to test new notification workflows, validate changes before deploying to production, and experiment with different configurations.

## Production Environment

The production environment is your live environment where notifications are sent to real users.

## Custom Environments

<Callout type="info">Custom environments are available in Business and Enterprise plans</Callout>

Create custom environments to match your development workflow:

1. Go to the Environments page in your dashboard
2. Create environments like `Staging` or `QA`
3. Assign unique colors to easily distinguish between environments
4. Sync changes between environments just like with development and production

The sync process works the same way as between development and production environments.

## What's Unique to Each Environment?

Each environment maintains its own separate:

* Subscriber list
* Notification workflows
* Message history
* Activity feed
* Integration settings
* Notification feeds
* Brand assets and settings

## Environment Credentials

Each environment has two unique identifiers:

1. **Application Identifier**

   * Public ID for client-side apps
   * Unique per environment
   * Safe to expose in frontend code

2. **API Secret Key**
   * Used for backend API authentication
   * Keep this secure and never expose publicly
   * Different for each environment

**Best Practice**: Configure these credentials in your application based on the active environment, similar to how you manage other service credentials.

## Promoting Changes to Production

You can move changes from development to production in two ways:

1. Using the Dashboard's sync interface
2. Using the Sync API in your CI/CD pipeline


file: ./content/docs/platform/concepts/integrations.mdx
# 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.

<Callout type="info">Each integration is scoped to a specific [environment](/platform/concepts/environments). You must create and configure separate integrations for each environment (for example, development, staging, production).</Callout>

## Providers vs integrations

A provider is the third-party service (for example, SendGrid for email or Twilio for SMS), and an integration is a configured instance of that provider within Novu.

* One provider can have multiple integrations.
* Each integration has:
  * A unique, editable identifier.
  * An optional name, which is useful when you have multiple integrations from the same provider. Novu uses the `providerId` as the default name. It is recommended to change the default name if you have multiple integrations from the same provider.

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/workflows/trigger-overrides) to modify the default behavior of a message during workflow trigger, such as overriding the notification title or content, using different integration that primary integration. This works alongside integrations to fine-tune delivery behavior. </Callout>

## 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 is used by default whenever a workflow sends a message for that channel .

You can:

* Set or change the primary integration via the dashboard or API.
* Mark an integration as inactive, which means Novu will no longer use it to send messages until it is marked active again.

<Callout type="warning">If no active integration is available for a sms or email channel, Novu cannot send notifications for email and sms channels. The corresponding workflow channel step will fail.</Callout>

## Integration credentials

Each integration requires a set of credentials to authenticate with the third-party provider. Secret credentials, such as API keys or tokens, are encrypted at rest, while non-secret fields, such as the sender name or from address, are stored as plain text.

When setting up an integration, you may need to provide:

* Sender information (for example, from email address, sender name).
* Credentials such as API keys or tokens.
* Optional configuration settings depending on the provider.

Read [documentation](/platform/integrations/overview) for each provider to see the required credentials and configuration settings.

## Integration store

You can manage integrations directly from the [Integration Store](https://dashboard.novu.co/integrations) in the Novu dashboard.

From there, you can:

* Add new integrations by providing credentials and configuration values.
* Set a primary integration per channel.
* Mark integrations as active or inactive as needed.
* Delete an integration, but if it’s currently set as the primary integration, you’ll be prompted to select another active integration to take its place.

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

## Explore the integration API

For implementation details and usage examples, refer to the [Integration API reference](/api-reference/integrations/integration-schema) documentation.


file: ./content/docs/platform/concepts/notifications.mdx
# Notifications

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.


file: ./content/docs/platform/concepts/preferences.mdx
# 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

When creating a new workflow, you can specify default preferences for your subscribers via code or in the Dashboard. These preferences will be used during notification delivery unless the subscriber overrides via the preferences page in `<Inbox/>`.

<img src="/images/preferences/preferences.png" alt="Preferences" className="rounded-lg border" />

## Subscriber channel preferences per workflow

`<Inbox/>` displays the available preferences per workflow, allowing subscribers to modify them for each channel. Critical workflows will be excluded from the list.

<img src="/images/preferences/inbox-workflow-preferences.png" alt="Inbox Workflow Preferences" className="rounded-lg border w-[400px]" />

<Callout type="info">Inbox displays only channels used by the current workflow.</Callout>

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

<img src="/images/preferences/inbox-global-preferences.png" alt="Inbox Global Preferences" className="rounded-lg border w-[400px]" />

## 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 Dashboard. Critical workflow are not displayed in the subscriber preferences page.


file: ./content/docs/platform/concepts/subscribers.mdx
# 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.

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.

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```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",
    });
    ```
  </Tab>
</Tabs>

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

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.

## 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-subscriber" description="Create a new subscriber in Novu" />

  <Card title="Update a subscriber API" href="/api-reference/subscribers/update-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-subscriber-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-subscriber) request payload.


file: ./content/docs/platform/concepts/tenants.mdx
# Multi-tenancy

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: "Acme Corp",
      logo: "https://acme-corp.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)

## FAQ

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

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


file: ./content/docs/platform/concepts/topics.mdx
# Topics

Learn how topics work in Novu and how they help you organize and target groups of subscribers efficiently.
        
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

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 topic key must be unique and cannot be changed after creation; Novu enforces this uniqueness behind the scenes.

Common use cases:

* 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 for delivery and billing.

Topics let you target large groups with a single API call, no 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

This ensures accurate delivery and billing while supporting massive audiences.

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

## Explore the topics API

For implementation details and usage examples, visit the [Topics API reference](/api-reference/topics/topic-schema).

## Frequently asked questions

<Accordions>
  <Accordion title="Do topics override subscriber preferences?">
    No. Topics only define delivery groups. Each subscriber’s individual notification preferences remain intact.
  </Accordion>

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

  <Accordion title="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`).
  </Accordion>

  <Accordion title="Can I reuse the same topic key across environments?">
    Topic keys must be unique within each environment. You can reuse the same key (for example, `feature-release`) in different environments like staging and production.
  </Accordion>

  <Accordion title="What happens if I trigger a workflow to a topic with no subscribers?">
    The workflow are processed, but no notifications are delivered.
  </Accordion>
</Accordions>


file: ./content/docs/platform/concepts/trigger.mdx
# 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` 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/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.


file: ./content/docs/platform/concepts/webhooks.mdx
# Webhooks

Receive notifications when events occur in your Novu account
        
<Callout type="info" title="Beta Feature">
  Webhooks are currently in beta. If you encounter any issues, please reach out to our support team.
</Callout>

## 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** (available): Notifications about workflow creation, updates, and deletions
* **Subscriber Events**  (upcoming): Notifications about subscriber creation, updates, and preference changes
* **Message Events** (upcoming): Notifications about message delivery status changes

Each event includes detailed information about the affected resource and the changes that occurred.

## 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 = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-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.


file: ./content/docs/platform/concepts/workflows.mdx
# Workflows

Learn what workflows are and how they work in Novu.
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

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/overview).
</Callout>

To learn more about building workflows using the workflow editor, filters, and personalizing templates, refer to the [Building Workflows documentation](/platform/workflow/overview).

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


file: ./content/docs/platform/inbox/overview.mdx
# Overview

Learn how to integrate Novu <Inbox />, a pre-built notification center component for real-time in-app notifications in your application.
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { MessageSquare, Palette, Zap } from 'lucide-react';

The Inbox component enables a rich context-aware in-app notifications center directly in your application, and with minimal effort.

Novu provides a pre-built, ready-to-use, and customizable Inbox UI component. It's in React today, and soon will be available in other popular frameworks including Vue, React Native, and full headless.

<img src="/images/inbox/overview@2x.png" alt="Fully functional and customizable React Inbox component" />

## Getting Started

<Cards>
  <Card title="Next.js" href="/platform/quickstart/nextjs" description="Get started with our pre-built UI component in Next.js" />

  <Card title="React" href="/platform/quickstart/react" description="Get started with our pre-built UI component in React" />

  <Card title="Remix" href="/platform/quickstart/remix" description="Get started with our pre-built UI component in Remix" />
</Cards>

## Design Files

To aide 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.


file: ./content/docs/platform/integrations/demo-providers.mdx
# Demo Providers

Learn about the default Novu email and sms providers
        
## Novu Demo Providers

To help you evaluate our services better, Novu provides an email demo provider by default for every account created. After signing up, you can go to the [Integrations store](https://dashboard.novu.co/integrations?utm_campaign=docs-default-providers) on the Novu Dashboard to see this.

<Callout type="info">
  This feature is available only in Novu cloud. This feature will not work in community self hosted
  version and local environment.
</Callout>

## Novu Email Provider

Novu offers a demo email provider that you can use to send emails to yourself during the evaluation period. This provider should not be used in production or staging environments.

### Limits of the Novu Demo Providers

300 emails per organization per month, and those can be only sent to the current logged in user.
To send more than these limits, or to other email addresses, you can configure your own email provider from the Integration store.


file: ./content/docs/platform/integrations/overview.mdx
# Overview

Discover how to integrate Novu with your tech stack including delivery providers, content frameworks, and validation libraries.
        
import { Card, Cards } from 'fumadocs-ui/components/card';

Novu was designed to be integrated with any part of your tech stack. This includes:

* Delivery providers
* Content frameworks
* Validation and schema libraries
* and more!

## Delivery provider integrations

You can find the list of available integrations for each channel:

<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/overview">
    Manage in-app notification center
  </Card>
</Cards>


file: ./content/docs/platform/integrations/trigger-overrides.mdx
# Trigger Overrides

Learn how to customize the behavior of your workflows at trigger time
        
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.

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

### Override structure

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.

#### Step-level provider 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.


file: ./content/docs/platform/novu-for/developers.mdx
# 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/overview)** 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/overview)** for in-app user notification feeds and preference experiences.
* **[Integration with multiple delivery providers](/platform/integrations/overview)**, 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.


file: ./content/docs/platform/novu-for/product.mdx
# 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.


file: ./content/docs/platform/quickstart/angular.mdx
# 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';

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

    [Create a Novu account](https://dashboard-v2.novu.co/auth/sign-up) or [sign in](https://dashboard-v2.novu.co/auth/sign-in) to an existing account.
  </Step>

  <Step>
    ### Create an Angular application

    Create a new Angular app with [angular cli](https://angular.dev/tools/cli) using the command below. Skip this step if you already have an existing project:

    ```bash
    ng new novu-inbox-angular
    ```

    Navigate to the newly created project:

    ```bash
    cd novu-inbox-angular
    ```
  </Step>

  <Step>
    ### Install the required package

    Run the command below to install [Novu Javascript SDK](/platform/sdks/javascript), which provides required component for Inbox UI:

    <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.component.ts` 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."}:

    ```ts title="src/app/app.component.ts"
    import { Component, ViewChild, ElementRef, AfterViewInit } from '@angular/core';
    import { RouterOutlet } from '@angular/router';
    import { NovuUI } from '@novu/js/ui';

    @Component({
      selector: 'app-root',
      standalone: true,
      imports: [RouterOutlet],
      templateUrl: './app.component.html',
      styleUrl: './app.component.css',
    })
    export class AppComponent implements AfterViewInit {
      @ViewChild('novuInbox') novuInbox!: ElementRef<HTMLElement>;
      title = 'inbox-angular';

      ngAfterViewInit() {
        const novu = new NovuUI({
          options: {
            applicationIdentifier: 'YOUR_APPLICATION_IDENTIFIER',
            subscriberId: 'YOUR_SUBSCRIBER_ID',
          },
        });

        novu.mountComponent({
          name: 'Inbox',
          props: {},
          element: this.novuInbox.nativeElement,
        });
      }
    }
    ```

    <div className="text-sm text-gray-500 text-center mt-[-12px]">
      [Sign in](https://dashboard-v2.novu.co/auth/sign-up) to get your own API keys
    </div>

    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.component.html` file:

    ```html title="src/app/app.component.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/overview">
    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>


file: ./content/docs/platform/quickstart/nextjs.mdx
# Next.js

Create an account and learn how to start using Novu notification Inbox in your Next.js application.
        
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

    [Create a Novu account](https://dashboard.novu.co/auth/sign-up) or [sign in](https://dashboard.novu.co/auth/sign-in) to access the Novu dashboard.
  </Step>

  <Step>
    ### Install `@novu/nextjs`

    In your Next.js project, run the following command to install the Novu Inbox 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/react/components/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/overview">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow/overview">
    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>


file: ./content/docs/platform/quickstart/react.mdx
# React

Create an account and learn how to start using Novu Inbox Notification in your application.
        
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';

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

    [Create a Novu account](https://dashboard.novu.co/auth/sign-up) or [sign in](https://dashboard.novu.co/auth/sign-in) to an existing account.
  </Step>

  <Step>
    ### Create a React application

    Create a new React app with [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project) using the command below. Skip this step if you already have an existing project:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm create vite@latest my-app -- --template react-ts
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm create vite my-app --template react-ts
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn create vite my-app --template react-ts
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx create-vite my-app --template react-ts
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Install the required packages

    Run the command below to install [Novu React SDK](/platform/sdks/react), which provides React components for building notification UIs and React Router Dom:

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm install @novu/react react-router-dom
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm add @novu/react react-router-dom
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn add @novu/react react-router-dom
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bun add @novu/react react-router-dom
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Create the Inbox component

    In the `src` directory, create a `components/notification-center.tsx` file and use the <Method href="/platform/inbox/react/components/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."}:

    ```tsx title="src/components/notification-center.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"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```

    <div className="text-sm text-gray-500 text-center mt-[-12px]">
      [Sign in](https://dashboard.novu.co/auth/sign-up) to get your own API keys
    </div>

    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 add the Notification Center

    Now you can set up React Router and add the `NotificationCenter` component to your app layout:

    ```tsx title="src/App.tsx"
    import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
    import { NotificationCenter } from './components/notification-center';

    function Layout({ children }: { children: React.ReactNode }) {
      return (
        <div>
          <nav>
            <NotificationCenter />
          </nav>
          {children}
        </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/overview">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow/overview">
    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>


file: ./content/docs/platform/quickstart/remix.mdx
# Remix

Create an account and learn how to start using Novu notification Inbox in your Remix application.
        
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';

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

    [Create a Novu account](https://dashboard.novu.co/auth/sign-up) or [sign in](https://dashboard.novu.co/auth/sign-in) to an existing account
  </Step>

  <Step>
    ### Create a Remix application

    Create a new Remix app using the command below. Skip this step if you already have an existing project:

    <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’s inbox 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>
  </Step>

  <Step>
    ### Create an Inbox component

    In the `app` directory, create a `components/notification-center.tsx` file and use the <Method href="/platform/inbox/react/components/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."}:

    ```tsx title="app/components/notification-center.tsx"
    import React from 'react';
    import { Inbox } from '@novu/react';
    import { useNavigate } from '@remix-run/react';

    export function NotificationCenter() {
      const navigate = useNavigate();
      
      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```

    <div className="text-sm text-gray-500 text-center mt-[-12px]">
      [Sign in](https://dashboard.novu.co/auth/sign-up) to get your own API keys
    </div>

    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/overview">
    Explore our full-stack UI components libraries for building in-app notifications.
  </Card>

  <Card title="Build Workflow" icon={<Workflow />} href="/platform/workflow/overview">
    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>


file: ./content/docs/platform/quickstart/vue.mdx
# 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';

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

    [Create a Novu account](https://dashboard-v2.novu.co/auth/sign-up) or [sign in](https://dashboard-v2.novu.co/auth/sign-in) to an existing account.
  </Step>

  <Step>
    ### Create a Vue application

    Create a new vue app with create-vue package. Skip this step if you already have an existing project:

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

    Navigate to the newly created project:

    ```bash
    cd novu-inbox-vue
    ```
  </Step>

  <Step>
    ### Install the required package

    Run the command below to install [Novu Javascript SDK](/platform/sdks/javascript), which provides required component for Inbox UI:

    <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."}:

    ```vue title="src/components/NovuInbox.vue"
    <template>
      <!-- 
        This empty div serves as a mounting point for the Novu Inbox.
        We use Vue's ref attribute to get direct access to this DOM element.
      -->
      <div ref="novuInbox"></div>
    </template>

    <script setup lang="ts">
    import { ref, onMounted, onUnmounted } from "vue";
    import { NovuUI } from "@novu/js/ui";

    interface NovuOptions {
      options: {
        applicationIdentifier: string;
        subscriberId: string;
      };
    }

    // Create a reactive reference to hold the DOM element
    const novuInbox = ref<HTMLElement | null>(null);
    // Store the Novu instance for cleanup during unmount
    let novuInstance: NovuUI | null = null;

    onMounted(() => {
      // Ensure our div reference exists before proceeding
      if (!novuInbox.value) {
        console.error("Novu inbox container element not found");
        return;
      }

      try {
        // Initialize the Novu UI instance with required configuration
        const novu = new NovuUI({
          options: {
            applicationIdentifier: 'YOUR_APPLICATION_IDENTIFIER',
            subscriberId: 'YOUR_SUBSCRIBER_ID',
          },
        } as NovuOptions);

        // Mount the Inbox component to our div reference
        // This is where Novu creates and injects its Inbox UI
        novu.mountComponent({
          name: "Inbox",
          props: {},
          element: novuInbox.value, // The actual DOM element where Inbox will be mounted
        });

        // Store the instance for cleanup
        novuInstance = novu;
      } catch (error) {
        console.error("Failed to initialize Novu inbox:", error);
      }
    });

    // Clean up when the component is destroyed
    onUnmounted(() => {
      if (novuInstance && novuInbox.value) {
        try {
          // Properly unmount the Novu component to prevent memory leaks
          novuInstance.unmountComponent(novuInbox.value);
        } catch (error) {
          console.error("Failed to unmount Novu inbox:", error);
        }
      }
    });
    </script>
    ```

    <div className="text-sm text-gray-500 text-center mt-[-12px]">
      [Sign in](https://dashboard-v2.novu.co/auth/sign-up) to get your own API keys
    </div>

    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/overview">
    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>


file: ./content/docs/platform/sdks/overview.mdx
# Overview

Explore Novu's comprehensive collection of server-side and client-side SDKs for seamless notification integration across multiple programming 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>
</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="Java (Community)" icon={<JavaIcon />} color="#dc2626" href="/platform/sdks/server/java">
    Connect your Java app to Novu via the Java 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>

  <Card title=".NET (Community)" icon={<DotnetIcon />} color="#dc2626" href="/platform/sdks/server/dotnet">
    Connect your C#/.NET app to Novu via the .NET 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/react/get-started">
    Official React SDK for Novu's notification center
  </Card>

  <Card title="Headless" icon={<JavascriptIcon />} href="/platform/inbox/headless/get-started">
    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>


file: ./content/docs/platform/workflow/build-a-workflow.mdx
# Build a Workflow

Learn how to build a Novu Workflow
        
<Steps>
  <Step title="Navigate to the workflows tab in the Novu Dashboard">
    This is where you can find and manage your existing workflows.
  </Step>

  <Step title="Click on Create Workflow">
    This will open the initial workflow creation screen.
    Here you define:

    * Name of the workflow
      * This is also referred to as the workflow `Identifier`
    * Tags (optional)
    * Description of the workflow (optional)

    Once you've filled in the required fields, click on **Create Workflow**.
  </Step>

  <Step title="Add a workflow step">
    This is where you can start adding steps to your workflow. The first step will always be the **"Workflow Trigger"**.

    You can add the following steps by clicking on **+** which is the add step icon :

    **Channels**

    * Email
    * In-app
    * Push
      * Web push
      * Mobile push
    * Chat
      * Enterprise messaging platforms (e.g. Slack, Microsoft Teams, etc.)
      * Consumer messaging tools (e.g. WhatsApp, Telegram, Discord, etc.)
    * SMS

    <Callout type="info">
      If a channel step you've added is not configured in your Novu account, you'll see an Error.
    </Callout>

    **Actions**

    * Digest
    * Delay
    * Custom (Coming soon, currently only available in the [Novu Framework](/framework/custom))
  </Step>

  <Step title="Configure a template">
    Each step in the workflow requires a template that defines the notification or message content and payload. The editor enables you to preview the rendered output of your content.

    **Content creation and templates**

    * Each channel step has its own template configuration options, tailored to the limitations and requirements of the specific channel.
    * The editor provides a live preview to show how the final message will appear.
    * You can use system variables for personalization, including:
      * Subscriber variables: firstName, lastName, email, phone, avatar.
      * Actor variables: for details about the event initiator.
      * Step variables: for data specific to the workflow execution.
      * Brand variables: for aligning with your organization's visual identity.
      * Tenant variables: for organization-specific data.

    **Dynamic content**

    * Inject dynamic data into your templates using payload variables.
    * These variables can be utilized in message content, subjects, and sender names for enhanced personalization.

    **Important:** When using dynamic content with payload variables, ensure that the required payload is passed when triggering the workflow.

    <Callout type="warn">
      Once you've finished configuring your template, don't forget to click the `Save step` button to apply your changes.
    </Callout>
  </Step>

  <Step title="Trigger the workflow">
    There are three main ways to trigger a workflow:

    * **Via the Novu Dashboard**\
      This method is ideal for conducting quick tests directly from the Dashboard. It's a simple and convenient way to verify basic functionality.
    * **Using the trigger code snippet**\
      Copy the code snippet and execute it in your local environment or an online sandbox. This approach allows for more thorough testing, enabling you to integrate the trigger with your application logic and live data for a realistic evaluation.
    * **Integrating the trigger in your application**\
      Once all tests are complete, you can implement the trigger method directly in your application. This allows you to test the workflow in a real-world scenario, ensuring it functions seamlessly with your app's actual environment and users.
  </Step>

  <Step title="Promote a workflow to the production environment">
    Novu operates in a multi environment setup, with the currently available environments:

    * **Development**: Acts as a staging and test environment, where your non-technical peers can view and modify controls.
    * **Production**: For triggering workflows to your customers.

    After you've tested your workflow in the **Development** environment, you can promote it to **Production**.

    [Learn more about promoting workflows to production](/framework/deployment/production)
  </Step>
</Steps>

## Manage payload schema

The Payload Schema in Novu allows you to define, manage, and validate the structure of incoming data for each workflow. By creating a schema, you ensure that dynamic payloads sent to workflows are predictable, type-safe, and consistent across environments.

<Callout>Novu’s payload schema is based on the [JSON Schema](https://json-schema.org/) standard.</Callout>

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.

The schema acts as a contract between your systems and Novu, ensuring that every payload sent into your workflow conforms to expected rules. It provides your team with clear visibility into which variables exist, how they’re structured, and what validations are applied.

Payload schemas are especially useful when building complex workflows that rely on dynamic content, reusable blocks, or strict validation requirements.

### Define workflow schema

You can define the expected payload schema in three ways: manually, by importing a JSON sample, or by creating inline variables. When adding or editing a schema property, you can mark it as required.

<Callout>
  If a property is marked as required, then it must be included in the payload when triggering the workflow using `novu.trigger()`.
</Callout>

#### Add Schema properties manually

You can manually define each property in your payload by specifying:

* Property name (It must be a string)
* Property type (string, integer, number, boolean, enum, array, object, null)

Each property you define becomes part of the payload schema, and helps Novu suggest accurate variables when configuring channels steps or digest actions.

#### Import from JSON

If you already have a sample payload, then you can quickly define the schema by importing it as a JSON object. Novu infers property names, types, and structures for you.

#### Create an inline variable

When referencing a variable that doesn’t exist in the schema (for example, `payload.title`) while editing a workflow step, follow these steps:

* Novu will prompt you to create the variable inline.
* Click Insert to add the variable to your schema with a default type of string.
* (Optional) After insertion, edit the variable in the manage schema tab. You can:
  * Changing its type.
  * Marking it as required.
  * Adding validation rules.

### Enforce schema validation

Schema validation is enabled on a per-workflow basis. When active, 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.

This validation is applied at the HTTP trigger level, and prevents invalid data from entering the workflow entirely.

### Schema configuration options

When defining a schema property, the available configuration fields vary depending on the selected type.

#### General fields (for all types)

* Property name
* Property type
* Required property checkbox
* Default value – Optional fallback if no value is provided
* Min length and max length

#### Type-specific configuration

Depending on the selected type, additional configuration options appear:

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


file: ./content/docs/platform/workflow/channel-steps.mdx
# Channel Steps

undefined
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Bell, Mail, MessageSquare, MessagesSquare, Smartphone } from 'lucide-react';

A **channel step** within a workflow is the core building block for creating and delivering notifications to subscribers (End users). Each channel step is linked to a specific notification template and represents a notification to be sent through a single channel type (e.g., email, push, SMS, in-app, etc.).

### Channel Step Execution

When a channel step is executed, Novu performs the following actions:

1. **Evaluates Step Conditions:** Novu checks any conditions defined for the step to determine if it should be executed. This allows for dynamic notification workflows.

2. **Verifies Subscriber's Information:**\
   Novu ensures the subscriber has the required information to receive notifications via this channel.

   For example:

   * For email, the recipient must have a valid email address.
   * For push notifications, the required channel data (device token) must be configured.

3. **Checks Subscriber's Preferences:**\
   Novu respects the recipient's notification preferences, verifying whether they've opted out of receiving notifications from this channel or workflow.

### Rendering and Delivering Notifications

If the step is valid and all conditions are met, Novu renders the associated template for the step and queues the message for delivery. The message is then sent to the selected provider using the credentials configured for the channel.

### Available Channels

<Cards>
  <Card title="Email" icon={<Mail className="h-4 w-4" />} href="/platform/integrations/email" />

  <Card title="In-App" icon={<Bell className="h-4 w-4" />} href="/platform/inbox/overview" />

  <Card title="Push" icon={<Smartphone className="h-4 w-4" />} href="/platform/integrations/push" />

  <Card title="SMS" icon={<MessageSquare className="h-4 w-4" />} href="/platform/integrations/sms" />

  <Card title="Chat" icon={<MessagesSquare className="h-4 w-4" />} href="/platform/integrations/chat" />
</Cards>


file: ./content/docs/platform/workflow/delay.mdx
# Delay

Learn how to use delay steps to control timing and pacing in your notification workflows.
        
The delay action awaits a specified amount of time before moving on to trigger the following steps of the workflow.

## Common use cases

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

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


file: ./content/docs/platform/workflow/digest.mdx
# Digest Engine

Collect Multiple Events to a Single Message with the Digest Engine
        
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

The digest engine collects multiple trigger events, aggregates them into a single message, and delivers that new payload to the next workflow step.
This becomes useful when a user would otherwise receive a large number of notifications, and you want to avoid over-notifying. When you use a Digest action step, Novu automatically batches the incoming trigger events based on the `subscriberId` and an **optional** `digestKey` that can be added to control the digest logic of the events.

## Digest action step

After adding a digest step to a workflow, each node that will be below the digest node will be only triggered once in the specified digest interval.
You can decide to send messages before adding a digest node and they will be triggered in real-time.

<img src="/workflow/media-assets/digest-engine.png" alt="Digest Engine" />

## Digest configuration

### Digest key

If specified, the digest engine will group the events based on the `digestKey` and `subscriberId`, otherwise the digest engine will group the events based only on the subscriberId.

The digest key might come useful when you want a particular subscriber to get events grouped on a custom field. For example when an actor likes the user's post, you might want to digest based on the `post_id` key.

### Time interval

The time interval determines how long the digest engine will wait before sending the message once created. You can specify the amount and the unit that best suits your needs.

In the image below, `5` is the interval amount, and `mins` is the interval unit. Interval units can be `sec(s)`, `min(s)`, `hour(s)`, or `day(s)`.

## Digest strategy types

The strategy which Novu should use to handle the digest step. More details on available strategies below.

Novu allows you to define different digest strategies depending on the actual use-case you are trying to achieve. At this point we allow you to select from 2 strategies:

* Regular
* Look-back
* Scheduled

Let's explore them in detail:

### Regular strategy

In regular strategy, a digest will always be created for the specified window time. Which means that from the first event trigger, if no active digest exists for this subscriber, one will be created and the user will receive the message only when the digest window time is reached.

### Look-back strategy

In the Look-Back strategy, before creating a digest, Novu will check if a message was sent to the user in the Look-back period. If a message was sent, a digest will be created. Otherwise, a message will be sent directly to the user and the digest creation will be skipped.

Look-back digest has two intervals, `digest interval` and `look-back window`. First, it checks if any event is triggered within the past look-back window, only then a digest is created for the digest interval. If not, the event is considered non-digest and workflow execution continues to the next step.

#### Example

Let's set the digest interval as 20 minutes and the look-back interval as 15 minutes.

If we trigger the first event. Since it is the first event and there was no event triggered in the past 15 minutes (look-back interval), this event will send a message immediately (without digest).
Now, if we trigger a second event within 15 minutes range, then a new digest will be created with this second event. From now on, for the next 20 minutes (digest interval), all triggers will be digested, and after 20 minutes, the workflow will carry forward to the next step with digested events as a payload.

### Scheduled digest

<Callout type="info">All digest times are in UTC time</Callout>

Digest incoming events for the specified time. Once that time threshold since the first event has passed, proceed to the next workflow step.

Available timeframes:

* Minutes
* Hours
* Daily
* Weekly

## Consuming digested events

The digest step collects and groups multiple events over time. Once digested, the results can be used directly in your notification templates to create clear and concise summaries, such as daily digests or batch notifications.

Novu provides built-in variables that expose the results of the digest step. These variables can be referenced in your templates to display totals, format summaries, or present grouped event data using LiquidJS filters.

<Callout type="info" title="Note">These variables are automatically exposed in all variable-supporting inputs following a digest step, as the digest payload determines their values.</Callout>

### Digest variables

Digest variables can be used to reference the list of events and their count, making it possible to create dynamic content inside your templates based on the actual events processed during the digest window.

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

You can loop through it to build dynamic message lists, such as comment summaries or blog post digests, and use it with LiquidJS filters.

```
New posts published: {{steps.digest-step.events | toSentence:'payload.title', 2, 'more'}}
```

If two events were collected, the rendered message would be:

```
New posts published: Scaling Node.js Apps, and Designing for Accessibility
```

If three or more events were collected, the rendered message would be:

```
New posts published: Scaling Node.js Apps, and Designing for Accessibility, and more.
```

#### steps.digest-step.eventCount

The `steps.digest-step.eventCount` variable holds the total number of events collected during the digest step window. It is an integer value and can be used directly or passed into LiquidJS filters like pluralize to generate grammatically correct summaries.

```
You have {{steps.digest-step.eventCount | pluralize: "new comment"}}.
```

If one event was collected, then the rendered message would be:

```
You have 1 new comment.
```

If two events were collected, then the rendered message would be:

```
You have 2 new comments.
```

### Digest template variables

Digest template variables are designed to simplify how you represent digested event data in user-facing messages. They wrap digest variables and LiquidJS filters to output preformatted summaries with minimal effort.

#### steps.digest-step.countSummary

The `countSummary` variable returns a sentence fragment summarizing the total number of digested events with correct pluralization.

This variable is built on top of:

* `steps.digest-step.eventCount`
* The LiquidJS pluralize filter

Internally, `countSummary` uses the event count to apply plural logic. To use `countSummary` in the editor, select it from the variables dropdown. This will automatically insert the variable like this:

```
You have {{steps.digest-step.eventCount | pluralize: 'notification'}}
```

For example, if the digest collected five events, then the output would be:

```
You have 5 notifications
```

If only one event was collected:

```
you have 1 notification
```

#### 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 variable is built on top of:

* `steps.digest-step.events`
* The LiquidJS `toSentence` filter

You can configure the `toSentence` filter 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 (for example, 3)
* The suffix to use for remaining items (for example, "others")

Internally, `sentenceSummary` uses the events array to generate the sentence. To use `sentenceSummary` in the editor, select it from the variables dropdown. This automatically inserts the variable as shown:

```
{{steps.digest-step.events | toSentence:'payload.name', 3, 'others'}} replied to your post.
```

If the events contain names "Radek", "Dima", and five more users, then the result would be:

```
Radek, Dima, and 5 others replied to your post.
```

If there are only two events:

```
Radek and Dima replied to your post.
```

These variable allows for dynamic personalization without writing custom iteration logic in your template.

## Email editor digest block

The digest block is available in the email editor when working with workflows that include a digest step. It loops over the events collected by your digest step and displays them in your email content, handling both layout and repetition automatically.

When you add a digest block to your email template:

* It automatically inserts a repeat block that loops over `steps.digest-step.events`, with the maximum number of iterations defaulting to five.
* Inside this loop, you define the structure once (for example, how each comment or notification looks), and it repeats for every event.
* 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.

You don’t need to write any code manually. The Email Editor handles the looping logic for you. Simply drag the digest block into your message and customize the layout visually using the available variables.

<Callout type="info" title="Note">
  The digest Block only appears if your workflow has a preceding digest step. This block will not be shown in the editor without a digest step.
</Callout>

## Frequently Asked Questions

### 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?"

If scheduled digest is sent for 9:00 daily, then novu will collect all events triggered between 9:00 AM today till 9:00 AM tomorrow and send the digest at 9:00 AM tomorrow. This process is repeated daily. If there is no any event triggered between 9:00 AM today and 9:00 AM tomorrow, then no digest will be sent.

### What is the difference between Regular and Scheduled Digest set to 1 Hour?

Both digests are same in this case.

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


file: ./content/docs/platform/workflow/overview.mdx
# Overview

The workflow Editor combines no-code simplicity and code-based flexibility, enabling users to design and manage advanced notification workflows tailored to their needs.
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { ArrowRightIcon } from 'lucide-react';

The workflow Editor is a robust visual tool that empowers both no-code users and developers to design advanced notification workflows. It seamlessly combines the intuitive simplicity of no-code building blocks with the adaptability and precision of code-based customization.

## What is a workflow?

A workflow in Novu is a container for all notification/message logic and templates within your system.

Each workflow:

* Has a unique identifier (key)
* Executes for one subscriber at a time (e.g. end user, recipient, customer, etc.)
* Contains complete notification/message logic and templates
* Supports subscriber preference management
* Can be triggered via API calls, events, or scheduled operations

## Different types of Novu Workflows

### Visual workflow editor (No-Code)

**Best suited for:**

* Straightforward use cases without complex logic
* Building emails using Novu's Email WYSIWYG Editor
* Modifying existing workflows
* Quick prototyping, testing, and iteration
* Collaboration with non-technical stakeholders

### Framework SDK (Code-Based)

**Best suited for:**

* Complex workflow logic implementation
* External API integration
* Custom data transformation
* Advanced routing rules
* Type safe workflow payloads
* Specialized business logic
* Complex conditional branches
* Custom email templates (React Email, Vue Email, MJML etc.)
* Workflow versioning

[Learn more about Novu Framework](/framework/overview)


file: ./content/docs/platform/workflow/step-conditions.mdx
# Step Conditions

Create dynamic notification workflows using rule-based conditions. Control message delivery based on subscriber data, payload information, and workflow outcomes.
        
The Step Condition feature in Novu enables you to define conditional logic for each workflow step (node), ensuring a precise and tailored notification experience. This feature adds flexibility and control by allowing you to determine whether a step should execute based on subscriber data, payload data, or conditions stemming from previous workflow steps.

## What Are Workflow Step Conditions?

When adding a workflow step (node) in Novu, it can either be:

1. **Channel Step**: In-App, Email, SMS, Push, or Chat.
2. **Action Step**: Digest or Delay.

Each step includes the ability to configure **step conditions** that define whether the step is executed. The conditions can combine multiple logical rules using **AND** and **OR** operators.

## Areas for Configuring Step Conditions

### 1. **Subscriber Variables**

Conditions can leverage subscriber-related fields to tailor notifications based on user-specific data. Examples of subscriber variables include:

* `subscriber.firstName`
* `subscriber.lastName`
* `subscriber.email`
* `subscriber.phone`
* `subscriber.avatar`
* `subscriber.locale`
* `subscriber.data`
* `subscriber.subscriberId`
* `subscriber.isOnline`
* `subscriber.lastOnlineAt`

<Callout type="info">
  For instance, you might want to send an SMS only to users whose `subscriber.isOnline` is `false`.
</Callout>

### 2. **Payload Data**

Conditions can also depend on custom payload data passed during the workflow trigger call to the Novu API. 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`

This makes it possible to create dynamic notifications based on context-specific information.

### 3. **Previous Step Conditions**

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**, 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 is especially useful for tailoring follow-up notifications. For instance, send an email only if the In-App notification was not read within 24 hours.

### 4. **Advanced Application State Calculations**

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

This approach allows you to:

* Access your application's database or external services
* Perform complex business logic calculations
* Make API calls to external services
* Execute custom validation rules

The skip step gives you full programmatic control over whether a notification step should be executed, going beyond the built-in condition builder capabilities.

## Query Builder Options

The query builder enables you to construct powerful logical expressions for your step conditions. Supported operators include:

| 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]`       |

## Using Dynamic Data Fields for Comparison

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}}"
    }
  ]
}
```

<img src="/workflow/media-assets/step-conditions.png" alt="Step Conditions" />

In this case, the step will execute only if `payload.foo` is equal to `payload.bar` at runtime.

You can also use subscriber variables in the same way:

```json
{
  "operator": "AND",
  "conditions": [
    {
      "field": "subscriber.firstName",
      "operator": "=",
      "value": "{{payload.firstName}}"
    }
  ]
}
```

<img src="/workflow/media-assets/step-conditions1.png" alt="Step Conditions" />

This enables flexible condition logic based on real-time data comparisons.

## Building Condition Groups

Novu allows you to group multiple conditions using **AND** and **OR** operators to create complex logic. For instance:

* **AND Group**: All conditions in the group must be true for the step to execute.
* **OR Group**: At least one condition in the group must be true.

Condition groups can also be nested for advanced use cases.

Novu's Step Condition feature empowers you to build intelligent and dynamic workflows tailored to your specific use cases. By leveraging subscriber data, payload information, and step outcomes, you can ensure that each notification reaches the right audience at the right time with the appropriate content.


file: ./content/docs/platform/workflow/tags.mdx
# Tags

Learn how to organize and manage notification tags using Novu's visual workflow editor for better user experience and notification management.
        
**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.

For example, you might want to group all security-related notifications together, separate from updates about account activity or promotional offers.

## Why Use Tags?

* **Filtering Notifications**: Tags make it easy to filter and display notifications based on categories.
  For instance, you can create a UI that allows users to view only security or promotional notifications. Learn more about using tags to filter notifications in the [Inbox](/platform/inbox/react/multiple-tabs) section.

Think of it as organizing emails into folders—tags help keep things tidy and manageable for both you and your users.

## How to Add Tags to Notifications

<Steps>
  <Step title="Navigate to Workflows">Navigate to the **"Workflows"** tab</Step>
  <Step title="Create or Edit Workflow">Create a new workflow or edit an existing workflow</Step>

  <Step title="Add Tags">
    One of the fields in the workflow is the **Tags** field. You can add one or more (max. 16) tags
    to a notification
  </Step>
</Steps>

## Best Practices for Using Tags

* **Define Categories Early**: Identify key notification categories for your app, such as security, promotions, or updates.
* **Consistent Naming**: Use clear and consistent tag names to avoid confusion (e.g., prefer security over sec\_alert).
* **Keep It Manageable**: Avoid overloading with too many tags. Focus on meaningful groupings that provide real value.

Tags are a powerful way to streamline your notification system, helping users stay organized and informed while giving you greater control over your app's notification behavior.


file: ./content/docs/platform/workflow/template-editor.mdx
# Template Editor

Learn how to use the Novu notification template editor to design notifications
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { FilterIcon } from 'lucide-react';

Each channel step in a Novu workflow comes with its own notification template. This template defines how notifications appear for a specific channel.

Quality templates are used to create personalized, visually appealing, and effective notifications.

* **Injecting variables from your trigger data into your notification template.**
* **Using Liquid syntax for logic and control flow within templates.**
* **Previewing and testing your notification templates.**

## Personalizing Notifications with Template Variables

To insert a variable into your Novu notification template, use double curly braces: `{{ variable_name }}`.

Novu templates allow you to reference several types of variables:

### Data payload variables

These variables originate from the data payload in your workflow trigger.
For example, if you include `{ "order_id": "12345" }` in your payload, you can reference it in your template as `{{ payload.order_id }}`.

### User properties

You can access user properties (like `firstName` or custom subscriber properties) using `{{ subscriber.* }}`. For instance:

```liquid
Hi {{ subscriber.firstName }},

You've been upgraded to the {{ subscriber.data.plan }} plan.

Thanks,
The Novu Team
```

## Variable Popover

When clicking on a variable in the template editor, a popover will appear. This popover can be used to easily manipulate the variable formatting by applying default values or Liquid Filters.

<img src="/images/variable-popover.png" alt="Variable Popover" />

### Applying Liquid Filters

The variable popover will display a list of suggested Liquid Filters based on the variable type, you can apply one or more filters to the variable and re-order using drag and drop.
Re-ordering filters is useful as the filters are applied in the order they are listed, and the output of each filter is passed to the next one.

### Previewing filters output

With more advanced filter logic, you can preview the output of the filters by clicking on the **Preview** button and pass the variable value to see how the filters will be applied.

### Raw Liquid.js syntax

You can also apply raw Liquid.js syntax to the variable by clicking on the **Raw** button which will reveal the raw Liquid.js content that will be applied to the variable.

## Adding logic with Liquid Filters

Novu supports Liquid filters to add dynamic and conditional content to your notifications. Below are examples of how to use the top 10 Liquid filters in real-world notification templates.

<a href="https://shopify.github.io/liquid/" target="_blank">
  Learn more about the Liquid Templating Language.
</a>

### `capitalize`

Use `capitalize` to ensure proper formatting for user names.

```liquid
Hello {{ subscriber.firstName | capitalize }},
Welcome to Novu! We're excited to have you on board.
```

**Output**:\
`Hello John,  
Welcome to Novu! We're excited to have you on board.`

### `upcase`

Use `upcase` for emphasizing specific information like workspace names.

```liquid
Your workspace {{ payload.workspaceName | upcase }} has been successfully created.
```

**Output**:\
`Your workspace TEAM ALPHA has been successfully created.`

### `downcase`

Use `downcase` for consistent email formatting or usernames.

```liquid
Hi {{ subscriber.email | downcase }},
We've sent a confirmation to your inbox.
```

**Output**:\
`Hi john.doe@example.com,  
We've sent a confirmation to your inbox.`

### `date`

Use `date` to format subscription or event dates.

```liquid
Your subscription will renew on {{ payload.renewalDate | date: "%B %d, %Y" }}.
```

**Output**:\
`Your subscription will renew on December 31, 2024.`

### `truncate`

Use `truncate` to shorten long content like notification messages.

```liquid
New comment on your post: {{ payload.commentText | truncate: 20 }}
Click here to read more.
```

**Output**:\
`New comment on your post: Great work on your...  
Click here to read more.`

### `truncatewords`

Use `truncatewords` to limit the number of words in a preview.

```liquid
{{ subscriber.firstName }}, here's a preview of the article:
{{ payload.articleExcerpt | truncatewords: 5 }}
```

**Output**:\
`John, here's a preview of the article:  
Novu is a flexible and...`

### `replace`

Use `replace` to dynamically update template content.

```liquid
Hi {{ subscriber.firstName }},
Your {{ payload.subscriptionType | replace: "basic", "premium" }} subscription is active.
```

**Output**:\
`Hi John,  
Your premium subscription is active.`

### `split`

Use `split` to parse tags or interests.

```liquid
You have new updates in {{ payload.tags | split: "," | join: ", " }}.
```

**Input**:\
`"announcements,updates,offers"`

**Output**:\
`You have new updates in announcements, updates, offers.`

### `join`

Use `join` to list multiple items in a human-readable way.

```liquid
Hello {{ subscriber.firstName }},
You have the following items pending: {{ payload.tasks | join: ", " }}.
```

**Input**:\
`["Upload documents", "Confirm email", "Schedule meeting"]`

**Output**:\
`Hello John,  
You have the following items pending: Upload documents, Confirm email, Schedule meeting.`

### `default`

Use `default` to provide fallback values.

```liquid
Hi {{ subscriber.nickname | default: subscriber.firstName }},
Your account settings are updated.
```

**Output (when nickname is null)**:\
`Hi John,  
Your account settings are updated.`

<Cards>
  <Card title="Liquid Filters" icon={<FilterIcon className="h-4 w-4" />} href="https://liquidjs.com/filters/overview.html?utm_source=Novu" description="Learn more about 40+ filters supported by LiquidJS" />
</Cards>

## Previewing and testing notification templates

When your notification template is ready, use the **Preview** mode to visualize how your notification will look. You can:

* **Test dynamic payload data:** Provide sample data to see how your template renders with different values.
* **Send test notifications:** Save your template, return to the workflow canvas, and run a test with real trigger data.


file: ./content/docs/framework/typescript/steps/chat.mdx
# 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.


file: ./content/docs/framework/typescript/steps/custom.mdx
# 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.


file: ./content/docs/framework/typescript/steps/delay.mdx
# 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,
  }
);
```


file: ./content/docs/framework/typescript/steps/digest.mdx
# 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>


file: ./content/docs/framework/typescript/steps/email.mdx
# 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.


file: ./content/docs/framework/typescript/steps/inApp.mdx
# In-App

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/react/components#handle-notification-click) 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/react/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.


file: ./content/docs/framework/typescript/steps/index.mdx
# 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.


file: ./content/docs/framework/typescript/steps/push.mdx
# 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.


file: ./content/docs/framework/typescript/steps/sms.mdx
# 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.


file: ./content/docs/platform/inbox/react/headless.mdx
# Headless

Learn how to use the Novu Inbox API to build your own inbox
        
The headless version of Novu’s notification library package provides users with a lightweight solution for integrating notification functionality into their web applications. With just the essential API methods, users can easily incorporate our notification system into any framework or vanilla JavaScript project, without being constrained by our default UI or dependencies. The SDK includes real-time notifications through a WebSocket connection and can be safely used across web browsers.

<Steps>
  <Step>
    ### Install the SDK

    <Tabs groupId="package-manager" persist items={}>
      <Tab value="npm">
        ```bash
        npm i @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>
    ### Initialize the SDK

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

    export const novu = new Novu({
      applicationIdentifier: 'YOUR_APPLICATION_IDENTIFIER',
      subscriberId: 'YOUR_SUBSCRIBER_ID',
    });
    ```
  </Step>

  <Step>
    ### Fetch notifications

    ```tsx
    const response = await novu.notifications.list({
      limit: 30,
    });

    const notifications = response.data.notifications;
    ```
  </Step>

  <Step>
    Display notifications in your UI.
  </Step>
</Steps>

## Realtime Notifications

Events are emitted when notifications are received, and when the unread notificatons count changes. `novu.on()` is used to listen to these events.

```tsx
novu.on("notifications.notification_received", (data) => {
  console.log("new notification =>", data);
});

novu.on("notifications.unread_count_changed", (data) => {
  console.log("new unread notifications count =>", data);
});
```

For the full list of methods available, see the [API Reference](/platform/sdks/javascript).


file: ./content/docs/platform/inbox/react/hooks.mdx
# Hooks

Learn how to build a custom notifications UI using React hooks powered by Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `@novu/react` package offers an interface that enables you to build a custom notifications UI using React hooks that are powered by real-time data from the Novu services.

These hooks are designed for use in both mobile and web applications, offering a flexible approach to building a custom notifications UI tailored to your application's requirements.

## Getting Started

Follow these steps to get started with building your custom inbox UI:

<Steps>
  <Step title="Install the @novu/react package">
    ```bash
    npm install @novu/react 
    ```
  </Step>

  <Step title="Implement the NovuProvider">
    To implement the [NovuProvider](/platform/sdks/react/hooks/novu-provider) component, you need to place it in your application's code at the tree level where you want the hooks to be accessible.

    ```tsx
    import { NovuProvider } from '@novu/react';

    function App() {
      return (
        <NovuProvider
          subscriber="SUBSCRIBER_ID"
          applicationIdentifier="APPLICATION_IDENTIFIER"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```

    <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="Create the custom Inbox UI">
    For example, you can create a custom popover UI with a bell icon that shows the unread notifications count and a list of notifications.

    ```tsx
    const YourCustomInbox = () => {
      return (
        <Popover.Root open={...} onOpenChange={...}>
          <Popover.Trigger>
            <BellButton />
          </Popover.Trigger>
          <Popover.Content>
            <NotificationsList />
          </Popover.Content>
        </Popover.Root>
      );
    };
    ```

    ### Bell Button with Unread Count

    The `BellButton` component fetches the unread notifications count and renders the count value in the indicator:

    ```tsx
    import { useCounts } from '@novu/react';

    function BellButton() {
      const { counts } = useCounts({ filters: [{ read: false }] });
      const unreadCount = counts?.[0].count ?? 0;

      return (
        <button>
          <BellIcon />
          {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
        </button>
      );
    }
    ```

    ### Notifications List

    The `NotificationsList` component retrieves and displays the notifications list with infinite scrolling functionality:

    ```tsx
    import { useNotifications } from '@novu/react';

    function NotificationsList() {
      const {
        notifications,
        error,
        isLoading,
        isFetching,
        refetch,
        fetchMore,
        hasMore,
      } = useNotifications();

      if (isLoading) return <div>Loading...</div>;
      if (error) return <div>Error: {error.message}</div>;

      return (
        <div>
          {notifications.map((notification) => (
            <NotificationItem
              key={notification.id}
              notification={notification}
            />
          ))}
          {hasMore && (
            <button onClick={fetchMore}>Load More</button>
          )}
        </div>
      );
    }
    ```

    #### Notification Item

    The `NotificationItem` component renders each notification item. When any action is performed on the `notification` instance (e.g., "read" button is clicked), the SDK will optimistically update the notification, which will trigger a rerender of the `useNotifications` hook.

    ```tsx
    const NotificationItem = ({ notification }) => {
      return (
        <div>
          {notification.isRead && <span className="dot-indicator" />}
          <h3>{notification.subject}</h3>
          <p>{notification.body}</p>
          <button onClick={() => notification.read()}>Read</button>
          <button onClick={() => notification.archive()}>Archive</button>
        </div>
      );
    };
    ```
  </Step>
</Steps>

Learn more about the Hook interfaces in the [React SDK](/platform/sdks/react/hooks/novu-provider) documentation.


file: ./content/docs/platform/inbox/react/localization.mdx
# Localization

Learn how to localize the pre built Inbox component
        
## Localization Prop

The `localization` prop can be used to change the copywriting of the Inbox to a different language for your users or change the wording to suit your product. See the list of [available keys](https://github.com/novuhq/novu/blob/next/packages/js/src/ui/config/defaultLocalization.ts#L1), or use the fully typed TS auto complete to find the key you need.

```tsx
import { Inbox } from '@novu/react';
 
function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      localization={{
        // Filter dropdown options
        'inbox.filters.dropdownOptions.unread': 'Unread only',
        'inbox.filters.dropdownOptions.default': 'Unread & read',
        'inbox.filters.dropdownOptions.archived': 'Archived',
        
        // Filter labels
        'inbox.filters.labels.unread': 'Unread',
        'inbox.filters.labels.default': 'Inbox',
        'inbox.filters.labels.archived': 'Archived',
        
        // Notifications section
        'notifications.emptyNotice': 'Quiet for now. Check back later.',
        'notifications.actions.readAll': 'Mark all as read',
        'notifications.actions.archiveAll': 'Archive all',
        'notifications.actions.archiveRead': 'Archive read',
        'notifications.newNotifications': ({ notificationCount }: { notificationCount: number }) =>
          `${notificationCount > 99 ? '99+' : notificationCount} new ${
            notificationCount === 1 ? 'notification' : 'notifications'
          }`,
        
        // Individual notification actions
        'notification.actions.read.tooltip': 'Mark as read',
        'notification.actions.unread.tooltip': 'Mark as unread',
        'notification.actions.archive.tooltip': 'Archive',
        'notification.actions.unarchive.tooltip': 'Unarchive',
        
        // Preferences section
        'preferences.title': 'Preferences',
        'preferences.emptyNotice': 'No notification specific preferences yet.',
        'preferences.global': 'Global Preferences',
        'preferences.workflow.disabled.notice':
          'Contact admin to enable subscription management for this critical notification.',
        'preferences.workflow.disabled.tooltip': 'Contact admin to edit',
        
        // Set locale
        locale: 'en-US',
        
        // Dynamic localization for workflow names
        dynamic: {
          // use the workflowId as a key to localize the workflow name
          'comment-on-post': 'Post comments',
        }
      }}
    />
  );
}
```


file: ./content/docs/platform/inbox/react/migration-guide.mdx
# Migration Guide

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 version.
        
<Callout type="info">
  [@novu/react](/platform/sdks/react) Inbox react component and
  [@novu/js](/platform/inbox/headless/get-started) headless package is compatible with
  [@novu/framework](/platform/workflow/overview) based workflows only. With old UI based workflows,
  our old
  [@novu/notification-center](https://v0.x-docs.novu.co/notification-center/client/react/get-started)
  component should be used.
</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` props is replaced by an enchanced and easy to use `appearance` prop to customize the appearance of the notification components. For more information on `appearance` customization visit [here](/platform/inbox/react/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
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;
+ isArchived: boolean;
+ readAt?: string | null;
+ archivedAt?: string | null;
+ avatar?: string;
+ tags?: string[];

createdAt: 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 migrating to `@novu/react`, install the package via npm:

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

## Basic Usage

* Old Implementation

```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;
```

* New 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. Utilize the `Inbox` and `Notifications` components to achieve this functionality.

* Old Implementation

```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;
```

* New 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.

* Old Implementation

```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;
```

* New 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.

* Old Implementation

```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;
```

* New 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.

* Old Implementation

```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;
```

* New 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

Customize the avatar displayed alongside notifications by specifying an avatar `URL` at the workflow definition level using `@novu/framework`.

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

workflow('welcome-notification', async (step) => {
  await step.inApp('inbox', async () => ({
    subject: 'Welcome to Our Service!',
    body: 'We are thrilled to have you onboard.',
    avatar: 'https://example.com/path-to-your-avatar-image.png',
  }));
});
```

## Popover Positioning

For advanced positioning and styling of the notifications popover, integrate third-party popover libraries such as Radix UI.

* Old Implementation

```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;
```

* New 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.

* Old Implementation

```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;
```

* New 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).

* Old Implementation

```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;
```

* New 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/react/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

* Old Implementation

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;
```

* New Implementation with `@novu/react`

1. Define multiple workflows with relevant tags.

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

workflow(
  'security-alerts',
  async (step) => {
    await step.inApp('inbox', async () => ({
      subject: 'Security Alert',
      body: 'A new login attempt was detected.',
    }));
  },
  { tags: ['security'] }
);

workflow(
  'promotional-offers',
  async (step) => {
    await step.inApp('inbox', async () => ({
      subject: 'Exclusive Offer!',
      body: 'Get 50% off on your next purchase.',
    }));
  },
  { tags: ['promotions'] }
);
```

2. Assign relevant tags to each workflow to categorize notifications appropriately.

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

const tabs = [
  { label: 'All Notifications', value: [] },
  { label: 'Security', value: ['security'] },
  { label: 'Promotions', value: ['promotions'] },
];

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APP_ID" subscriber="YOUR_SUBSCRIBER_ID" tabs={tabs} />
  );
}

export default Novu;
```

## Localization

Customize the language and text content of the notification components using the localization prop.

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="YOUR_SUBSCRIBER_ID"
      localization={{
        'inbox.title': 'Notificaciones',
        'notifications.emptyNotice': 'No tienes nuevas notificaciones',
        'notifications.markAllAsRead': 'Marcar todo como leído',
        locale: 'es-ES',
      }}
    />
  );
}

export default Novu;
```

## HMAC Encryption

The process remains the same as before. See the detailed guide [here](/platform/inbox/react/production#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;
```


file: ./content/docs/platform/inbox/react/multiple-tabs.mdx
# Tabs

undefined
        
Novu enables the creation of a multi-tab experience for the Inbox, allowing you to filter and display notification lists within distinct UI tabs.

## Defining tabs

Define the `tabs` prop to display multiple tabs in the Inbox component.

Each tab object should include a `label` and `filter` properties. The `label` property represents the text displayed on the specific tab. The `filter` property is an object that serves as the "filter criteria" for the notifications displayed in the list. The filter should include the `tags` which is an array of strings.

The notifications are filtered and matched by comparing the [workflow](/platform/workflow/overview#tags) `tags` field with the tab `filter.tags` array. Each notification is a part of a specific [workflow](/platform/concepts/workflows). You can combine tags from different workflows to create a customized tab experience.

The example below demonstrates how to define multiple tabs in the Inbox component.

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

const tabs = [
  {
    label: 'All Notifications',
    filter: { tags: [] },
  },
  {
    label: 'Newsletter',
    filter: { tags: ['newsletter'] },
  },
  {
    label: 'React',
    filter: { tags: ['react'] },
  },
];

function InboxNovu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}
```

<Callout type="info">
  Here tab `filter.tags` are taken from workflow tags. Tags can be configured in the
  [workflow](/platform/workflow/tags) editor.
</Callout>


file: ./content/docs/platform/inbox/react/preferences.mdx
# Preferences

Learn how to manage and customize subscriber notification preferences in your React application.
        
By default, Novu will show the subscriber preferences cog icon on the Inbox component.

Users can enable/disable any active channel in the workflow using subscriber preferences or they can update the preference globally for all workflows under the `Global Preferences`.

<img style={{ borderRadius: '0.5rem' }} src="/images/inbox/preferences@2x.png" alt="Preferences" />

### Hide global preferences

Global preferences can be hidden by using following css style in root css file.

```css
.nv-workflowContainer:first-child {
  display: none;
}
```


file: ./content/docs/platform/inbox/react/production.mdx
# Going to production

Learn how to prepare your React notification inbox for production deployment including HMAC encryption and security best practices.
        
## HMAC Encryption

When Novu's user adds the Inbox to their application they are required to pass a `subscriberId` which identifies the user's end-customer, and the application Identifier which is acted as a public key to communicate with the notification feed API.

A malicious actor can access the user feed by accessing the API and passing another `subscriberId` using the public application identifier.

HMAC encryption will make sure that a `subscriberId` is encrypted using the secret API key, and those will prevent malicious actors from impersonating users.

### Enabling HMAC Encryption

In order to enable Hash-Based Message Authentication Codes, you need to visit the admin panel In-App settings page and enable HMAC encryption for your environment.

1. Next step would be to generate an HMAC encrypted subscriberId on your backend:

```tsx
import { createHmac } from 'crypto';

const hmacHash = createHmac('sha256', process.env.NOVU_SECRET_KEY)
  .update(subscriberId)
  .digest('hex');
```

2. Then pass the created HMAC to your client side application forward it to the component:

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

<Inbox
  applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
  subscriber="YOUR_SUBSCRIBER_ID"
  subscriberHash="YOUR_SUBSCRIBER_ID_HASH_VALUE"
/>;
```

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


file: ./content/docs/platform/inbox/react/styling.mdx
# Styling

Learn how to style the pre built Inbox component
        
import { TypeTable } from 'fumadocs-ui/components/type-table';

## Customization Hierarchy

The Inbox component is built to allow for multiple layers of styling, which allows the specificity required to style the Inbox to meet the requirements of your use case.

Depending on the level of customization you need, you can choose to style the inbox using one of the following approaches:

* [Appearance Prop](#appearance-prop)
  * [Variables](#variables) - Global primitives such as buttons, popovers, drop-downs and etc...
  * [Elements](#elements) - Style individual elements
* [Custom notification rendering](#render-notification-component) - Render a custom notification item with complete control
* [Custom Composition](/platform/inbox/react/components/overview#composition) - Compose our components for custom layouts

<Callout type="info">
  You can see Styling in action on the [Inbox Playground](https://inbox.novu.co) with common themes
  like Notion, Reddit and more!
</Callout>

## Appearance Prop

The `appearance` prop can be used to customise the Inbox. It has three main keys: `baseTheme`, `variables` and `elements`.

* **Variables**: Global styling variables that apply to multiple elements within the inbox.
* **Elements**: Elements are the individual UI components that make up the Inbox.
* **Base theme**: This is the base theme applied to the `<Inbox />`. It has the same keys as `appearance`. Used for applying base themes like `dark`.

### Variables

Variables are used to define global styling properties that can be reused throughout the inbox. You might want to use variables to the styling of multiple components at once, for example, if you want to change the border radius of all the components at once, you can do so by updating the `colorPrimary` variable, which will modify the CTA buttons, unseen counter and etc...

<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.',
  },
}}
/>

<img src="/images/inbox/styling_01@2x.png" alt="Appearance Variables" />

#### Styling Variables

You can override the default elements by passing your own styles or CSS classes to the `elements` object.

```tsx
import { Inbox } from '@novu/react';
const appearance = {
  variables: {
    colorBackground: 'yellow',
  },
};

<Inbox appearance={appearance} />;
```

### Elements

The `elements` object allows you to define styles for these components. Each key corresponds to a component, and the value is an object containing `style properties` or you can also pass your `css classes`. Here's a list of available elements that can be styled using the `elements` object in your appearance configuration:

#### Finding element selectors

You can inspect the elements you want to customize using the browser's dev tools, each element has a unique selector that you can use to style starting with `nv-`.

Strip the `nv-` prefix when and add it to the `elements` object. For example, to style the `nv-notificationPrimaryAction__button` element, you can add the following to the `elements` object:

```tsx
const appearance = {
  elements: {
    notificationPrimaryAction__button: {
      backgroundColor: 'red',
    },
  },
};
```

<img src="/images/inbox/styling_02@2x.png" alt="Finding Element Selectors" />

<Callout type="info">
  Any selector that appears before the 🔔 emoji, 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>

### Customizing icons

The `icons` property in the `appearance` prop lets you customize any icon used in the Inbox component. This is useful when you want to:

* Match the bell icon with your host app's navbar icon set.
  – Use your own icon library, such as [react-icons](https://react-icons.github.io/react-icons/) or [Material Icons](https://mui.com/material-ui/material-icons/).

* Modify all icons to fit your application's visual style.

For each icon 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 icon keys

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>

### Dark theme

No need to implement a custom dark theme. Just import our premade `dark` theme and use it via the `baseTheme` option in `appearance`.

```tsx
import { Inbox } from '@novu/react';
import { dark } from '@novu/react/themes';
import { useTheme } from 'next-themes';

export function Novu() {
  const { resolvedTheme } = useTheme();

  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={{ baseTheme: resolvedTheme === 'dark' ? dark : undefined }}
    />
  );
}
```

### Bring your own CSS

You can override the default elements by passing your own styles or CSS classes to the `elements` object.

#### Using Tailwind CSS

You can also use Tailwind CSS classes to style the Inbox components. You can pass the classes directly to the `elements` object.

```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',
  },
};

export function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}
```

#### Using CSS Modules

You can also use `CSS Modules` to style the Inbox components. Here's how you can do it:

* Create a CSS module file `(e.g. styles.module.css)` with the styles you want to apply to the Inbox components.

```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;
}
```

* Import the CSS module file and pass the classes to the elements object.

```tsx
import { Inbox } from '@novu/react';
import styles from './styles.module.css';

const appearance = {
  elements: {
    bellIcon: styles.bellIcon,
    notification: styles.notification,
  },
};

export function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}
```

#### Using Styles Object

You can also use a styles object to style the Inbox components. You can pass the styles directly to the `elements` object.

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

const appearance = {
  elements: {
    bellIcon: {
      padding: '1rem',
      backgroundColor: 'white',
      borderRadius: '50%',
    },
    notification: {
      backgroundColor: 'white',
      borderRadius: '0.5rem',
      boxShadow: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
    },
  },
};

export function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      appearance={appearance}
    />
  );
}
```

#### Render subject and body with bold text

By default, the Inbox notification text for the subject and body is rendered in a normal font weight. To highlight important words or phrases within your notification messages, you can wrap the desired subject or body text in double asterisks (\*\*). Here's an example of how you can do this using the Novu Framework:

```js
await step.inApp('inbox', async () => {
  return {
    subject: '**A new member joined the team!**',
    body: '**John Doe** joined the team! Say hello and help them feel at home',
  };
});
```

<Callout type="info">
  Note: When rendering the custom notification component, you will need to parse the text and apply the bold styling accordingly.
</Callout>

Currently, the Inbox component only support bold text. Other text formatting options will be available in the future. To learn, refer to the [Novu Framework in-app step documentation](/framework/typescript/steps/inApp).

## Render notification component

You can render your own custom notification item component by passing a `renderNotification` prop to the `Inbox` or `Notifications` component. This lets you style and render more complex notification items.

```tsx
import { Inbox } from '@novu/react';
import { CustomNotification } from './CustomNotification';

<Inbox
  renderNotification={(notification) => {
    return <CustomNotification notification={notification} />;
  }}
/>;
```

## The Inbox styles placement

The <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component automatically injects its styles into the `<head>` tag of the HTML document when rendered in the standard DOM.

However, when rendered inside a shadow DOM, it detects the shadow context and injects styles into the shadow root instead. This ensures proper style encapsulation and prevents leakage or conflicts with global styles without any additional configuration.


file: ./content/docs/platform/inbox/react/tabs.mdx
# Tabs

Learn what tabs are and how to filter multiple tabs in the Novu Inbox component.
        
Tabs in the Novu Inbox enable you to organize and display different sets of notifications within distinct UI tabs. This creates a structured, filterable interface for end users to easily navigate their in-app notification feed.

Each tab is defined using the `tabs` prop of the <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component. Every tab object include the following properties:

* **`label`**: A string representing the tab's visible title.
* **`filter`**: An object defining the filter criteria for notifications displayed in that tab.

The `filter` property supports two filtering options:

* **Tags**: Filter based on the `tags` assigned to a workflow in the workflow editor.
* **Data attributes**: Filter based on values in the notification payload (`data`).

![Filtering tabs by tags and data attributes](/images/inbox/filter-tabs-by-tags-and-data-attributes.png)

## Filter tabs by tags

Each notification is associated with a workflow, and workflows can be tagged in the workflow editor. These tags can then be used to group notifications from one or more workflows under a single tab by referencing shared tag names.

To use tags effectively in tab filters, assign clear and descriptive tags to your workflows in the workflow editor. For example, use tags like `promotions` to group marketing messages or `security` to collect alerts related to user safety.

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

export default function InboxWithFilters() {

  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}
    />
  );
}
```

## Filter tabs by data attributes

Each notification can include a `data` payload that contains custom metadata such as priority, category, or activity type. This method is most useful when you want to segment notifications by metadata embedded in the payload rather than by workflow configuration. You can use these [data attributes](/platform/inbox/react/components/inbox#data-object) to group notifications under a single tab by filtering based on specific values in the payload.

To use data attributes effectively in tab filters, make sure your notification payloads are consistently structured and contain clearly defined fields. For example, you might include `priority: "high"` to identify urgent alerts or `type: "login"` to track user sign-ins.

The data `object` supports only scalar values, such as strings, numbers, booleans, or null. String values are limited to 256 characters.

```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}
    />
  );
}
```

## Combining tags and data

You can also combine both tags and data in a single filter to create highly specific tabs tailored to your use case.

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

export default function InboxWithFilters() {

  const tabs = [
    {
      label: 'High Priority',
      filter: { 
        tags: ['alert'], // [\!code highlight]
        data: { priority: 'high' } // [\!code highlight]
      },
    },
  ];
  
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      tabs={tabs}
    />
  );
}
```


file: ./content/docs/platform/integrations/email/adding-email.mdx
# Adding Email Channel

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>


file: ./content/docs/platform/integrations/email/index.mdx
# E-mail

Learn how to configure the Email channel
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

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.

## 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
* **Customizable Templates**: Leverage templates with dynamic placeholders to personalize messages
* **Delivery Insights (Coming Soon)**: Track delivery status, open rates, and more in the Novu dashboard

## Common Use Cases

* **Transactional Emails**: Password resets, account verification, purchase confirmations
* **System Alerts**: Security notifications, system updates
* **Engagement Emails**: Onboarding, reminders, promotional updates

Novu can be used to deliver email messages to your subscribers using a unified delivery API. You can easily integrate your favorite email provider using the built-in integration store.

## Configuring email providers

When creating an email provider integration you will be asked to provide additional fields alongside the provider-specific credentials:

* **Sender name** - Will be displayed as the sender of the message
* **From email address** - Emails sent using Novu will be sent using this address

For some email providers including SendGrid you will have to authenticate the **From email address** to make sure you will send email messages using an authorized address.

## Sending Email Overrides

The overrides field supports an email property. The email overrides field have properties like `to`, `from`, `senderName` etc

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
      to: {
        subscriberId: '<SUBSCRIBER_ID>',
      },
      overrides: {
        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">
  It's very important to know that Novu merges the `to` field in the email overrides with the subscriber email. It DOES NOT REPLACE IT.
</Callout>

## Sending Email attachments

You can easily send attachments with the Novu API by passing the attachments array when triggering an Email based workflow. Attachment file can either be in the `buffer` or `base64` format. There is total limit of 20 mb for all attachments included and email size.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
      to: {
        subscriberId: '<SUBSCRIBER_ID>',
      },
      payload: {
        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>

## Using different email integration

In Novu integration store, multiple email channel type provider integrations can be active at the same time. But only one provider integration can be primary at a time. This primary integration will be used as a provider to deliver the email by default. If you want to use a different active provider integration then you can use the `integrationIdentifier` email overrides field.

If there are 4 active email integrations with these identifiers:

1. sendgrid-abcdef
2. sendgrid-ghijkl
3. brevo-abcdef
4. mailersend-abcdef

Here, if `sendgrid-abcdef` is primary integration and you want to use `brevo-abcdef` with this trigger then you can use `integrationIdentifier` email overrides field as below:

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
      to: {
        subscriberId: '<SUBSCRIBER_ID>',
      },
      overrides: {
        email: {
          integrationIdentifier: "brevo-abcdef"
        },
      },
    });
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Integration identifier is similar to Provider identifier but it is different than Provider Id. It is unique for each integration. You can find the `integrationIdentifier` in the integration store page.
</Callout>

<Callout type="info">
  Looking to integrate an email provider? Check out our [provider integrations](/platform/integrations/email).
</Callout>

```
```


file: ./content/docs/platform/integrations/email/writing-email-template.mdx
# Writing Email Template

Learn how to write an email template in Novu. This document will guide you through the process of creating an email template using the Novu email editor, all supported blocks and how to use them
        
## Email Editor

The Email Editor is a `WYSIWYG` editor that allows you to create and edit email templates. It has two fields: `Subject` and `Body`.

<img src="/images/channels-and-providers/email/writing-email-template/email-editor.png" alt="Email editor" />

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

## Email Editor Blocks

Email editor body is made of blocks. A block can be added by clicking on the plus icon on the top left corner of the editor or by adding a forward slash `/`. In both the cases, a popover will appear with the list of supported blocks. Click on the desired block to add it to the editor. Menu option besides 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 widh 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 (can be customised with text, url, color and size and background color)
* **Hard Break** - Adds a line break
* **Blockquote** - Adds a blockquote
* **Repeat** - Can be used for interation 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

### Repeat Block

`Repeat` block is synonym with the javascript language `for` loop. It can be used to iterate over an array of data and render a block for each item in the array. Use + icon or / to add a `Repeat` block. Checkout the below video on how to use `Repeat` block

<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 above example, if subscriber has `showTracking` field set to `true` in custom `data` attribute, then the `Track your order` button will be shown in the email sent to the subscriber. Similarly, payload variables can be used to conditionally show the content.


file: ./content/docs/platform/integrations/chat/adding-chat.mdx
# Adding Chat Channel

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>


file: ./content/docs/platform/integrations/chat/index.mdx
# Chat

Learn how to configure and use chat providers like Slack, Microsoft Teams, WhatsApp, and Discord with Novu's notification infrastructure.
        
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.

The Chat channel provides:

* **Cross-Platform Integration**: A single system to handle messaging platforms (e.g., Slack, Teams) and apps (e.g., WhatsApp, Telegram, Discord)
* **Scalability at Its Core**: Designed to handle high-frequency messaging without breaking a sweat
* **Effortless Configuration**: Minimal setup, maximum control over your chat notification workflows

## Key Features

* **Platform and App Agnostic**: Supports workplace messaging platforms (Slack, Teams) and consumer apps (Discord, WhatsApp, Telegram) without additional overhead
* **Dynamic Content Handling**: Inject real-time, user-specific data into messages with simple APIs
* **Provider Independence**: Easily switch between chat providers or use multiple simultaneously
* **Delivery Monitoring**: Full visibility into delivery status, failures, and message engagement
* **Fallback Logic**: Automate retries and backup providers to ensure messages are delivered
* **Reusable Message Templates**: Standardize message structure across your channels
* **Developer-Centric APIs**: Clean, intuitive endpoints to plug notifications directly into your backend

## Messaging Platforms vs. Messaging Apps

* **Messaging Platforms** (e.g., Slack, Teams): Ideal for structured, workplace communication. Use these to notify teams or users in collaborative environments
* **Messaging Apps** (e.g., WhatsApp, Telegram, Discord): Best for consumer-facing messaging. Engage users directly through personal or group chats

## Common Use Cases

* **Team Notifications**: Deliver updates to Slack channels or Teams users without needing complex integrations
* **Customer Engagement**: Notify users on apps like Telegram or WhatsApp with real-time updates or alerts
* **System Alerts**: Push critical system or workflow notifications to technical teams via chat platforms
* **Event Reminders**: Send timely reminders for meetings, webinars, or deadlines
* **Community Notifications**: Manage announcements, updates, or discussions in platforms like Discord

## Update credential webhookUrl

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Slack, { webhookUrl: "<WEBHOOK_URL>", });

    ```
  </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>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

<Callout type="info">
  Integration identifier is similar to Provider identifier but it is different than Provider Id. It
  is unique for each integration. You can find the `integrationIdentifier` in the integration store
  page.
</Callout>

## Common errors

Common erros and reason of those errors while sending chat messages using Novu.

* Subscriber does not have a configured channel
  * if the subscriber does not have credentials set up for any of the chat provider
* Webhook URL for the chat channel is missing
  * `webhookUrl` field is null, undefined or not set. Check using [get subscriber api](/api-reference/subscribers/retrieve-a-subscriber)
* Subscriber does not have an active integration
  * if subscriber have credentials set but integration is either not active or deleted for this credential


file: ./content/docs/platform/integrations/push/adding-push.mdx
# Adding Push Channel

Learn how to add the push channel to your application
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Steps>
  <Step title="Add a push channel provider">
    To send push notifications using Novu, you need to set up a provider in the integration store.

    1. Go to the Novu Dashboard and click **"Integrations"** on the left sidebar
    2. Locate your desired push provider and configure it with the required credentials
    3. Ensure the provider is enabled
  </Step>

  <Step title="Set up push channel in a workflow">
    Add push notifications to a new or existing workflow.

    1. Navigate to the **"Workflows"** section in the Novu Dashboard
    2. Click **"Add a Workflow"** or select an existing workflow
    3. Add a step and choose **"Push"** as the channel
    4. Configure the push step by adding static or dynamic content such as title, message body, and variables
  </Step>

  <Step title="Store device tokens in subscriber profiles">
    For push notifications to reach the right subscribers, store provider-specific device tokens or identifiers.

    * Follow your provider's documentation to obtain device tokens
    * Use Novu's subscriber management features to add these tokens to the subscriber profiles
  </Step>

  <Step title="Verify provider configuration">
    Before triggering workflows, ensure your provider configuration is complete.

    * Refer to your push provider's documentation to confirm all required steps are correctly set up
    * Double-check any provider-specific settings in the integration store
  </Step>

  <Step title="Trigger and test push workflow">
    Test the push workflow to ensure everything is working as expected

    1. Go to the **"Workflows"** section in the Novu Dashboard and select your configured workflow
    2. Use the **"Test Workflow"** option
    3. Verify the push notification delivery in Novu Logs or the push provider's dashboard
  </Step>
</Steps>

## Supported providers

* [Firebase Cloud Messaging (FCM)](/platform/integrations/push/fcm)
* [Expo push](/platform/integrations/push/expo-push)
* [Apple push notification Service](/platform/integrations/push/apns)
* [OneSignal](/platform/integrations/push/onesignal)
* [Pushpad](/platform/integrations/push/pushpad)
* [Push webhook](/platform/integrations/push/push-webhook)
* [Pusher Beams](/platform/integrations/push/pusher-beams)

<Callout>Novu supports multiple active providers for push channel.</Callout>


file: ./content/docs/platform/integrations/push/index.mdx
# Push

Learn how to configure the Push channel
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

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.

Novu simplifies the process by offering a unified API that supports multiple push notification providers, enabling reliable and efficient message delivery.

## 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
* **Dynamic Content**: Customize notifications with variables for personalized user experiences
* **Device Management**: Keep subscriber device tokens in sync using just-in-time or manual updates

## Common Use Cases

* **Transactional Notifications**: Payment updates, delivery alerts, appointment reminders
* **Engagement Notifications**: Promotions, re-engagement campaigns, social media interactions
* **System Alerts**: Security warnings, downtime alerts, account activity updates

## How to send push notifications

To send a push notification to subscribers (users) using Novu:

* Add a push channel provider in integration store
* Add push channel as a step in existing or new workflow.
* Add static or dynamic content using variables in push step fields
* Store provider specific device tokens/identifiers in subscriber profile. Read provider specific documentation on how to obtain and store device tokens.
* Make sure all provider specific steps are configured properly before triggering workflow. Read provider related documentation for all required steps.
* Trigger the workflow.

## Supported providers

* [Firebase Cloud Messaging (FCM)](/platform/integrations/push/fcm)
* [Expo Push](/platform/integrations/push/expo-push)
* [Apple Push Notification Service](/platform/integrations/push/apns)
* [OneSignal](/platform/integrations/push/onesignal)
* [Pushpad](/platform/integrations/push/pushpad)
* [Push Webhook](/platform/integrations/push/push-webhook)

<Callout>Novu supports multiple active providers for push channel.</Callout>

## Managing push device tokens

To send push notifications to subscribers, you need to store device tokens or identifiers in subscriber profiles. These tokens are unique identifiers that help push notification providers deliver messages to the correct devices. Each provider has its own method for obtaining and storing device tokens.

Novu offers to ways of keeping your device tokens in sync with subscriber profiles:

* Just-in-time: Pass device tokens in the payload when triggering a workflow. Novu will automatically update subscriber profiles with the new device tokens.
* Manual: Update subscriber profiles with device tokens using the Novu Set Credentials API.

### Just-in-time

When triggering a workflow, you can pass the `channels` array on the subscriber object with the device tokens for the push provider of your choice. Here is an example with fcm:

```typescript
novu.trigger('workflow-id', {
  to: {
    subscriberId: 'subscriber-id',
    channels: [
      {
        providerId: 'fcm',
        credentials: {
          deviceTokens: ['token-1', 'token-2'],
        },
      },
    ],
  },
  payload: {},
});
```

### Manual

Use the Novu Set Credentials API to update subscriber profiles with device tokens. You can read more about the API in the [API Reference](/api-reference/subscribers/update-provider-credentials) or the [FCM Example](/platform/integrations/push/fcm#setting-device-token)

## Frequently Asked Questions

### How to remove one or more device tokens from subscriber credentials?

To remove device token(s) from subscriber credentials, follow this process:

1. Fetch the subscriber details, store all device tokens for the provider in a variable.
2. Remove all device tokens using sdk or api.
3. Filter out the device token(s) you want to remove from the variable.
4. Update the subscriber credentials with new filtered device tokens stored in variable.

As this process requires server side sdk or api, it is recommended to create a separate api for this or handle this while user logs out in backend.

**Example:**

If a user logs in to their device and their device gets registered to their subscriberId, and then this user logs out and a friend logs in, so these device tokens should be removed from user's credentials.

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```ts
    import { Novu, PushProviderIdEnum } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    // fetch subscriber details
    const subscriber = await novu.subscribers.get('subscriberId');

    // get current device tokens from subscriber credentials for the provider
    const currentDeviceTokens = subsciber.data.data.channels.find(
      // \_integrationId can also be checked in place of providerId ;
      (channel) => channel.providerId === PushProviderIdEnum.FCM,
    ).credentials.deviceTokens;

    // remove all device tokens
    await this.novu.subscribers.setCredentials(
      'subscriberId',
      PushProviderIdEnum.FCM, {
        deviceTokens: []
      },
    );

    // remove the particular token
    const newDeviceTokens = currentDeviceTokens.filter(
      (token) => token !== 'token-to-be-removed',
    );

    // update subscriber credentials with new device tokens
    await this.novu.subscribers.setCredentials(
      'subscriberId',
      PushProviderIdEnum.FCM, {
        deviceTokens: newDeviceTokens
      },
    );
    ```
  </Tab>
</Tabs>


file: ./content/docs/platform/integrations/sms/adding-sms.mdx
# Adding SMS Channel

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>


file: ./content/docs/platform/integrations/sms/index.mdx
# SMS

Configure and manage SMS notification providers like Twilio, Nexmo, and others with Novu's notification infrastructure.
        
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.

With the SMS channel, you can:

* **Switch Providers Effortlessly:** Integrate popular services like Twilio, Nexmo, or a custom provider
* **Deliver at Scale:** Handle high-volume messaging with confidence
* **Customize and Track:** Tailor SMS content dynamically and monitor delivery status in real time

## Key Features

* **Dynamic Messaging:** Inject user-specific data into messages for personalization
* **Multi-Provider Support:** Switch or combine providers to maximize reliability
* **Delivery Insights:** Track message delivery, failures, and user engagement
* **Fallback Mechanisms:** Ensure reliable messaging with backup providers
* **Template Management:** Simplify content creation with reusable SMS templates
* **Streamlined API Integration:** Easily connect your backend for automated messaging workflows

## Common Use Cases

* **Transactional Notifications:** Send OTPs, receipts, or order updates instantly
* **Marketing Campaigns:** Deliver promotional offers and updates to your audience
* **Critical Alerts:** Notify users of urgent events, like security breaches or system outages
* **Reminders and Scheduling:** Automate reminders for appointments, events, or deadlines

## Sending SMS overrides

The overrides field supports a `sms` property and `from`, `to`, `content` field overrides. This allows you to send a message to a different recipient, from a different sender, or with a different content.

```javascript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  overrides: {
    sms: {
      to: '+123012345678',
      from: 'Novu Team',
      content: 'This SMS message is from overrides',
    },
  },
});
```

## Using different SMS integration

In Novu integration store, multiple SMS channel type provider integrations can be active at the same time. But only one provider integration can be primary at a time. This primary integration will be used as a provider to deliver the SMS by default. If you want to use a different active provider integration then you can use the `integrationIdentifier` sms overrides field.

If there are 4 active SMS integrations with these identifiers:-

1. twilio-abcdef
2. twilio-ghijkl
3. firetext-abcdef
4. infobip-abcdef

Here, if `twilio-abcdef` is primary integration and you want to use `infobip-abcdef` with this trigger then you can use `integrationIdentifier` sms overrides field as below:-

<Tabs items={['Node.js']}>
  <Tab value="Node.js">
    ```javascript
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', { to: { subscriberId: '<SUBSCRIBER_ID>', }, overrides: { sms: { integrationIdentifier: 'infobip-abcdef', }, }, });

    ```
  </Tab>
</Tabs>

<Callout type="info">
  Integration identifier is similar to Provider identifier but it is different than Provider Id. It is unique for each integration. You can find the `integrationIdentifier` in the integration store page.
</Callout>

## Common errors

Common errors and reason for these errors while sending sms messages using Novu.

1. Subscriber does not have a configured channel.
   * if the `from` field is missing / null / undefined.


file: ./content/docs/platform/sdks/javascript/index.mdx
# @novu/js

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"
},
"subscriberHash": {
  "description": "",
  "type": "string"
},
"apiUrl": {
  "description": "",
  "type": "string"
},
"socketUrl": {
  "description": "",
  "type": "string"
},
"useCache": {
  "description": "",
  "type": "boolean"
},
"subscriberId": {
  "description": "",
  "type": "string"
},
"subscriber": {
  "description": "",
  "type": "string | Subscriber"
}
}}
/>

### Usage

<Tabs items={['US', 'EU', '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: "https://eu.ws.novu.co",
    });
    ```
  </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"
}
}}
/>

```typescript
const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
  offset: 0,
});
```

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"
}
}}
/>

<Tabs items={['Single Filter', 'Multiple Filters']}>
  <Tab value="Single Filter">
    ```typescript
    // Single filter
    const count = await novu.notifications.count({
      read: false,
      archived: false,
       // data attributes
      data: {
        type: 'login',
      },
    });
    ```
  </Tab>

  <Tab value="Multiple Filters">
    ```typescript
    // Multiple filters
    const counts = await novu.notifications.count({
      filters: [{ read: false }, { 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' });
```

#### 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. Can be filtered by tags.

```typescript
await novu.notifications.readAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAll

Archives all notifications. Can be filtered by tags.

```typescript
await novu.notifications.archiveAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAllRead

Archives all read notifications. Can be filtered by tags.

```typescript
await novu.notifications.archiveAllRead({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### 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' });
```

## Preferences

### Methods

#### list

Fetches the subscriber's notification preferences.

```typescript
const preferences = await novu.preferences.list();
```

The response will be of type:

<TypeTable
  name="PreferenceResponse"
  type={{
"level": {
  "description": "",
  "type": "PreferenceLevel"
},
"enabled": {
  "description": "",
  "type": "boolean"
},
"channels": {
  "description": "",
  "type": "ChannelPreference"
},
"overrides": {
  "description": "",
  "type": "IPreferenceOverride[]"
},
"workflow": {
  "description": "",
  "type": "Workflow"
}
}}
/>

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

### Usage

```typescript
novu.on('notifications.notification_received', (data) => {
  console.log('New notification:', data);
});

novu.on('notifications.unread_count_changed', (data) => {
  console.log('Unread count:', data);
});
```

## Types

### Notification

<TypeTable
  name="Notification"
  type={{
"id": {
  "description": "",
  "type": "string"
},
"subject": {
  "description": "",
  "type": "string"
},
"body": {
  "description": "",
  "type": "string"
},
"to": {
  "description": "",
  "type": "Subscriber"
},
"isRead": {
  "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"
},
"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"
},
"read": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unread": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"archive": {
  "description": "",
  "type": "() => Result<Notification, NovuError>"
},
"unarchive": {
  "description": "",
  "type": "() => Result<Notification, 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"
}
}}
/>


file: ./content/docs/platform/sdks/javascript/index.model.mdx
# @novu/js

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

\---type-table---
../types/js-types.ts#NovuOptions
\---end---

### Usage

<Tabs items={['US', 'EU', '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: "https://eu.ws.novu.co",
    });
    ```
  </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.

\---type-table---
../types/js-types.ts#NotificationFilter
\---end---

```typescript
const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
  offset: 0,
});
```

The response will be of type:

\---type-table---
../types/js-types.ts#NotificationsResponse
\---end---

#### count

Fetches the count of notifications based on filters.

\---type-table---
../types/js-types.ts#NotificationFilter
\---end---

<Tabs items={['Single Filter', 'Multiple Filters']}>
  <Tab value="Single Filter">
    ```typescript
    // Single filter
    const count = await novu.notifications.count({
      read: false,
      archived: false,
       // data attributes
      data: {
        type: 'login',
      },
    });
    ```
  </Tab>

  <Tab value="Multiple Filters">
    ```typescript
    // Multiple filters
    const counts = await novu.notifications.count({
      filters: [{ read: false }, { 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' });
```

#### 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. Can be filtered by tags.

```typescript
await novu.notifications.readAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAll

Archives all notifications. Can be filtered by tags.

```typescript
await novu.notifications.archiveAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### archiveAllRead

Archives all read notifications. Can be filtered by tags.

```typescript
await novu.notifications.archiveAllRead({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});
```

#### 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' });
```

## Preferences

### Methods

#### list

Fetches the subscriber's notification preferences.

```typescript
const preferences = await novu.preferences.list();
```

The response will be of type:

\---type-table---
../types/js-types.ts#PreferenceResponse
\---end---

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

### Usage

```typescript
novu.on('notifications.notification_received', (data) => {
  console.log('New notification:', data);
});

novu.on('notifications.unread_count_changed', (data) => {
  console.log('Unread count:', data);
});
```

## Types

### Notification

\---type-table---
../types/js-types.ts#Notification
\---end---

### Subscriber

\---type-table---
../types/js-types.ts#Subscriber
\---end---


file: ./content/docs/platform/sdks/react-native/index.mdx
# Quickstart

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"
              backendUrl="https://api.eu.novu.co"
              socketUrl="https://ws.eu.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/react/production#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>


file: ./content/docs/platform/sdks/react/index.mdx
# @novu/react

undefined
        
## Components

The @novu/react package provides React components for building notification UIs.

## Inbox

The main component for displaying notifications.

### Props

<TypeTable
  name="InboxProps"
  type={{
"applicationIdentifier": {
  "description": "",
  "type": "string"
},
"subscriberHash": {
  "description": "",
  "type": "string"
},
"backendUrl": {
  "description": "",
  "type": "string"
},
"socketUrl": {
  "description": "",
  "type": "string"
},
"appearance": {
  "description": "",
  "type": "Appearance"
},
"localization": {
  "description": "",
  "type": "Localization"
},
"tabs": {
  "description": "",
  "type": "Tab[]"
},
"preferencesFilter": {
  "description": "",
  "type": "PreferencesFilter"
},
"routerPush": {
  "description": "",
  "type": "RouterPush"
},
"subscriberId": {
  "description": "",
  "type": "string"
},
"subscriber": {
  "description": "",
  "type": "string | Subscriber"
}
}}
/>

### Usage

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

function NotificationCenter() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="USER_ID"
      backendUrl="https://api.novu.co"
      socketUrl="https://ws.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"
},
"baseTheme": {
  "description": "",
  "type": "Theme | Theme[]"
}
}}
/>

#### 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"
}
}}
/>

#### Elements

<TypeTable
  name="InboxAppearanceElements"
  type={{
"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"
},
"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"
},
"collapsible": {
  "description": "",
  "type": "ElementStyles"
},
"tooltipContent": {
  "description": "",
  "type": "ElementStyles"
},
"tooltipTrigger": {
  "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"
},
"root": {
  "description": "",
  "type": "ElementStyles"
},
"bellIcon": {
  "description": "",
  "type": "ElementStyles"
},
"bellContainer": {
  "description": "",
  "type": "ElementStyles"
},
"bellDot": {
  "description": "",
  "type": "ElementStyles"
},
"preferences__button": {
  "description": "",
  "type": "ElementStyles"
},
"preferencesContainer": {
  "description": "",
  "type": "ElementStyles"
},
"inboxHeader": {
  "description": "",
  "type": "ElementStyles"
},
"loading": {
  "description": "",
  "type": "ElementStyles"
},
"inboxContent": {
  "description": "",
  "type": "ElementStyles"
},
"inbox__popoverTrigger": {
  "description": "",
  "type": "ElementStyles"
},
"inbox__popoverContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationListContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationList": {
  "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"
},
"notification": {
  "description": "",
  "type": "ElementStyles"
},
"notificationContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationTextContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDot": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSubject": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSubject__strong": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBody": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBody__strong": {
  "description": "",
  "type": "ElementStyles"
},
"notificationBodyContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationImage": {
  "description": "",
  "type": "ElementStyles"
},
"notificationImageLoadingFallback": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDate": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDateActionsContainer": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDefaultActions": {
  "description": "",
  "type": "ElementStyles"
},
"notificationCustomActions": {
  "description": "",
  "type": "ElementStyles"
},
"notificationPrimaryAction__button": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSecondaryAction__button": {
  "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"
},
"workflowContainer": {
  "description": "",
  "type": "ElementStyles"
},
"workflowLabel": {
  "description": "",
  "type": "ElementStyles"
},
"workflowLabelHeader": {
  "description": "",
  "type": "ElementStyles"
},
"workflowLabelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"workflowContainerDisabledNotice": {
  "description": "",
  "type": "ElementStyles"
},
"workflowLabelDisabled__icon": {
  "description": "",
  "type": "ElementStyles"
},
"workflowContainerRight__icon": {
  "description": "",
  "type": "ElementStyles"
},
"workflowArrow__icon": {
  "description": "",
  "type": "ElementStyles"
},
"workflowDescription": {
  "description": "",
  "type": "ElementStyles"
},
"channelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"channelIconContainer": {
  "description": "",
  "type": "ElementStyles"
},
"channel__icon": {
  "description": "",
  "type": "ElementStyles"
},
"channelsContainerCollapsible": {
  "description": "",
  "type": "ElementStyles"
},
"channelsContainer": {
  "description": "",
  "type": "ElementStyles"
},
"channelLabel": {
  "description": "",
  "type": "ElementStyles"
},
"channelLabelContainer": {
  "description": "",
  "type": "ElementStyles"
},
"channelName": {
  "description": "",
  "type": "ElementStyles"
},
"channelSwitchContainer": {
  "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"
},
"notificationSnooze__dropdownContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__dropdownItem": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnooze__dropdownItem__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnoozeCustomTime_popoverContent": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDeliveredAt__badge": {
  "description": "",
  "type": "ElementStyles"
},
"notificationDeliveredAt__icon": {
  "description": "",
  "type": "ElementStyles"
},
"notificationSnoozedUntil__icon": {
  "description": "",
  "type": "ElementStyles"
},
"strong": {
  "description": "",
  "type": "ElementStyles"
}
}}
/>

## 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"
},
"renderSubject": {
  "description": "",
  "type": "SubjectRenderer"
},
"renderBody": {
  "description": "",
  "type": "BodyRenderer"
}
}}
/>

### 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"
},
"renderSubject": {
  "description": "",
  "type": "SubjectRenderer"
},
"renderBody": {
  "description": "",
  "type": "BodyRenderer"
}
}}
/>

### 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>
  );
}
```


file: ./content/docs/platform/sdks/react/index.model.mdx
# @novu/react

undefined
        
## Components

The @novu/react package provides React components for building notification UIs.

## Inbox

The main component for displaying notifications.

### Props

\---type-table---
../types/react-types.ts#InboxProps
\---end---

### Usage

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

function NotificationCenter() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APP_ID"
      subscriber="USER_ID"
      backendUrl="https://api.novu.co"
      socketUrl="https://ws.novu.co"
      placement="right"
      placementOffset={10}
      onNotificationClick={(notification) => {
        // Handle notification click
        console.log(notification);
      }}
    />
  );
}
```

### Appearance Configuration

\---type-table---
../types/react-types.ts#InboxAppearanceProps
\---end---

#### Variables

\---type-table---
../types/react-types.ts#InboxAppearanceVariables
\---end---

#### Elements

\---type-table---
../types/react-types.ts#InboxAppearanceElements
\---end---

## Bell

A customizable notification bell component.

### Props

\---type-table---
../types/react-types.ts#BellProps
\---end---

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

\---type-table---
../types/react-types.ts#NotificationProps
\---end---

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

\---type-table---
../types/react-types.ts#InboxContentProps
\---end---

### 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>
  );
}
```


file: ./content/docs/platform/sdks/server/dotnet.mdx
# .NET

Connect a .NET application to Novu
        
<Callout type="warn">
  This SDK is community maintained. Feel free to contribute on our [GitHub
  repository](https://github.com/novuhq/novu-dotnet).
</Callout>

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-dotnet)

## Installation

```csharp
dotnet add package Novu
```

## Usage

```csharp
using Novu.DTO;
using Novu.Models;
using Novu;
...

var novuConfiguration = new NovuClientConfiguration
{
    // Defaults to https://api.novu.co/v1
    Url = "https://novu-api.my-domain.com/v1",
    ApiKey = "12345",
};

var novu = new NovuClient(novuConfiguration);

// OnboardEventPayload.cs
public class OnboardEventPayload
{
  [JsonProperty("username")]
  public string Username { get; set; }

  [JsonProperty("welcomeMessage")]
  public string WelcomeMessage { get; set; }
}

// MyFile.cs
var onboardingMessage = new OnboardEventPayload
{
  Username = "jdoe",
  WelcomeMessage = "Welcome to novu-dotnet"
};

var payload = new EventTriggerDataDto()
{
  EventName = "onboarding",
  To = { SubscriberId = "subscriberId" },
  Payload = onboardingMessage
};

var trigger = await novu.Event.Trigger(payload);

if (trigger.TriggerResponsePayloadDto.Acknowledged)
{
  Console.WriteLine("Trigger has been created.");
}
```


file: ./content/docs/platform/sdks/server/go.mdx
# Go SDK

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>


file: ./content/docs/platform/sdks/server/index.mdx
# Server Side

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>
</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="Java (Community)" icon={<JavaIcon />} color="#dc2626" href="/platform/sdks/server/java">
    Connect your Java app to Novu via the Java 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>

  <Card title=".NET (Community)" icon={<DotnetIcon />} color="#dc2626" href="/platform/sdks/server/dotnet">
    Connect your C#/.NET app to Novu via the .NET SDK.
  </Card>
</Cards>


file: ./content/docs/platform/sdks/server/java.mdx
# Java

Connect a Java application to Novu
        
<Callout type="warn">
  This SDK is community maintained. Feel free to contribute on our [GitHub
  repository](https://github.com/novuhq/novu-java).
</Callout>

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

Maven users:

```java
<!--add dependency-->
<dependency>
    <groupId>co.novu</groupId>
    <artifactId>novu-java</artifactId>
    <version>{use-latest-version}</version>
</dependency>
```

The latest version can be found [on GitHub.](https://github.com/novuhq/novu-java#installation)

Gradle users:

```groovy
implementation 'co.novu:novu-java:{latest-version}'
```

Sync your project, and you should have the artifacts downloaded.

## Usage

```java
import co.novu.sdk.Novu;

public class Main {
    public static void main(String[] args) {
        String apiKey = "INSERT_API_KEY_HERE";
        // Using the API Key only
        Novu novu = new Novu(apiKey);

        // Using the Config Param
        NovuConfig novuConfig = new NovuConfig(apiKey);
        Novu novu = new Novu(novuConfig);

        // Sample usage
        novu.triggerEvent(event);
    }
}

// Sign up on https://dashboard.novu.co and grab your API key from https://dashboard.novu.co/settings
```


file: ./content/docs/platform/sdks/server/kotlin.mdx
# 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)
}

```


file: ./content/docs/platform/sdks/server/laravel.mdx
# 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();
```


file: ./content/docs/platform/sdks/server/php.mdx
# PHP SDK

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>


file: ./content/docs/platform/sdks/server/python.mdx
# 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>

```
```


file: ./content/docs/platform/sdks/server/ruby.mdx
# 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)
```


file: ./content/docs/platform/sdks/server/typescript.mdx
# 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

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


file: ./content/docs/platform/inbox/react/components/bell.mdx
# <Bell />

The Bell component displays the notification bell icon and unread notification count
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The `Bell` component displays the notification bell icon. It can also be used to show the number of unread notifications.

## Custom Bell

You can pass any custom components to the `renderBell` prop to use with your own bell icon and unread count UI.

```tsx
import { Inbox, Bell } from '@novu/react';
import { BellIcon } from './icons';

function Novu() {
  return (
    <Inbox 
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" 
      subscriber="YOUR_SUBSCRIBER_ID" 
      renderBell={(unreadCount) => {
          return (
            <div className="bg-purple-300 p-4 inline-flex">
              New ${unreadCount} notifications
            </div>
          );
      }} 
    />
  );
}
```

## Custom Popover Integration

<Callout type="info">
  `<Inbox />` can be mounted in your own popover component. For further customization, you can also
  use the `renderBell` and `renderNotification` render props.
</Callout>

Below is an example of how to use `<Inbox />` with [Radix UI](https://www.radix-ui.com/):

```tsx
import React from 'react';
import * as Popover from '@radix-ui/react-popover';
import { BellIcon, Cross2Icon } from '@radix-ui/react-icons';
import { Inbox, Bell, Notifications } from '@novu/react';
import './styles.css';

const PopoverDemo = () => (
  <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
    <Popover.Root>
      <Popover.Trigger asChild>
        <Bell
          renderBell={(unreadCount) => (
            <div>
              <span>{unreadCount}</span>
              <BellIcon />
            </div>
          )}
        />
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Content className="PopoverContent" sideOffset={5}>
          <Notifications />
          <Popover.Close className="PopoverClose" aria-label="Close">
            <Cross2Icon />
          </Popover.Close>
          <Popover.Arrow className="PopoverArrow" />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  </Inbox>
);

export default PopoverDemo;
```


file: ./content/docs/platform/inbox/react/components/inbox-content.mdx
# <InboxContent />

Learn how to use the InboxContent component with custom popovers and handle notification interactions
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

By default, `<InboxContent />` renders the content of the `<Inbox />` popover. This component is meant to be used with a custom popover.

## Basic Usage

<Callout type="info">
  The InboxContent component provides a flexible way to customize the inbox display while
  maintaining all the core notification functionality.
</Callout>

```tsx
import { Bell, Inbox, InboxContent } from '@novu/react';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';

export default 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>
  );
}
```

## Advanced Usage

The `<InboxContent />` component can receive all the props that `<Inbox />` does, besides the configuration and bell specific ones. This allows for extensive customization of notification handling and display.

```tsx
import { Bell, Inbox, InboxContent } from '@novu/react';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';

export default 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
            onNotificationClick={(notification) => {
              // your logic to handle notification click
            }}
            onPrimaryActionClick={(notification) => {
              // your logic to handle primary action click
            }}
            onSecondaryActionClick={(notification) => {
              // your logic to handle secondary action click
            }}
            renderNotification={(notification) => (
              <div>
                <h3>{notification.subject}</h3>
                <p>{notification.body}</p>
              </div>
            )}
          />
        </PopoverContent>
      </Popover>
    </Inbox>
  );
}
```

<Callout type="info">
  The example above demonstrates how to:

  * Handle notification clicks
  * Customize primary and secondary action behaviors
  * Provide custom rendering for notifications
</Callout>


file: ./content/docs/platform/inbox/react/components/inbox.mdx
# <Inbox />

Learn how to use and customize the Inbox component in your application
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

By default, the `<Inbox />` renders a bell button, that opens a popover on click. The popover contains the notifications list and the user preferences.

## Try it without keys (Keyless Mode)

Try Novu Inbox instantly - no setup required. With Keyless mode, you can integrate and test the `<Inbox />` right in your app. It’s ideal for exploring features and sending test notifications.

```tsx
import React from 'react';
import { Inbox } from '@novu/react';
 
export function KeylessInbox() {
 
  return (
    <Inbox />
  );
}
```

<Callout type="info" title="Ready for the Full Experience?">
  Keyless mode is designed for quick exploration. To save your configuration, identify users, and unlock all of Novu's powerful features, you'll need to sign up for a free account and configure your environment. <a href="https://dashboard.novu.co/auth/sign-up" target="_blank" rel="noopener noreferrer" class="nx-text-primary-600 nx-underline">Sign up on Novu Cloud</a>
</Callout>

## Basic Usage

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

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID" />
  );
}
```

## Navigation

The Inbox component uses the `routerPush` prop to make your notifications navigatable. We will automatically pass the `redirect.url` from your workflow definitions to the `routerPush` prop.

<Callout type="info">
  To make the navigation work, you will need to specify the `routerPush` behaviour depending on your
  routing library.
</Callout>

<Tabs items={['Next.js', 'Remix', 'React Router', 'Gatsby', 'Create React App']}>
  <Tab>
    ```tsx
    import { Inbox } from '@novu/nextjs';

    function Novu() {
      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { useNavigate } from '@remix-run/react';

    function Novu() {
      const navigate = useNavigate();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { useNavigate } from 'react-router-dom';

    function Novu() {
      const navigate = useNavigate();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { navigate } from 'gatsby';

    function Novu() {
      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';
    import { useNavigate } from 'react-router-dom';

    function Novu() {
      const navigate = useNavigate();

      return (
        <Inbox
          applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
          subscriber="YOUR_SUBSCRIBER_ID"
          routerPush={(path: string) => navigate(path)}
        />
      );
    }
    ```
  </Tab>
</Tabs>

## Data object

The `data` object is a key-value store within each notification, used to extend <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> notifications by embedding step-specific metadata. It provides flexible notification handling, supporting both static and dynamic values:

* **Static Values**: These are hardcoded into the notification step—for example, a string like "status": "merged" or "icon": "heart". These values don't change based on the recipient or context.
* **Dynamic Values**: These values are derived from subscriber or payload data. For instance, they can reference `subscriber.firstName` or `payload.issueId` to tailor notifications for individual users.

You can pass data such as:

* `reactionType`: To display specific icons such as 👍, ❤️, or a comment bubble.
* `entityId` (like `pullRequestId` or `issueId`): Create direct links or show relevant badges (e.g., a GitHub logo linking to the PR).
* `status` or `actionType`: To show visual cues such as colored dots or status icons (e.g., green for 'merged', orange for 'commented').

<img alt="Data object for in-app Inbox step" src="/images/inbox/data-object.png" />

The `data` object is defined within a workflow's in-app step in the Novu dashboard. Each key-value pair, referred to as a property, can be static or dynamic, and you get up to 10 properties per in-app step. These properties are accessible on the frontend via the `notification.data` property.

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

<Inbox
  applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
  subscriber="YOUR_SUBSCRIBER_ID"
  renderNotification={(notification) => (
    <div>
      <p>{notification.data?.customKey}</p>
      <p>{notification.data?.dataId}</p>
    </div>
  )}
/>
```

<Callout type="warn">
  `notification.data` is included in the client response, so do not store any sensitive data in it.
</Callout>

By default, `notification.data` is untyped. To ensure type safety, declare the `NotificationData` interface globally.

```ts
declare global {
  interface NotificationData {
    customKey?: string;
    dataId?: number;
  }
}
```

This lets TypeScript infer the structure of `notification.data`, preventing errors when accessing properties. However, as not all notifications include the same keys, check properties for existence before usage.

## Snooze

The <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component includes built-in support for snoozing notifications, which lets users delay reminders and resurface them at a more convenient time.

When a user snoozes a notification, it is temporarily removed from the active list and automatically redelivered at the specified time. This helps reduce noise while keeping important updates accessible.

<Callout type="info">Snooze is supported in client-side SDKs starting from version 3.3.0 and is only available for Cloud workspaces.</Callout>

### Snoozing a notification

All dates and times are interpreted in the user's local timezone. Users can snooze a notification directly from the <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> 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.

<img src="/images/inbox/snooze-a-notification.png" alt="Render HTML in Inbox" />

<Callout type="info">The selected snooze time must be at least 3 minutes in the future.</Callout>

Once snoozed:

* The notification leaves the All tab and appears in the Snoozed tab.
* It cannot be marked as read or unread or archived until it returns.

All of these behaviors are handled automatically by the <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component.

Developers can also configure how the snooze options are presented by customizing styles, localization keys, or using snooze-related actions exposed on the notification object. For instance, each notification instance includes `.snooze()` and `.unsnooze()` methods in the client-side SDKs, allowing you to control reminders when needed.

<Callout type="info">
  Snoozing is available on all plans for Cloud workspaces:

  * 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
</Callout>

### Managing snoozed notifications

The <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> 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.

## Event Handling

### Notification Click

<Callout type="info">
  You can handle notification clicks without navigation by using the `onNotificationClick` prop.
  This is useful for opening modals or drawers instead of navigating to a page.
</Callout>

```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
      }}
    />
  );
}
```

### Action Clicks

Handle action button clicks without navigation using the `onPrimaryActionClick` and `onSecondaryActionClick` props:

```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
      }}
    />
  );
}
```

## Customization

### Controlled Popover State

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

function Novu() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Inbox
        applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
        subscriber="YOUR_SUBSCRIBER_ID"
        open={open}
      />
      <button onClick={() => setOpen(!open)}>Toggle Inbox</button>
    </>
  );
}
```

### Custom notification Item

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderNotification={(notification) => (
        <div>
          <h3>{notification.subject}</h3>
          <p>{notification.body}</p>
        </div>
      )}
    />
  );
}
```

### Custom notification Subject

Render a custom subject for the notification, while keeping the default notification component.

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderSubject={(notification) => (
        <div>
          <p>{notification.subject}</p>
        </div>
      )}
    />
  );
}
```

### Custom notification Body

Render a custom body for the notification, while keeping the default notification component.

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderBody={(notification) => (
        <div>
          <p>{notification.body}</p>
        </div>
      )}
    />
  );
}
```

## Conditional rendering of notifications

The <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component supports conditional rendering of notifications using the renderNotification prop. This function receives a `notification` object and returns a custom React element.

You can use workflow tags, workflow identifiers, or values from the data object to customize how each notification is displayed. You can also combine multiple conditions to create dynamic and tailored notification displays.

### Render based on workflow tags

You can conditionally render 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=""
      subscriber=""
      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>
        );
      }}
    />
  );
}
```

### Render 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=""
      subscriber=""
      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>
        );
      }}
    />
  );
}
```

### Render based on data object

You can also use values from the notification [data object](/platform/inbox/react/components/inbox#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=""
      subscriber=""
      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>
        );
      }}
    />
  );
}
```

## Rendering HTML

To render HTML tags in inbox, user renderBody props and render the notification body as a `dangerouslySetInnerHTML` element.

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

function NovuInbox() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      renderBody={(notification) => (
        <div>
          <p dangerouslySetInnerHTML={{ __html: notification.body }} />
        </div>
      )}
    />
  );
}
```

**Steps**:

1. Create a workflow with in-app step.
2. Toggle on the `Disable content sanitization` option on the top right corner of the in-app step.
3. Use html tags in in-app step body as shown in the image below

<img src="/images/inbox/render-html.png" alt="Render HTML in Inbox" />

HTML Content:

```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="{{payload.analyticsPage}}" 
target="_blank">here</a> and gain deeper insights into your usage.
```

## Filtering Preferences

<Callout type="info">
  Customize visible preferences using the `preferencesFilter` prop to display only relevant
  preferences to your users. The filtering works by matching workflow
  [tags](/platform/workflow/overview#tags) with the specified filter `tags` value.
</Callout>

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferencesFilter={{ tags: ['general', 'admin', 'security'] }}
    />
  );
}
```

## Subscriber Data Upsert

The `<Inbox />` component supports real-time subscriber data updates when properly configured with HMAC authentication. This allows you to update subscriber information directly through the component without making separate API calls:

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

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberHash="GENERATED_HMAC_HASH" // Generated on your backend
      subscriber={{
        subscriberId: "YOUR_SUBSCRIBER_ID",
        firstName: "John",
        lastName: "Doe",
        email: "john@example.com"
      }}
    />
  );
}
```

<Callout type="info">
  To enable real-time subscriber data updates, make sure to provide the `subscriberHash` for secure HMAC authentication. This allows you to update subscriber data directly through the component while maintaining security.
</Callout>

Learn more about setting up HMAC authentication in the [Enabling HMAC Encryption](/platform/inbox/react/production#hmac-encryption) guide.


file: ./content/docs/platform/inbox/react/components/index.mdx
# Components

undefined
        
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Bell, Code, Layout, Sliders } from 'lucide-react';

## Composition

The Inbox is composed of the following sub-components that you can use to build your Inbox structure and layout:

<Cards>
  <Card title="Inbox" icon={<Layout />} href="/platform/inbox/react/components/inbox">
    The Inbox wrapper, which is used to wrap the entire inbox UI and establish the session
  </Card>

  <Card title="Bell" icon={<Bell />} href="/platform/inbox/react/components/bell">
    Used to display the bell icon and trigger the popover component when clicked
  </Card>

  <Card title="Notifications" icon={<Code />}>
    Displays the notifications list
  </Card>

  <Card title="Preferences" icon={<Sliders />} href="/platform/inbox/react/components/preferences">
    Used to display the preferences modal
  </Card>

  <Card title="InboxContent" icon={<Layout />} href="/platform/inbox/react/components/inbox-content">
    Usage with a custom popover
  </Card>
</Cards>

The internal UI and styles for those components can be modified using the [`appearance`](/platform/inbox/react/styling#appearance-prop) prop.

<img src="/images/inbox/composition@2x.png" alt="Component Composition" />

## Layouts

The composition of the indivudal components can generate multiple different popular inbox layouts.

### Inbox with Bell (Default)

A trigger button usually located at the top right corner of the screen, which triggers the popover component when clicked.

<Tabs items={['Default Bell', 'Custom Bell']}>
  <Tab>
    ```tsx
    import { Inbox } from '@novu/react';

    function Novu() {
      return <Inbox subscriber="1" applicationIdentifier="1" />;
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    import { Inbox, Bell } from '@novu/react';
    import { BellIcon } from './icons';

    function Novu() {
      return (
        <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
          <Bell
            renderBell={(unreadCount) => (
              <div>
                <span>{unreadCount}</span>
                <BellIcon />
              </div>
            )}
          />
        </Inbox>
      );
    }
    ```
  </Tab>
</Tabs>

### Side menu Inbox

To render a side menu inbox, use the `<Notifications />` component as a direct child of the `<Inbox />` component, you can hide or show it based on any custom logic.

```tsx
import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      {showSideMenu && <Notifications />}
    </Inbox>
  );
}
```

### Full page Inbox

Similiary to the side menu inbox, you can use the `<Notifications />` component as a direct child of the `<Inbox />` component, you can hide or show it based on any custom logic.

```tsx
import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      <Notifications />
    </Inbox>
  );
}
```

### Inbox with a custom popover

```tsx
import { Bell, Inbox, InboxContent } from '@novu/react';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';

export default function CustomPopoverPage() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      <Popover>
        <PopoverTrigger>
          <Bell />
        </PopoverTrigger>
        <PopoverContent className="h-[500px] w-[400px] overflow-auto p-0">
          <InboxContent />
        </PopoverContent>
      </Popover>
    </Inbox>
  );
}
```


file: ./content/docs/platform/inbox/react/components/notifications.mdx
# <Notifications />

Display and customize the list of notifications in your application
        
The `Notifications` component is used to display the list of notifications.

## Basic Usage

Display notifications as a list without the Bell and Popover:

```tsx
import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      <Notifications />
    </Inbox>
  );
}
```

## Custom Notification Item

You can customize how each notification is rendered using the `renderNotification` prop:

```tsx
import { Inbox, Notifications } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      <Notifications
        renderNotification={(notification) => (
          <div>
            <h3>{notification.subject}</h3>
            <p>{notification.body}</p>
          </div>
        )}
      />
    </Inbox>
  );
}
```

<Callout type="info">
  The `renderNotification` prop gives you full control over how each notification is displayed,
  allowing you to customize the layout, styling, and what notification data to show.
</Callout>


file: ./content/docs/platform/inbox/react/components/preferences.mdx
# <Preferences />

Learn how to use and customize the Preferences component in React to manage notification settings.
        
By default, Novu will show the subscriber preferences cog icon on the Inbox component.

Users can enable/disable any active channel in the workflow using subscriber preferences or they can update the preference globally for all workflows under the `Global Preferences`.

![Preferences](/images/inbox/preferences@2x.png)

## Basic usage

The `Preferences` component is used to display the subscriber preferences. Use it when you want to render preferences in another part of your application or create a custom layout for the Inbox.

```tsx
import { Inbox, Preferences } from '@novu/react';

function Novu() {
  return (
    <Inbox applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" subscriber="YOUR_SUBSCRIBER_ID">
      <Preferences />
    </Inbox>
  );
}
```

## Customization options

### Filtering preferences

<Callout type="info">
  You can filter the preferences visible by the user by specifying the `preferenceFilter` on the
  `Inbox` component. Learn more about it
  [here](/platform/inbox/react/components/inbox#filter-visible-preferences).
</Callout>

### Hiding global preferences

Global subscriber preferences are shown by default. To hide them, add the following code to your global CSS file:

```css
.nv-workflowContainer:first-child {
  display: none;
}
```

### Grouping preferences

Preference grouping lets you organize extensive lists of workflows into well-organized, meaningful groups. This ensures that your end-users get a better experience when managing their preferences.

<Callout type="info">
  Note: Grouping preference is supported in client-side SDKs starting from version 3.4.0.
</Callout>

To implement preference grouping, use the `preferenceGroups` prop on the `Inbox` component. Each group requires:

* `name`: The text displayed for the group
* `filter`: Criteria for which preferences appear in the group (object or function)

Here are the different ways to group preferences:

#### Group by tags

Use this approach to group preferences that share specific tags.

```tsx
const preferenceGroups = [
{
 name: 'General',
 filter: {
   tags: ['account'],
 },
},
];
```

#### Group by tags and workflow IDs

Combine tags and workflow IDs to define a more targeted group of preferences.

```tsx
const preferenceGroups = [
{
 name: 'Marketing',
 filter: {
   tags: ['marketing'],
   workflowIds: ['workflow-id'],
 },
},
];

```

#### Group all workflows

Include every available workflow, regardless of its tag or grouping, by returning the full preferences list.

```tsx
const preferenceGroups = [
{
 name: 'All Workflows',
 filter: ({ preferences }) => preferences,
},
];
```

#### Group using custom logic

You can implement custom filtering logic using a function that receives the preferences array (excluding global preferences) and returns filtered preferences based on your criteria.

<Callout type="info">
  The Global Preferences are always visible and cannot be removed from the list.
</Callout>

Here’s how the `preferenceGroups` prop fits into the full <Method href="/platform/inbox/react/components/inbox">{`<Inbox />`}</Method> component:

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

function InboxWithGroups() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      preferenceGroups={[
        {
          name: 'General',
          filter: { tags: ['account'] },
        },
        {
          name: 'Marketing',
          filter: { tags: ['marketing'], workflowIds: ['workflow-id'] },
        },
        {
          name: 'All Workflows',
          filter: ({ preferences }) => preferences,
        },
      ]}
    />
  );
}
```

<img src="/images/inbox/preference-groups.png" alt="Grouping preferences" className="rounded-lg border w-[800px]" />


file: ./content/docs/platform/integrations/email/(providers)/amazon-ses.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/braze.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/brevo.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/custom-smtp.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/infobip.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/mailersend.mdx
# 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">
    ```jsx
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_SECRET_KEY>');

    await novu.subscribers.trigger("workflowIdentifier", { 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 />


file: ./content/docs/platform/integrations/email/(providers)/mailgun.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/mailjet.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/mailtrap.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/mandrill.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/maqsam.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/netcore.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/outlook365.mdx
# Outlook 365

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 />


file: ./content/docs/platform/integrations/email/(providers)/plunk.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/postmark.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/resend.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/sendgrid.mdx
# 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/node";

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.trigger("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="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 />


file: ./content/docs/platform/integrations/email/(providers)/sparkpost.mdx
# 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 />


file: ./content/docs/platform/integrations/email/(providers)/webhook.mdx
# 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 />


file: ./content/docs/platform/integrations/chat/(providers)/discord.mdx
# 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">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Discord, {
      webhookUrl: "<WEBHOOK_URL>",
    });

    ```
  </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 ChatProviderIdEnum 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/node` package or directly using the REST API in the channel you chose on your discord server.


file: ./content/docs/platform/integrations/chat/(providers)/mattermost.mdx
# 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, ChatProviderIdEnum } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Mattermost, {
  webhookUrl: '<enter-mattermost-webhook-url>',
});

// Send a notification to Mattermost using the subscriber ID and payload.
await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<UNIQUE_SUBSCRIBER_IDENTIFIER>',
  },
  payload: {
    message: 'This is a notification from my application!',
  },
});
```

### Mattermost Bot Integration

To integrate Mattermost with your application using the Mattermost Bot integration, you will need to create a Mattermost bot account and generate an API token for the bot. Once you have the API token, you can store it in the subscriber entity in your application.

Once you have stored the API token in the subscriber entity, you can send notifications to Mattermost using the following code:

```typescript
import { Novu, ChatProviderIdEnum } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

// Get the Mattermost bot API token for the subscriber.
await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Mattermost, {
  botApiToken: '<enter-mattermost-bot-api-token>',
});

// Send a notification to Mattermost using the bot API token.
await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<UNIQUE_SUBSCRIBER_IDENTIFIER>',
  },
  payload: {
    message: 'This is a notification from my application!',
  },
});
```


file: ./content/docs/platform/integrations/chat/(providers)/ms-teams.mdx
# MS Teams

Learn about how to use MS Teams provider for chat notifications
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

MS Teams does not need any `API Key` or `Client ID` to send notifications. Our current implementation is based on the [Incoming Webhook URL](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cjavascript). It is a URL that you can use to send messages to a specific channel. This URL needs to be stored on the subscriber entity

Similar to [Discord](/platform/integrations/chat/discord), the credential for this provider needs to be stored in the [subscriber entity](/api-reference/subscribers/update-provider-credentials).

## Creating incoming webhook URL

Checkout step by step instructions on microsoft team's documentation on how to [create an incoming webhook url](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cjavascript).

![Steps to create incoming webhook url](/images/channels-and-providers/chat/msteams/create-incoming-webhook.gif)

## Storing webhook url on subscriber entity

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 MS Teams provider id. You can do this step by using the `@novu/node` library, as shown below:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.MsTeams, {
      webhookUrl: "<WEBHOOK_URL>"
    }, 'msteams-MnGLxp8uy');
    ```
  </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": "msteams",
      "credentials": {
          "webhookUrl": "<WEBHOOK_URL>"
      },
      "integrationIdentifier": "msteams-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 ChatProviderIdEnum to specify the provider.
* The third parameter is the credentials object, in this case, we use the `webhookUrl` property to specify the MS Teams channel webhook URL or by calling the `Update Subscriber Credentials` endpoint on Novu API. Check endpoint details [here](/api-reference/subscribers/update-provider-credentials).


file: ./content/docs/platform/integrations/chat/(providers)/slack.mdx
# Slack

Learn about how to use Slack provider for chat notifications
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

When using Slack you will have to save the integration credentials in the subscriber entity.

This guide will walk you through the steps needed to obtain the `webhookUrl` that Novu requires to send chat messages to your customers.

We will provide the basic flow that the user needs to perform, to successfully send notifications via the Slack integration.

## Creating application

This step is optional, if you already have a Slack application you can reuse it.

<Steps>
  <Step title="Create a new Slack app">
    Go to Slack's developer dashboard [https://api.slack.com/apps](https://api.slack.com/apps) and create a new application.
  </Step>
</Steps>

## Integrating Novu with Slack

### Manually managed

To use the manually managed option, you need to generate a `webhookUrl` and plug it into your backend.

<Steps>
  <Step title="Enable Incoming Webhooks">
    Goto 'Incoming Webhooks' in your Slack app settings and turn it on.

    ![Turn on Incoming Webhooks](/images/guides/slack-guide/on.png)
  </Step>

  <Step title="Add New Webhook">
    Click on the 'Add New Webhook to Workspace':

    ![Add New Webhook to Workspace](/images/guides/slack-guide/add.png)
  </Step>

  <Step title="Select Channel">
    Now, go ahead and select the channel in which you want to send notifications and click 'allow'.

    ![Select channel](/images/guides/slack-guide/install.png)
  </Step>

  <Step title="Copy Webhook URL">
    Copy the 'webhookUrl' from Slack.

    ![Copy webhookUrl](/images/guides/slack-guide/hook.png)
  </Step>

  <Step title="Save Webhook URL">
    Now, you need to save the `webhookUrl` on the relevant subscriber entity in Novu. Here's an example to do the same using our Node SDK:
  </Step>
</Steps>

## Writing Slack content (Blocks API)

Novu Framework supports using [blocks](https://api.slack.com/block-kit) as part of the delivered messages using the provider overrides of the `chat` channel:

You can use the [Blocks Playground](https://app.slack.com/block-kit-builder/T02QYEPHZMM#%7B%22blocks%22:%5B%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22Hello,%20Assistant%20to%20the%20Regional%20Manager%20Dwight!%20*Michael%20Scott*%20wants%20to%20know%20where%20you'd%20like%20to%20take%20the%20Paper%20Company%20investors%20to%20dinner%20tonight.%5Cn%5Cn%20*Please%20select%20a%20restaurant:*%22%7D%7D,%7B%22type%22:%22divider%22%7D,%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Farmhouse%20Thai%20Cuisine*%5Cn:star::star::star::star:%201528%20reviews%5Cn%20They%20do%20have%20some%20vegan%20options,%20like%20the%20roti%20and%20curry,%20plus%20they%20have%20a%20ton%20of%20salad%20stuff%20and%20noodles%20can%20be%20ordered%20without%20meat!!%20They%20have%20something%20for%20everyone%20here%22%7D,%22accessory%22:%7B%22type%22:%22image%22,%22image_url%22:%22https://s3-media3.fl.yelpcdn.com/bphoto/c7ed05m9lC2EmA3Aruue7A/o.jpg%22,%22alt_text%22:%22alt%20text%20for%20image%22%7D%7D,%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Kin%20Khao*%5Cn:star::star::star::star:%201638%20reviews%5Cn%20The%20sticky%20rice%20also%20goes%20wonderfully%20with%20the%20caramelized%20pork%20belly,%20which%20is%20absolutely%20melt-in-your-mouth%20and%20so%20soft.%22%7D,%22accessory%22:%7B%22type%22:%22image%22,%22image_url%22:%22https://s3-media2.fl.yelpcdn.com/bphoto/korel-1YjNtFtJlMTaC26A/o.jpg%22,%22alt_text%22:%22alt%20text%20for%20image%22%7D%7D,%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Ler%20Ros*%5Cn:star::star::star::star:%202082%20reviews%5Cn%20I%20would%20really%20recommend%20the%20%20Yum%20Koh%20Moo%20Yang%20-%20Spicy%20lime%20dressing%20and%20roasted%20quick%20marinated%20pork%20shoulder,%20basil%20leaves,%20chili%20&%20rice%20powder.%22%7D,%22accessory%22:%7B%22type%22:%22image%22,%22image_url%22:%22https://s3-media2.fl.yelpcdn.com/bphoto/DawwNigKJ2ckPeDeDM7jAg/o.jpg%22,%22alt_text%22:%22alt%20text%20for%20image%22%7D%7D,%7B%22type%22:%22divider%22%7D,%7B%22type%22:%22actions%22,%22elements%22:%5B%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22Farmhouse%22,%22emoji%22:true%7D,%22value%22:%22click_me_123%22%7D,%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22Kin%20Khao%22,%22emoji%22:true%7D,%22value%22:%22click_me_123%22,%22url%22:%22https://google.com%22%7D,%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22Ler%20Ros%22,%22emoji%22:true%7D,%22value%22:%22click_me_123%22,%22url%22:%22https://google.com%22%7D%5D%7D%5D%7D) from Slack to learn more about the diffrent blocks available.

```typescript
await step.chat(
  'send-chat',
  async () => {
    return {
      // This will be used as a fallback for the chat provider if other than Slack provider is used
      body: 'A new post has been created',
    };
  },
  {
    providers: {
      slack: async ({ inputs }) => ({
        text: 'A new post has been created',
        blocks: [
          {
            type: 'section',
            text: {
              type: 'mrkdwn',
              text: 'A new post has been created',
            },
          },
        ],
      }),
    },
  }
);
```

## Update credential webhookUrl

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Slack, { webhookUrl: "<WEBHOOK_URL>", });

    ```
  </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>

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 ChatProviderIdEnum.Slack if you're using Node, else string of Slack 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/node package or directly using the REST API.

## Configuring Slack application

<Steps>
  <Step title="Configure OAuth & Permissions">
    Go to OAuth & Permissions on Slack's Developer Dashboard and add your REDIRECT\_URL in Redirect URLs.

    * If you use a manual Management solution, add the API endpoint you created in Step 1.
  </Step>

  <Step title="Enable Incoming Webhooks">
    Go to Incoming Webhooks from the left menu and Activate Incoming Webhooks.
  </Step>

  <Step title="Configure Distribution Settings">
    Go to Manage Distribution and at the bottom of the page, tick Remove Hard Coded Information and Activate Public Distribution.
  </Step>
</Steps>

### Enabling HMAC Encryption

To enable Hash-Based Message Authentication Codes, you need to do the following steps:

<Steps>
  <Step title="Enable HMAC encryption">
    Visit the integration store page and enable HMAC encryption under your chat provider.
  </Step>

  <Step title="Generate HMAC hash">
    The next step would be to generate an HMAC encrypted subscriberId on your backend:

    ```jsx
    import { createHmac } from 'crypto';

    const hmacHash = createHmac('sha256', process.env.NOVU_SECRET_KEY)
      .update(subscriberId)
      .digest('hex');
    ```
  </Step>

  <Step title="Add HMAC to URL">
    Add the newly created hash HMAC to the Sharable URL as a query.
  </Step>
</Steps>

This concludes the Slack provider guide.


file: ./content/docs/platform/integrations/chat/(providers)/whats-app.mdx
# WhatsApp Business

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
    novu.trigger('workflow-id', {
      to: {
        subscriberId: 'SUBSCRIBER_ID',
        phone: '+11111111111',
      },
      payload: {},
      overrides: {
        chat: {
          template: {
            name: 'template_name',
            language: {
              code: 'en_US',
            },
          },
        },
      },
    });
    ```
  </Step>
</Steps>


file: ./content/docs/platform/integrations/chat/(providers)/zulip.mdx
# 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/node` library, as shown below:

## Update credential webhookUrl

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', ChatProviderIdEnum.Zulip, {
    webhookUrl: "<WEBHOOK_URL>",
    });

    ```
  </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 ChatProviderIdEnum 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/node` package or directly using the REST API.


file: ./content/docs/platform/integrations/push/(providers)/apns.mdx
# Apple Push Notification Service (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';

[Apple Push Notification Service](https://docs.expo.dev/push-notifications/overview/), as the name suggests, is a notification delivery service provided by Apple.

Apple provides two authentication methods to make a secure connection to APNs. The first is Certificate-Based Authentication (using a .p12 certificate). The second is Token-Based Authentication (using a .p8 key). We'll make use of the **.p8** key.

To enable APNS integration, you need to create an [Apple Developer](https://developer.apple.com/) account with an [Admin role](https://appstoreconnect.apple.com/access/users).

To generate the p8 key for your account:

1. Head over to **Certificates, Identifiers & Profiles > Keys**.
2. Register a new key and give it a name.
3. Enable the Apple Push Notifications service (APNs) checkbox by selecting it.
4. Click the **Continue** button and on the next page, select **Register**.
5. Download the **.p8** key file.

You also need the following to connect to APNs:

1. **Key ID** - This is a 10-character unique identifier for the authentication key. You can find it in the key details section of the newly created key in your Apple developer account.
2. **Team ID** - This is available in your Apple developer account.
3. **Bundle ID** - This is the ID of your app. You can find it in the app info section of your Apple developer account.

The overrides field supports all [Notification payload](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc) values, as shown below:

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {
    abc: 'def', // If the notification is a data notification, the payload will be sent as the data
  },
  overrides: {
    apns: {
      payload: {
        aps: {
          notification: {
            title: 'Test',
            body: 'Test push',
          },
          data: {
            key: 'value',
          },
        },
      },
    },
  },
});
```

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {
    key1: 'val1',
    key2: 'val2', // If the notification is a data notification, the payload will be sent as the data
  },
  overrides: {
    type: 'data',
    apns: {
      headers: {
        'apns-priority': '5',
      },
      payload: {
        aps: {
          alert: {
            'loc-key': 'GAME_PLAY_REQUEST_FORMAT',
            'loc-args': ['Shelly', 'Rick'],
          },
          sound: 'demo.wav',
        },
      },
    },
  },
});
```

Before triggering the notification to a subscriber(user) with push as a step in the workflow, make sure you have added the subscriber's device token as follows:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.APNS, {
    deviceTokens: ['token1', 'token2'],
    });

    ```
  </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": "apns-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.


file: ./content/docs/platform/integrations/push/(providers)/expo-push.mdx
# Expo Push

Learn how to use the Expo push provider to send push notifications using Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[Expo Push](https://docs.expo.dev/push-notifications/overview/) is a notification delivery service provided by Expo.

To enable Expo Push integration, you need to create an [Expo Application Services (EAS)](https://expo.dev/)account and generate an access token in the EAS dashboard.

The overrides field supports all [Message Request](https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format) values. An example of the same follows:

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {
    abc: 'def',
  },
});
```

Before triggering the notification to a subscriber(user) with push as a step in the workflow, make sure you have added the subscriber's device token as follows:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,PushProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.EXPO, {
      deviceTokens: ['token1', 'token2'],
    });

    ```
  </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": "expo-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.


file: ./content/docs/platform/integrations/push/(providers)/fcm.mdx
# Firebase Cloud Messaging (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';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) is a free notification delivery service provided by Google Firebase.

To enable the FCM integration, you need to get your service account key from the [Firebase Console](https://console.firebase.google.com/).

## Generating a Service Account Key JSON

To acquire the account key JSON file for your service account

1. Select your project, and click the gear icon on the top of the sidebar.
2. Head to project settings.
3. Navigate to the service account tab.
4. Click **Generate New Private Key,** then confirm by clicking **Generate Key.**
5. Clicking **Generate Key** downloads the JSON file.

After that, paste the entire JSON file content in the Service Account field of the FCM provider in the integration store on Novu's web dashboard.

Make sure your service account json content 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"
}
```

## FCM Overrides

The overrides field supports apns, android, webpush and 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)       |

## Setting Device Token

Before triggering the notification to a subscriber(user) with push as a step in the workflow, make sure you have added the subscriber's device token as follows:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      PushProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials(
      'subscriberId',
      PushProviderIdEnum.FCM, {
        deviceTokens: ['token1', 'token2']
      },
      'fcm-MnGLxp8uy'
    );
    ```
  </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>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

## SDK Trigger Example

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {
    abc: 'def', // If the notification is a data notification, the payload will be sent as the data
  },
  overrides: {
    fcm: {
      // type: 'data' => will turn this into an FCM data notification, where the payload is sent as a data notification. If the type is not set, you can use the "data" override to send notification messages with optional data payload
      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> Novu uses FCM version V1</Callout>

## Relative Link in Webpush

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">
    ```javascript
    import {
      Novu
    } from "@novu/node";

    const novu = new Novu("<NOVU_SECRET_KEY>");

    novu.trigger("<WORKFLOW_TRIGGER_IDENTIFIER>", {
      to: {
        subscriberId: "<SUBSCRIBER_ID>",
      },
      payload: {
        abc: "def", // If the notification is a data notification, the payload will be sent as the data
      },
      overrides: {
        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>

## FCM Cost

As per Firebase [pricing](https://firebase.google.com/pricing), **Cloud Messaging** product is free of cost to use. If other Firebase products are used, the cost will be charged as per the product.

## FAQs

<Accordions>
  <Accordion title="The registration token is not a valid FCM registration token">
    You may come across an error like so:

    ""Sending message failed due to "The registration token is not a valid FCM registration token""".

    This error happens because of invalid or stale token. The fix for this is to remove old tokens, generate a new token and save it 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 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>


file: ./content/docs/platform/integrations/push/(providers)/onesignal.mdx
# Onesignal

Learn how to use the Onesignal provider to send push notifications using Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[OneSignal](https://onesignal.com/) is a paid push notification service that supports sending messages via both [Apple Push Notification Service](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server) (APNs) as well as [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) (FCM).

To configure the OneSignal integration, you will need an active account which has credentials for APNs, FCM or both, and have access to the `OneSignal App ID` and `Rest API Key` available via your [application's settings page](https://documentation.onesignal.com/docs/keys-and-ids).

## Setting the Device Token

Once OneSignal has been configured with your credentials for APNs/FCM, and the OneSignal SDK has been [set up and configured](https://documentation.onesignal.com/docs/onboarding-with-onesignal#step-1-setup-onesignal-sdk) for your application, your users will begin to be automatically assigned a unique OneSignal [player\_id](https://documentation.onesignal.com/docs/users#player-id) identifier by the SDK.

This identifier allows targeting your user when sending push notifications without having to retrieve the specific Android or iOS device tokens - which are managed by OneSignal.

In order to target the OneSignal user from Novu, you must register the OneSignal `player_id`as the `deviceToken` for your Novu subscriber. This value can be retrieved via the [OneSignal SDK](https://documentation.onesignal.com/docs/users-and-devices#finding-users) for your platform.

Once you have the user's `player_id` value, the `deviceToken` for your Novu subscriber can be set via:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.OneSignal, {
      // Your user's unique 'player_id' from OneSignal
      deviceTokens: [ 'ad0452ca-3ca7-43b5-bf9b-fa93fd322035' ],
    });
    ```
  </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": ["ad0452ca-3ca7-43b5-bf9b-fa93fd322035"],
      "integrationIdentifier": "one-signal-MnGLxp8uy"
    }'
    ```
  </Tab>
</Tabs>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

## SDK Trigger Example

```typescript
novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  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, `External ID` option can be selected in the onesignal integration settings. If `External ID` option is selected, `deviceTokens` stored in subscriber credentials for onesignal provider, will be used as external user ids.

<img src="/images/channels-and-providers/push/onesignal/select-external-id-option.gif" alt="Select external id option" />


file: ./content/docs/platform/integrations/push/(providers)/push-webhook.mdx
# Push Webhook

Learn how to use the Push Webhook provider to send  notifications using Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Push Webhook provider is a bit different different from other push providers as it does not depend on other third party services.
Users can use their own api url as webhook url and novu will make a post request on that webhook url.

## Steps To Configure

1. Go to [integration store](https://dashboard.novu.co/integrations?utm_campaign=docs-push-webhook) and click on `Add a provider` button. Choose `Push` channel and then `Push Webhook` provider.
2. Enter your Webhook URL. For quick testing use [this](https://webhook.site/) website.
3. Enter Secret Hmac Key. Novu will use this secret hmac key to encrypt the data using `HMAC SHA256` algorithm and send the hash as value of `x-novu-signature` header. User can use `x-novu-signature` header to test authenticity of the request. Read more [here](#checking-authenticity)
4. Click on the update button.
5. Update the subscriber credentials using SDK or API. Read more [here](#set-device-token)

<Callout>Your webhook url should accept `POST` request.</Callout>

## Set Device Token

This step is a mandatory step. Other push providers have third party dependencies where a device token can be generated. But in case of push webhook provider, there is no any way to generate device token. Any random string can be used as device token.

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    // PushProviderIdEnum.PushWebhook = push-webhook
    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.PushWebhook, {
      deviceTokens: ['ANY_RANDOM_STRING'],
    });

    ```
  </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>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

## Example paylod sent by novu to webhook url

```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

```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');
  }
}
```

```
```


file: ./content/docs/platform/integrations/push/(providers)/pusher-beams.mdx
# Pusher Beams

Learn how to use the Pusher Beams provider to send push notifications using Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[Pusher Beams](https://pusher.com/beams/) is a cross-platform push notification API service provided by Pusher.

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/).

## Setting the Device Token

Once Pusher Beams instance has been created, and the Pusher Beams SDK has been [set up and configured](https://pusher.com/docs/beams/reference/all-libraries/) for your application, you can associate users with their devices using [Authenticated Users](https://pusher.com/docs/beams/guides/publish-to-specific-user/web/).

This identifier allows targeting your user when sending push notifications without having to retrieve the specific Web, Android or iOS device tokens - which are managed by Pusher Beams.

In order to target the Pusher Beams user from Novu, you must register the Pusher Beams Authenticated Users with their `userId` as the `deviceToken` for your Novu subscriber. This value can be retrieved via [getUserId()](https://pusher.com/docs/beams/reference/web/#getuserid) method from the SDK for your platform.

Once you have the user's `userId` value, the `deviceToken` for your Novu subscriber can be set via:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.PusherBeams, {
      // Your user's unique 'userId' from Pusher Beams
      deviceTokens: ['userId-from-pusher-beams'],
    });

    ```
  </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>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

## SDK Trigger Example

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {
    custom_data: 'custom_data', // the payload will be sent as notification data object. Cannot contain the key "pusher"
  },
});
```


file: ./content/docs/platform/integrations/push/(providers)/pushpad.mdx
# Pushpad

Learn how to use the Pushpad provider to send web push notifications using Novu
        
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[Pushpad](https://pushpad.xyz) is a web push service that supports sending notifications to all major browsers (Chrome, Firefox, Edge, Safari, etc.) via FCM, Mozilla autopush, Windows Push Notification Services and Apple Push Notification service, with just one simple API.

To configure the Pushpad integration, you will need an active account and you need to have a `Pushpad Auth Token` (from the [account settings](https://pushpad.xyz/access_tokens)) and the `Pushpad Project ID` (from the project settings).

## Setting the Device Token

Once Pushpad has been configured with your credentials and the Pushpad SDK has been [set up and installed](https://pushpad.xyz/docs/pushpad_pro_getting_started) on your website, you can [assign a user ID (uid)](https://pushpad.xyz/docs/identifying_users) to the push subscriptions.

This identifier (`uid` or `user ID`) allows targeting a specific browser when sending push notifications.

In order to target the Pushpad user from Novu, you must register the Pushpad `uid` as the `deviceToken` for your Novu subscriber. For example, if you invoked the [Pushpad JavaScript SDK](https://pushpad.xyz/docs/javascript_sdk_reference) with `pushpad('uid', 'user123')`, then `user123` is the user ID for that browser.

Once you have the `uid` value, the `deviceToken` for your Novu subscriber can be set using this code:

<Tabs items={['Node.js', 'cURL']}>
  <Tab value="Node.js">
    ```javascript
    import {
      Novu,
      ChatProviderIdEnum
    } from '@novu/node';

    const novu = new Novu("<NOVU_SECRET_KEY>");

    await novu.subscribers.setCredentials('subscriberId', PushProviderIdEnum.Pushpad, {
      // the user ID (uid) that you used for Pushpad
      deviceTokens: ['user123'],
    });

    ```
  </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>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.

## SDK Trigger Example

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  payload: {},
});
```


file: ./content/docs/platform/integrations/sms/(providers)/46elks.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/africas-talking.mdx
# Africa's 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" />

* 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" />

* 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" />

## 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" />
* 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" />
* 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" />
* 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" />
* 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" />

## 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" />

* 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" />

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


file: ./content/docs/platform/integrations/sms/(providers)/aws-sns.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/azure.mdx
# Azure SMS

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.


file: ./content/docs/platform/integrations/sms/(providers)/bulk-sms.mdx
# BulkSMS

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.


file: ./content/docs/platform/integrations/sms/(providers)/burst-sms.mdx
# BurstSMS

Learn how to use the BurstSMS provider to send sms notifications using Novu
        
You can use the [BurstSMS](https://burstsms.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 BurstSMS provider in the SMS channel, the first step is to create an BurstSMS account and add the personal BurstSMS API key and your BurstSMS API Secret to the BurstSMS integration on the Novu platform.

## Find the API and Secret key

To find the BurstSMS API and Secret key, log into the personal BurstSMS 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 BurstSMS 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 **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 **BurstSMS** in Novu.


file: ./content/docs/platform/integrations/sms/(providers)/clickatell.mdx
# 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" />
  </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" />

    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" />

    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" />
  </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" />

    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" />
  </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.


file: ./content/docs/platform/integrations/sms/(providers)/clicksend.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/firetext.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/gupshup.mdx
# 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>


file: ./content/docs/platform/integrations/sms/(providers)/infobip.mdx
# Infobip - SMS

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.


file: ./content/docs/platform/integrations/sms/(providers)/kannel.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/messagebird.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/nexmo.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/plivo.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/sendchamp.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/simpletexting.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/sms-central.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/sms77.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/sns.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/telnyx.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/termii.mdx
# 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.


file: ./content/docs/platform/integrations/sms/(providers)/twilio.mdx
# 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 messages with Twilio

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
    await novu.trigger("<WORKFLOW_TRIGGER_IDENTIFIER>", {
      to: {
        subscriberId: "<UNIQUE_SUBSCRIBER_IDENTIFIER>",
        phone: "whatsapp:555-4242",
      },
    });
    ```
  </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>


file: ./content/docs/platform/sdks/react-native/hooks/novu-provider.mdx
# NovuProvider

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/api-reference#novu) 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                        |
| backendUrl            | string    | No       | Custom backend 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"
          backendUrl="https://eu.api.novu.co"
          socketUrl="https://eu.ws.novu.co"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    <Callout type="info">
      Read more about [HMAC Encryption](/platform/inbox/react/production#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>


file: ./content/docs/platform/sdks/react-native/hooks/use-counts.mdx
# useCounts

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>


file: ./content/docs/platform/sdks/react-native/hooks/use-notifications.mdx
# useNotifications

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>
      )}
    />
  );
}
```


file: ./content/docs/platform/sdks/react-native/hooks/use-novu.mdx
# useNovu

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/api-reference#novu) 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, isLoading } = 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>
  );
}
```

### Managing Preferences

You can also manage notification preferences:

```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',
      channelPreferences: {
        email: false,
        sms: true,
      },
    });
  };

  return <Button title="Update Preferences" onPress={updatePreferences} />;
}
```

### 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/api-reference).
</Callout>


file: ./content/docs/platform/sdks/react-native/hooks/use-preferences.mdx
# usePreferences

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>


file: ./content/docs/platform/sdks/react/hooks/novu-provider.mdx
# NovuProvider

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/api-reference#novu) 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",
  },
  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', '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"
          backendUrl="https://eu.api.novu.co"
          socketUrl="https://eu.ws.novu.co"
        >
          {/* Your app components */}
        </NovuProvider>
      );
    }
    ```
  </Tab>

  <Tab value="HMAC Encryption">
    <Callout type="info">
      Read more about [HMAC Encryption](/platform/inbox/react/production#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>


file: ./content/docs/platform/sdks/react/hooks/use-counts.mdx
# useCounts

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, and total counts. 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 notification counts:

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

function BellButton() {
  const { counts } = useCounts({ filters: [{ read: false }] });
  const unreadCount = counts?.[0].count ?? 0;

  return (
    <button>
      <BellIcon />
      {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
    </button>
  );
}
```

<Callout type="info">
  The counts are automatically updated in real-time when notifications are
  marked as read/unread or when new notifications arrive.
</Callout>


file: ./content/docs/platform/sdks/react/hooks/use-notifications.mdx
# useNotifications

Learn how to use the useNotifications hook to fetch and manage notifications in your React application
        
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
  type={{
  tags: {
    type: "string[]",
    description: "Filter notifications by tags",
  },
  read: {
    type: "boolean",
    description: "Filter notifications by read status",
  },
  archived: {
    type: "boolean",
    description: "Filter notifications by archived status",
  },
  limit: {
    type: "number",
    description: "Number of notifications to fetch per page",
  },
  onSuccess: {
    type: "(data: Notification[]) => void",
    description:
      "Callback function called when notifications are successfully fetched",
  },
  onError: {
    type: "(error: NovuError) => void",
    description: "Callback function called when an error occurs",
  },
}}
/>

## Return Value

<TypeTable
  type={{
  notifications: {
    type: "Notification[] | undefined",
    description: "Array of notification 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",
  },
  isFetching: {
    type: "boolean",
    description:
      "True during any loading state (initial or refetch), false otherwise",
  },
  refetch: {
    type: "() => Promise<void>",
    description:
      "Function to manually trigger a refetch of the notifications",
  },
  fetchMore: {
    type: "() => Promise<void>",
    description: "Function to load the next page of notifications",
  },
  hasMore: {
    type: "boolean",
    description:
      "True if there are more notifications to load, false otherwise",
  },
  readAll: {
    type: "() => Promise<{ data?: void; error?: NovuError }>",
    description: "Function to mark all notifications as read",
  },
  archiveAll: {
    type: "() => Promise<{ data?: void; error?: NovuError }>",
    description: "Function to archive all notifications",
  },
  archiveAllRead: {
    type: "() => Promise<{ data?: void; error?: NovuError }>",
    description: "Function to archive all read notifications",
  },
}}
/>

## Notification Type

The Notification type from @novu/js includes many properties. Here are the most commonly used ones:

<TypeTable
  type={{
  id: {
    type: "string",
    description: "Unique identifier for the notification",
  },
  subject: {
    type: "string",
    description: "Subject of the notification",
  },
  body: {
    type: "string",
    description: "Body content of the notification",
  },
  isRead: {
    type: "boolean",
    description: "Whether the notification has been read",
  },
  isArchived: {
    type: "boolean",
    description: "Whether the notification has been archived",
  },
  createdAt: {
    type: "string",
    description: "ISO timestamp when the notification was created",
  },
  readAt: {
    type: "string",
    description: "ISO timestamp when the notification was read",
  },
  archivedAt: {
    type: "string",
    description: "ISO timestamp when the notification was archived",
  },
  tags: {
    type: "string[]",
    description: "Tags associated with the notification",
  },
  data: {
    type: "Record<string, unknown>",
    description: "Custom data associated with the notification",
  },
}}
/>

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

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

function FilteredNotifications() {
  const { notifications, isLoading } = useNotifications({
    read: false, // Only unread notifications
    tags: ["important", "urgent"], // Only notifications with these tags
    limit: 20, // Fetch 20 notifications per page
  });

  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, 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 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={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>
  );
}
```

<Callout type="info">
  The notifications list is automatically updated in real-time when new
  notifications arrive or when notifications are marked as read/unread.
</Callout>


file: ./content/docs/platform/sdks/react/hooks/use-novu.mdx
# useNovu

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/api-reference#novu) 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 } from "@novu/js";
import { useNovu } from "@novu/react";

function NotificationItem({ notification }: { notification: Notification }) {
  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>
  );
}
```

### 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 } from "@novu/js";

function NotificationListener() {
  const novu = useNovu();

  useEffect(() => {
    // Handler for new notifications
    const handleNewNotification = ({ result }: { result: Notification }) => {
      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/inbox/headless/api-reference). For a complete
  list of methods and events, refer to the API documentation.
</Callout>


file: ./content/docs/platform/sdks/react/hooks/use-preferences.mdx
# usePreferences

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[] }",
    description: "Filter preferences by tags",
  },
  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/js 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/js";
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:

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

function FilteredPreferences() {
  const { preferences, isLoading } = usePreferences({
    filter: {
      tags: ["important", "marketing"],
    },
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-bold">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>
  );
}
```

### With Channel Groups

You can organize preferences by channel type:

```tsx
import type { Preference, ChannelType } from "@novu/js";
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>