diff --git a/content/docs/platform/concepts/notifications.mdx b/content/docs/platform/concepts/notifications.mdx index 1d187d3fd..0f8328b5a 100644 --- a/content/docs/platform/concepts/notifications.mdx +++ b/content/docs/platform/concepts/notifications.mdx @@ -4,7 +4,7 @@ description: 'Learn about the Novu notifications lifecycle and the key entities icon: 'BellRing' --- -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. +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, they’re seeing 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. @@ -20,31 +20,29 @@ A notification doesn't exist in isolation, it’s the result of a sequence of in ### 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). +The notification lifecycle starts with an event, this event represents something meaningful that has happened in your application, such as a new comment, user sign-up, or password reset request. -Each event contains: -- A name that maps to a specific workflow (user_signed_up) +These events are how your application communicates to Novu that it is time to send a particular notification to certain subscribers. + +Each event in Novu 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. +This event that was triggered in your application, in turn triggers the workflow(s) attached to it. This workflow determines the delivery channels to be used to send the notification to the user and also the format in which the notification content will be displayed in the various channels. -Refer to the [Workflows documentation](/platform/concepts/workflows). +This is covered in depth in the [Workflows concept documentation](/platform/concepts/workflows). ### 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: +Once the workflow begins, Novu creates a notification for each subscriber included in the event. +Think of it as the container for all activity triggered by a single event for a single user. It contains a full record of what happened from the moment the event was triggered to when one or more messages were delivered or failed to deliver. + +It includes: - The subscriber details - The workflow (template) used - The event payload @@ -52,52 +50,12 @@ Once the workflow starts executing, Novu creates a notification for each subscri - 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. - - - In simpler terms, when a workflow is triggered to a subscriber, it creates an event. One event is one notification. - +All these properties can be seen from the [Notification API](https://docs.novu.co/api-reference/notifications/list-all-events) response and are also displayed in the Novu dashboard’s [Activity Feed](https://dashboard.novu.co/activity-feed) for visual traceability. ### 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 - -Each message has a unique ID and status, learn more about this in the [Messages API](/api-reference/messages/message-schema). - -## 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? +Message is the final **phase** in the notification lifecycle. It is the actual notification content that is sent to the subscriber from the workflow. -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. +Messages are delivered to your users using any or all of the channels defined in your workflow, and each message can be customized for each channel. -### 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. \ No newline at end of file +Messages are live entities and can be tracked in real-time, with full visibility into channels used, delivery status and other important properties from the [Message API](https://docs.novu.co/api-reference/notifications/list-all-events) response. \ No newline at end of file diff --git a/public/images/concepts/notifications/notification-life-cycle.png b/public/images/concepts/notifications/notification-life-cycle.png index a57881ce4..cc805cd43 100644 Binary files a/public/images/concepts/notifications/notification-life-cycle.png and b/public/images/concepts/notifications/notification-life-cycle.png differ