> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Behavior

# Configuration

#### setTabConfig

* Using this config, you can customize the name of the tabs or disable them altogether.
* By default, all the three tabs are enabled.

> [tab] React / Next.js with Hooks
>
> You can set it on Notifications Tool:
>
> ```jsx theme={null}
> <VeltNotificationsTool tabConfig={{
>     "forYou": {
>         name: 'Custom For You',
>         enable: true,
>     },
>     "documents": {
>         name: 'Custom Document',
>         enable: false,
>     },
>     "all": {
>         name: 'Custom All',
>         enable: true,
>     },
> }
> } />
> ```
>
> You can alternatively set it on Notifications Panel if you have directly embedded it:
>
> ```jsx theme={null}
> <VeltNotificationsPanel tabConfig={{
>     "forYou": {
>         name: 'Custom For You',
>         enable: true,
>     },
>     "documents": {
>         name: 'Custom Document',
>         enable: false,
>     },
>     "all": {
>         name: 'Custom All',
>         enable: true,
>     },
> }
> } />
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
>
> ​​const tabConfig = {
> 	"forYou": {
> 		name: 'Custom For You',
> 		enable: true,
> 	},
> 	"documents": {
> 		name: 'Custom Document',
> 		enable: false,
> 	},
> 	"all": {
> 		name: 'Custom All',
> 		enable: true,
> 	},
> };
>
> notificationElement.setTabConfig(tabConfig);
> ```

> [tab] React / Next.js
>
> You can set it on Notifications Tool:
>
> ```jsx theme={null}
> <VeltNotificationsTool tabConfig={{
>     "forYou": {
>         name: 'Custom For You',
>         enable: true,
>     },
>     "documents": {
>         name: 'Custom Document',
>         enable: false,
>     },
>     "all": {
>         name: 'Custom All',
>         enable: true,
>     },
> }
> } />
> ```
>
> You can alternatively set it on Notifications Panel if you have directly embedded it:
>
> ```jsx theme={null}
> <VeltNotificationsPanel tabConfig={{
>     "forYou": {
>         name: 'Custom For You',
>         enable: true,
>     },
>     "documents": {
>         name: 'Custom Document',
>         enable: false,
>     },
>     "all": {
>         name: 'Custom All',
>         enable: true,
>     },
> }
> } />
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
>
> ​​const tabConfig = {
> 	"forYou": {
> 		name: 'Custom For You',
> 		enable: true,
> 	},
> 	"documents": {
> 		name: 'Custom Document',
> 		enable: false,
> 	},
> 	"all": {
> 		name: 'Custom All',
> 		enable: true,
> 	},
> };
>
> notificationElement.setTabConfig(tabConfig);
> ```

> [tab] Other Frameworks
>
> ```js theme={null}
> const tabConfig = {
> 	"forYou": {
> 		name: 'Custom For You',
> 		enable: true,
> 	},
> 	"documents": {
> 		name: 'Custom Document',
> 		enable: false,
> 	},
> 	"all": {
> 		name: 'Custom All',
> 		enable: true,
> 	},
> };
>
> // Set it using Notifications Tool
> const notificationsTool = document.querySelector('velt-notifications-tool');
> notificationsTool?.setAttribute("tab-config", JSON.stringify(tabConfig));
>
> // Or, set it using Notifications Panel
> const notificationsPanel = document.querySelector('velt-notifications-panel');
> notificationsPanel?.setAttribute("tab-config", JSON.stringify(tabConfig));
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
>
> ​​const tabConfig = {
> 	"forYou": {
> 		name: 'Custom For You',
> 		enable: true,
> 	},
> 	"documents": {
> 		name: 'Custom Document',
> 		enable: false,
> 	},
> 	"all": {
> 		name: 'Custom All',
> 		enable: true,
> 	},
> };
>
> notificationElement.setTabConfig(tabConfig);
> ```

#### considerAllNotifications

Controls the notification count and unread indicator for the notification panel. When enabled, the notification count and unread badge include items from all tabs; when disabled (default), they only include items from the “For You” tab.

Default: `false`

> [tab] React / Next.js
>
> **Using Props:**
>
> ```jsx theme={null}
> <VeltNotificationsTool considerAllNotifications={true} />
> ```

> [tab] Other Frameworks
>
> **Using Props:**
>
> ```html theme={null}
> <velt-notifications-tool consider-all-notifications="true"></velt-notifications-tool>
> ```

#### enableCurrentDocumentOnly

Programmatically filters notifications to show only those from the current document. By default it shows notifications for the 15 most recently active documents accessible to the current user in the current organization.

> [tab] React / Next.js
>
> **Hooks:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
>
> useEffect(() => {
>   notificationElement.enableCurrentDocumentOnly();
>   notificationElement.disableCurrentDocumentOnly();
> }, [notificationElement]);
> ```
>
> **API:**
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
> notificationElement.enableCurrentDocumentOnly();
> notificationElement.disableCurrentDocumentOnly();
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.enableCurrentDocumentOnly();
> notificationElement.disableCurrentDocumentOnly();
> ```

#### setMaxDays

Notifications older than the specified number of days will not be displayed.

Default: 15 days.

> [tab] React / Next.js with Hooks
>
> ```jsx theme={null}
> <VeltNotificationsTool maxDays={15} />
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.setMaxDays(15);
> ```

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltNotificationsTool maxDays={15} />
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
> notificationElement.setMaxDays(15);
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
> <velt-notifications-tool max-days="15"></velt-notifications-tool>
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.setMaxDays(15);
> ```

#### panelOpenMode

Notifications Panel opens in one of the following ways:

* `popover`: It opens as a popover on the Notification Tool.
* `sidebar`: It opens as a sidebar from the right edge of the screen.

Default: `popover`.

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltNotificationsTool panelOpenMode='sidebar' />
> <VeltNotificationsPanel panelOpenMode='sidebar' />
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
> <velt-notifications-tool panel-open-mode="sidebar"></velt-notifications-tool>
> <velt-notifications-panel panel-open-mode="sidebar"></velt-notifications-panel>
> ```

#### pageSize

Control initial notification load count.

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltNotificationsPanel pageSize={5} />
> <VeltNotificationsTool pageSize={5} />
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <velt-notifications-panel page-size="5"></velt-notifications-panel>
> <velt-notifications-tool page-size="5"></velt-notifications-tool>
> ```

#### enableReadNotificationsOnForYouTab

* You can control whether read notifications are displayed in the "For You" tab. By default, read notifications are removed from this tab.
* This feature allows you to customize the visibility of read notifications in the "For You" tab, providing more flexibility in how notifications are displayed to users.

Default: `false`.

> [tab] React / Next.js with Hooks
>
> Using Props:
>
> ```jsx theme={null}
> <VeltNotificationsTool readNotificationsOnForYouTab={true} />
> <VeltNotificationsPanel readNotificationsOnForYouTab={true} />
> ```
>
> Using APIs:
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> // Enable to keep read notifications in the for you tab
> notificationElement.enableReadNotificationsOnForYouTab();
> // Disable to hide read notifications in the for you tab
> notificationElement.disableReadNotificationsOnForYouTab();
> ```

> [tab] React / Next.js
>
> Using Props:
>
> ```jsx theme={null}
> <VeltNotificationsTool readNotificationsOnForYouTab={true} />
> <VeltNotificationsPanel readNotificationsOnForYouTab={true} />
> ```
>
> Using APIs:
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
> // Enable to keep read notifications in the for you tab
> notificationElement.enableReadNotificationsOnForYouTab();
> // Disable to hide read notifications in the for you tab
> notificationElement.disableReadNotificationsOnForYouTab();
> ```

> [tab] Other Frameworks
>
> Using Props:
>
> ```html theme={null}
> <velt-notifications-tool read-notifications-on-for-you-tab="true">
> </velt-notifications-tool>
> <velt-notifications-panel read-notifications-on-for-you-tab="true">
> </velt-notifications-panel>
> ```
>
> Using API:
>
> ```html theme={null}
> <script>
>   // Using APIs
>   const notificationElement = Velt.getNotificationElement();
>   // Enable to keep read notifications in the for you tab
>   notificationElement.enableReadNotificationsOnForYouTab();
>   // Disable to hide read notifications in the for you tab
>   notificationElement.disableReadNotificationsOnForYouTab();
> </script>
> ```

#### enableCrossOrganization

* When enabled, notifications from docs user has access to in other organizations are merged into the "For You" tab.
* Only the "For You" feed is supported.
* The `enableCrossOrganization` prop accepts a `boolean`, a `CrossOrganizationConfig` object, or a JSON config string; the `enable-cross-organization` attribute accepts `"true"` / `"false"` or a JSON config string.

Default: `false`.

> [tab] React / Next.js
>
> Using Props:
>
> ```jsx theme={null}
> {/* Enable with defaults */}
> <VeltNotificationsTool enableCrossOrganization={true} />
> <VeltNotificationsPanel enableCrossOrganization={true} />
>
> {/* Enable with custom config */}
> <VeltNotificationsTool enableCrossOrganization={{
>     organizationIds: ['org-1', 'org-2'],
> }} />
> <VeltNotificationsPanel enableCrossOrganization={{
>     organizationIds: ['org-1', 'org-2'],
> }} />
> ```
>
> Using APIs:
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
>
> // Enable with defaults
> notificationElement.enableCrossOrganization();
>
> // Enable with config
> notificationElement.enableCrossOrganization({
>     organizationIds: ['org-1', 'org-2'],
> });
>
> // Disable
> notificationElement.disableCrossOrganization();
>
> // Get current config (one-time)
> const config = notificationElement.getCrossOrganizationConfig();
>
> // Subscribe to config changes
> const subscription = notificationElement.getCrossOrganizationConfig$().subscribe((config) => {
>     console.log('Cross-org config:', config);
> });
> ```

> [tab] Other Frameworks
>
> Using Props:
>
> ```html theme={null}
> <!-- Enable with defaults -->
> <velt-notifications-tool enable-cross-organization="true">
> </velt-notifications-tool>
> <velt-notifications-panel enable-cross-organization="true">
> </velt-notifications-panel>
>
> <!-- Enable with config (JSON string) -->
> <velt-notifications-tool enable-cross-organization='{"organizationIds":["org-1","org-2"]}'>
> </velt-notifications-tool>
> <velt-notifications-panel enable-cross-organization='{"organizationIds":["org-1","org-2"]}'>
> </velt-notifications-panel>
> ```
>
> Using API:
>
> ```html theme={null}
> <script>
>   const notificationElement = Velt.getNotificationElement();
>
>   // Enable with defaults
>   notificationElement.enableCrossOrganization();
>
>   // Enable with config
>   notificationElement.enableCrossOrganization({
>       organizationIds: ['org-1', 'org-2'],
>   });
>
>   // Disable
>   notificationElement.disableCrossOrganization();
>
>   // Get current config (one-time)
>   const config = notificationElement.getCrossOrganizationConfig();
>
>   // Subscribe to config changes
>   const subscription = notificationElement.getCrossOrganizationConfig$().subscribe((config) => {
>       console.log('Cross-org config:', config);
>   });
> </script>
> ```

**`CrossOrganizationConfig` fields:** See [`CrossOrganizationConfig`](https://velt.dev/docs/api-reference/sdk/models/data-models#crossorganizationconfig) for the full type definition.

| Property | Type | Default | Notes |
| - | - | - | - |
| `enabled` | `boolean` | `true` | Set to `false` to disable (equivalent to calling `disableCrossOrganization()`). |
| `organizationIds` | `string[]` | None | Allowlist; when omitted, all indexed orgs are eligible. |
| `excludeOrganizationIds` | `string[]` | None | Additional orgs to exclude. Current org always excluded. |
| `feeds` | `('forYou' \| 'all')[]` | None | Only `'forYou'` is supported; `'all'` is ignored with a warning. |

> [!NOTE]
>
> Passing `{ enabled: false }` as the config to `enableCrossOrganization()` routes to disable. Passing `null` or calling without arguments opts in with all defaults.

#### getCrossOrganizationConfig

Retrieve the current cross-organization configuration. Use `getCrossOrganizationConfig$()` to subscribe to ongoing changes.

> [tab] React / Next.js with Hooks
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
>
> // One-time read
> const config = notificationElement.getCrossOrganizationConfig();
>
> // Subscribe to changes
> const subscription = notificationElement.getCrossOrganizationConfig$().subscribe((config) => {
>     console.log('Cross-org config updated:', config);
> });
> ```

> [tab] React / Next.js
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
>
> // One-time read
> const config = notificationElement.getCrossOrganizationConfig();
>
> // Subscribe to changes
> const subscription = notificationElement.getCrossOrganizationConfig$().subscribe((config) => {
>     console.log('Cross-org config updated:', config);
> });
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <script>
>   const notificationElement = Velt.getNotificationElement();
>
>   // One-time read
>   const config = notificationElement.getCrossOrganizationConfig();
>
>   // Subscribe to changes
>   const subscription = notificationElement.getCrossOrganizationConfig$().subscribe((config) => {
>       console.log('Cross-org config updated:', config);
>   });
> </script>
> ```

#### enableUserScopedNotifications

* By default, the "For You" tab and the unread count are derived from the organization's 15 most recently active documents. An unread notification whose document falls outside that window is not fetched, so it disappears from the tab and the count until the document becomes active again.
* When enabled, the SDK also fetches the signed-in user's newest notifications for the current organization directly, independent of that window. Those notifications are merged into the "For You" store, deduped by `notificationId`, and merged additively into the "All" tab.
* The `enableUserScopedNotifications` prop accepts a `boolean`, a `UserScopedNotificationsConfig` object, or a JSON config string; the `enable-user-scoped-notifications` attribute accepts `"true"` / `"false"` or a JSON config string.

Default: `false`.

> [tab] React / Next.js
>
> Using Props:
>
> ```jsx theme={null}
> {/* Enable with the default limit of 25 */}
> <VeltNotificationsTool enableUserScopedNotifications={true} />
> <VeltNotificationsPanel enableUserScopedNotifications={true} />
>
> {/* Enable with a custom limit */}
> <VeltNotificationsTool enableUserScopedNotifications={{
>     limit: 60,
> }} />
> <VeltNotificationsPanel enableUserScopedNotifications={{
>     limit: 60,
> }} />
> ```
>
> Using APIs:
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
>
> // Enable with the default limit of 25
> notificationElement.enableUserScopedNotifications();
>
> // Enable with a custom limit
> notificationElement.enableUserScopedNotifications({
>     limit: 60,
> });
>
> // Disable, keeping the configured limit
> notificationElement.disableUserScopedNotifications();
> ```

> [tab] Other Frameworks
>
> Using Props:
>
> ```html theme={null}
> <!-- Enable with the default limit of 25 -->
> <velt-notifications-tool enable-user-scoped-notifications="true">
> </velt-notifications-tool>
> <velt-notifications-panel enable-user-scoped-notifications="true">
> </velt-notifications-panel>
>
> <!-- Enable with a custom limit (JSON string) -->
> <velt-notifications-tool enable-user-scoped-notifications='{"limit":60}'>
> </velt-notifications-tool>
> <velt-notifications-panel enable-user-scoped-notifications='{"limit":60}'>
> </velt-notifications-panel>
> ```
>
> Using APIs:
>
> ```html theme={null}
> <script>
>   const notificationElement = Velt.getNotificationElement();
>
>   // Enable with the default limit of 25
>   notificationElement.enableUserScopedNotifications();
>
>   // Enable with a custom limit
>   notificationElement.enableUserScopedNotifications({
>       limit: 60,
>   });
>
>   // Disable, keeping the configured limit
>   notificationElement.disableUserScopedNotifications();
> </script>
> ```

**`UserScopedNotificationsConfig` fields:** See [`UserScopedNotificationsConfig`](https://velt.dev/docs/api-reference/sdk/models/data-models#userscopednotificationsconfig) for the full type definition.

| Property | Type | Default | Notes |
| - | - | - | - |
| `enabled` | `boolean` | `true` | Set to `false` to disable (equivalent to calling `disableUserScopedNotifications()`). Keeps the configured `limit`. |
| `limit` | `number` | `25` | Maximum user-scoped notifications fetched. Clamped to `[1, 200]`; non-numeric, non-finite, or values below `1` fall back to `25`. |

**Behavior:**

* Setting the prop and calling the API method write to the same setting, so the last write wins. Drive it from one place only, and note that setting it on either `VeltNotificationsTool` or `VeltNotificationsPanel` is equivalent.
* Calling `enableUserScopedNotifications()` before initialization or `setDocument()` is safe. The setting latches and takes effect on the first full fetch after the organization pipeline initializes.
* The user-scoped fetch runs on full fetches only, and is suppressed under `currentDocumentOnly`. Narrowing the scope explicitly wins over this setting.
* Switching organization or document clears the stores as before, and the next full fetch re-sends the setting, so user-scoped notifications never carry across organizations.
* In the "For You" store, a notification that arrives through both the per-document path and the user-scoped path appears once. In the "All" tab, document notifications win on ID collision and user-scoped notifications outrank cross-organization ones; the result is sorted by timestamp descending.
* Cross-organization "For You" behavior and the `maxNotificationDays` retention bound are unchanged.
* The fetch requires matching backend support. Against an older backend it falls back to the windowed behavior instead of failing.

> [!NOTE]
>
> Passing `{ enabled: false }` as the config to `enableUserScopedNotifications()` routes to disable and keeps the previously configured `limit`. Passing `null` or calling without arguments opts in with all defaults.

> [!NOTE]
>
> The first load after opting in at a busy organization surfaces previously invisible unread notifications in one batch. This is the intended correction. The unread count is capped at the configured `limit`.

#### disableUserScopedNotifications

Turn the user-scoped fetch back off. The "For You" tab and the unread count return to the recently-active-documents window with no other change.

> [tab] React / Next.js
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.disableUserScopedNotifications();
> ```

> [tab] Other Frameworks
>
> ```js theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.disableUserScopedNotifications();
> ```

#### enableSelfNotifications

* By default notifications api and components exclude notifications where the current user is the action user.
* This feature allows you to enable self notifications.

Default: `false`.

> [tab] React / Next.js
>
> **Using props:**
>
> ```jsx theme={null}
> <VeltNotificationsTool selfNotifications={true} />
> <VeltNotificationsPanel selfNotifications={true} />
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.enableSelfNotifications(); // Enables self notifications.
> notificationElement.disableSelfNotifications(); // Disables self notifications.
> ```

> [tab] Other Frameworks
>
> **Using attributes:**
>
> ```html theme={null}
> <velt-notifications-tool self-notifications="true"></velt-notifications-tool>
> <velt-notifications-panel self-notifications="true"></velt-notifications-panel>
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.enableSelfNotifications(); // Enables self notifications.
> notificationElement.disableSelfNotifications(); // Disables self notifications.
> ```

# Data

#### getNotificationsData

* Get the notifications data for the current user.
* Velt returns a notification for a private comment only to users who can see that comment. [Learn more →](https://velt.dev/docs/async-collaboration/notifications/overview.md#notifications-for-private-comments)

> [!NOTE]
>
> * The returned data includes notifications from up to the number of days specified by [max days](#setmaxdays) configuration.
> * "For You" tab: By default only the latest 50 notifications are fetched. This is done to reduce clutter and noise.
> * "Document" and "All" tabs: By default, up to 15 notifications are fetched for each of the 15 most recently active documents accessible to the current user. This highlights the most relevant and recent activity.

* Params:
  * query: Optional. [`GetNotificationsDataQuery`](https://velt.dev/docs/api-reference/sdk/models/data-models#getnotificationsdataquery)
    * `type`: Filter for notification type: all, for you, or documents.
      * `forYou`: returns notifications where the current user is involved.
      * `all` / `documents`: returns all notifications from the documents the user has access to.

* Returns [`Notification[]`](https://velt.dev/docs/api-reference/sdk/models/data-models#notification)

> [tab] React / Next.js
>
> **Using Hooks:**
>
> ```jsx theme={null}
> // Without query
> const notificationData = useNotificationsData();
>
> // With query
> const notificationsData = useNotificationsData({ type: 'forYou' });
>
> useEffect(() => {
>   if (notificationsData) {
>     console.log(notificationsData);
>   }
> }, [notificationsData]);
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationElement = client.getNotificationElement();
>
> // Without query
> let subscription = notificationElement.getNotificationsData().subscribe((notifications) => {
>     console.log("Notifications: ", notifications)
> });
>
> // With query
> let subscription = notificationElement.getNotificationsData({ type: 'forYou' }).subscribe((notifications) => {
>     console.log("Notifications: ", notifications)
> });
> ```
>
> To unsubscribe from the subscription:
>
> ```jsx theme={null}
> subscription?.unsubscribe()
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
>
> // Without query
> let subscription = notificationElement.getNotificationsData().subscribe((notifications) => {
>     console.log("Notifications: ", notifications)
> });
>
> // With query
> let subscription = notificationElement.getNotificationsData({ type: 'forYou' }).subscribe((notifications) => {
>     console.log("Notifications: ", notifications)
> });
>
> ```
>
> To unsubscribe from the subscription:
>
> ```jsx theme={null}
> subscription?.unsubscribe()
> ```

#### getUnreadNotificationsCount

* Retrieve the count of unread notifications, which includes a breakdown for different tabs.
* The 'Document' tab is not included in the response because it contains all the notifications present in the 'All' tab.

**Sample response:**

```javascript theme={null}
{ 
  forYou: 4, // # of unread notifications in the "For You" tab
  all: 5     // # of unread notifications in the "All" or "Document" tab
}
```

> [tab] React / Next.js
>
> Using Hooks:
>
> ```jsx theme={null}
> const unreadCount = useUnreadNotificationsCount();
>
> useEffect(() => {
>   console.log('Unread Count', unreadCount);
> }, [unreadCount]);
> ```
>
> Using API:
>
> ```javascript theme={null}
> const notificationElement = client.getNotificationElement();
> notificationElement.getUnreadNotificationsCount().subscribe((data) => {
>   console.log('Unread notifications count:', data);
> });
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.getUnreadNotificationsCount().subscribe((data) => {
>   console.log('Unread notifications count:', data);
> });
> ```

# Event Subscription

#### on

* Subscribe to Notification Events. Here is the list of events you can subscribe to and the event objects you will receive.

| Event Type | Description | Event Object |
| - | - | - |
| `settingsUpdated` | Triggered when the settings are updated by the user using UI or the API | [SettingsUpdatedEvent](https://velt.dev/docs/api-reference/sdk/models/data-models.md#settingsupdatedevent) |

> [tab] React / Next.js
>
> ```jsx theme={null}
> // Hook
> const settingsUpdatedEvent  = useNotificationEventCallback('settingsUpdated')
>
> useEffect(() => {
>     console.log('settingsUpdatedEvent', settingsUpdatedEvent)
> }, [settingsUpdatedEvent])
>
>
> // API Method
> const notificationElement = useNotificationUtils();
> notificationElement.on('settingsUpdated').subscribe((event) => {
>      console.log('settingsUpdatedEvent', event);
> });
>
> ```

> [tab] Other Frameworks
>
> ```js theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.on('settingsUpdated').subscribe((event) => {
>     console.log('settingsUpdatedEvent', event);
> });
> ```

#### onNotificationClick

* The `onNotificationClick` event fires when a notification is clicked in the Notifications Panel.
* It returns a [`Notification`](https://velt.dev/docs/api-reference/sdk/models/data-models#notification) object with details about the clicked notification.
* Listen to this event via either the Notification Tool or the Notification Panel, but not both.
* Use this event to implement custom actions in response to notification clicks, such as navigating to a specific part of the app.

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltNotificationsTool onNotificationClick={(notification) => onNotificationClickEvent(notification)} />
>
> <VeltNotificationsPanel onNotificationClick={(notification) => onNotificationClickEvent(notification)} />
>
> const onNotificationClickEvent = (notification) => {
> 	console.log('onNotificationClick: ', notification);
> }
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
>   const notificationsTool = document.querySelector('velt-notifications-tool');
> 	notificationsTool?.addEventListener('onNotificationClick', (event) => {
> 	  console.log('onNotificationClick from Tool: ', event.detail);
>   });
>
>   const notificationsPanel = document.querySelector('velt-notifications-panel');
> 	notificationsPanel?.addEventListener('onNotificationClick', (event) => {
> 	  console.log('onNotificationClick from Panel: ', event.detail);
>   });
> ```

# Actions

#### markNotificationAsReadById

* Mark a single notification as read using its notificationId.
* The notification will be marked as read in all tabs.

> [tab] React / Next.js
>
> ```javascript theme={null}
> const notificationElement = client.getNotificationElement();
> notificationElement.markNotificationAsReadById("notificationId");
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.markNotificationAsReadById("notificationId");
> ```

#### openNotificationsPanel

* Programmatically open or close the notification panel using the provided APIs.
* This will not work if you have embedded the notification panel in your app.

> [tab] React / Next.js
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils()
> notificationElement.openNotificationsPanel()
> notificationElement.closeNotificationsPanel()
>
> ```

> [tab] Other Frameworks
>
> ```jsx theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.openNotificationsPanel();
> notificationElement.closeNotificationsPanel();
> ```

#### setAllNotificationsAsRead

* Mark all notifications as read, either globally or for a specific tab.
* Using 'all' or 'document' as the `tabId` marks all notifications as read across all tabs (equivalent to calling `setAllNotificationsAsRead()` without arguments).
* Using 'for-you' as the `tabId` only marks notifications in the 'for-you' tab as read.

> [tab] React / Next.js
>
> ```javascript theme={null}
> const notificationElement = client.getNotificationElement();
>
> // Mark all notifications as read
> notificationElement.setAllNotificationsAsRead();
>
> // Mark all notifications as read for a specific tab
> notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
> notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
> notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
>
> // Mark all notifications as read
> notificationElement.setAllNotificationsAsRead();
>
> // Mark all notifications as read for a specific tab
> notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
> notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
> notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
> ```

# Notification Settings

> [!WARNING]
>
> 1. This feature currently only updates the settings for the current user in the current Velt document. If you are using multiple documents or folders, the settings will apply to the root document.
> 2. Make sure to first enable the settings feature in [Velt Console](https://console.velt.dev/dashboard/config/notification).

#### enableSettings

* Enable or disable the settings feature for notifications. This allows users to configure their notification preferences.
* Params: `none`
* Returns: `void`

> [tab] React / Next.js
>
> **Using Props:**
>
> ```jsx theme={null}
> // You can enable this on either the tool or the panel
> <VeltNotificationsTool settings={true} />
> <VeltNotificationsPanel settings={true} />
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.enableSettings(); // enables the settings feature
> notificationElement.disableSettings(); // disables the settings feature
> ```

> [tab] Other Frameworks
>
> **Using Props:**
>
> ```html theme={null}
> <velt-notifications-tool settings="true"></velt-notifications-tool>
> <velt-notifications-panel settings="true"></velt-notifications-panel>
> ```
>
> **Using APIs:**
>
> ```js theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.enableSettings(); // enables the settings feature
> notificationElement.disableSettings(); // disables the settings feature
> ```

#### enableSettingsAtOrganizationLevel

Enable organization-level notification settings. When enabled, settings apply to all documents in the organization instead of per-document.

**Params:** `none`
**Returns:** `void`

> [tab] React / Next.js
>
> **Using Props:**
>
> ```jsx theme={null}
> // Enable organization-level settings on the tool
> <VeltNotificationsTool
>   settings={true}
>   enableSettingsAtOrganizationLevel={true}
> />
>
> // Or on the panel
> <VeltNotificationsPanel
>   settings={true}
>   enableSettingsAtOrganizationLevel={true}
> />
> ```
>
> **Using APIs:**
>
> ```jsx theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.enableSettingsAtOrganizationLevel(); // enable org-level settings
> notificationElement.disableSettingsAtOrganizationLevel(); // disable org-level settings
> ```

> [tab] Other Frameworks
>
> **Using Props:**
>
> ```html theme={null}
> <!-- Enable organization-level settings on the tool -->
> <velt-notifications-tool
>   settings="true"
>   enable-settings-at-organization-level="true">
> </velt-notifications-tool>
>
> <!-- Or on the panel -->
> <velt-notifications-panel
>   settings="true"
>   enable-settings-at-organization-level="true">
> </velt-notifications-panel>
> ```
>
> **Using APIs:**
>
> ```js theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.enableSettingsAtOrganizationLevel(); // enable org-level settings
> notificationElement.disableSettingsAtOrganizationLevel(); // disable org-level settings
> ```

#### settingsLayout

Control how notification settings are displayed. Two layout modes are available.

Default: `accordion`

**Type:** [`NotificationSettingsLayout`](https://velt.dev/docs/api-reference/sdk/models/data-models#notificationsettingslayout)

**Options:**

* `accordion`: Settings displayed in expandable accordion
* `dropdown`: Settings displayed in dropdown menu

> [tab] React / Next.js
>
> ```jsx theme={null}
> <VeltNotificationsTool settingsLayout="dropdown" />
> <VeltNotificationsPanel settingsLayout="dropdown" />
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <velt-notifications-tool settings-layout="dropdown"></velt-notifications-tool>
> <velt-notifications-panel settings-layout="dropdown"></velt-notifications-panel>
> ```

#### setSettingsInitialConfig

* Set the initial default configuration for notification settings. This defines the available settings options and their default values.
* By default we have config added for inbox (in-app notifications) and email.
* You can extend this to add more channels where you intend to send notifications to your users. eg: slack, jira, asana, linear etc.
* If you do extend it to other custom channels, you will need to send the data to those channels yourself using our webhooks. [Learn more](https://velt.dev/docs/webhooks/basic.md)
* This config will automatically generate the settings UI for the user to configure their notification preferences.
* Params: [`NotificationInitialSettingsConfig[]`](https://velt.dev/docs/api-reference/sdk/models/data-models#notificationinitialsettingsconfig)
  * Here is what the value types mean:
    * `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document.
    * `MINE`: Subscribes the user to notifications that are related to the current user on the current document.
    * `NONE`: Subscribes the user to no notifications on this channel on the current document.
* Returns: `void`

Default:

```js theme={null}
[
  {
    name: 'Inbox',
    id: 'inbox',
    default: 'ALL',
    enable: true,
    values: [
      {
        name: 'All',
        id: 'ALL',
      },
      {
        name: 'Only Involved',
        id: 'MINE',
      },
      {
        name: 'None',
        id: 'NONE',
      }
    ]
  },
  {
    name: 'Email',
    id: 'email',
    default: 'MINE',
    enable: true,
    values: [
      {
        name: 'All',
        id: 'ALL',
      },
      {
        name: 'Only Involved',
        id: 'MINE',
      },
      {
        name: 'None',
        id: 'NONE',
      }
    ]
  },
]
```

> [tab] React / Next.js
>
> **Using Hook:**
>
> ```jsx theme={null}
> const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
> setSettingsInitialConfig([
>   {
>     name: 'Inbox',
>     id: 'inbox',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Slack',
>     id: 'slack',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Linear',
>     id: 'linear',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
> ]);
> ```
>
> **Using API:**
>
> ```javascript theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.setSettingsInitialConfig([
>   {
>     name: 'Inbox',
>     id: 'inbox',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Slack',
>     id: 'slack',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Linear',
>     id: 'linear',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
> ]);
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.setSettingsInitialConfig([
>   {
>     name: 'Inbox',
>     id: 'inbox',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Slack',
>     id: 'slack',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
>   {
>     name: 'Linear',
>     id: 'linear',
>     default: 'MINE',
>     enable: true,
>     values: [
>       {
>         name: 'All',
>         id: 'ALL',
>       },
>       {
>         name: 'Only Involved',
>         id: 'MINE',
>       },
>       {
>         name: 'None',
>         id: 'NONE',
>       }
>     ]
>   },
> ]);
> ```

#### muteAllNotifications

* Mutes all notifications across all the channels for the current user in this current document.
* In case of multiple documents or folders, this will mute all notifications for the user in the root document.
* Params: `none`
* Returns: `void`

> [tab] React / Next.js
>
> ```javascript theme={null}
> const notificationElement = client.getNotificationElement();
> notificationElement.muteAllNotifications();
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.muteAllNotifications();
> ```

#### setSettings

* Update notification settings configuration for the current user.
* Here you need to provide the id of the channel config and its value id.
* Params: [`NotificationSettingsConfig`](https://velt.dev/docs/api-reference/sdk/models/data-models#notificationsettingsconfig)
* Here is what the value types mean:
  * `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document.
  * `MINE`: Subscribes the user to notifications that are related to the current user on the current document.
  * `NONE`: Subscribes the user to no notifications on this channel on the current document.
* Returns: `void`

> [tab] React / Next.js
>
> **Using Hook:**
>
> ```jsx theme={null}
> const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
> setSettings({
>   'email': 'MINE',
>   'inbox': 'NONE',
>   'slack': 'ALL',
>   'linear': 'MINE'
> });
> ```
>
> **Using API:**
>
> ```javascript theme={null}
> const notificationElement = useNotificationUtils();
> notificationElement.setSettings({
>   'email': 'MINE',
>   'inbox': 'NONE',
>   'slack': 'ALL',
>   'linear': 'MINE'
> });
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationElement = Velt.getNotificationElement();
> notificationElement.setSettings({
>   'email': 'MINE',
>   'inbox': 'NONE',
>   'slack': 'ALL',
>   'linear': 'MINE'
> });
> ```

#### getSettings

* Get the current notification settings configuration for the user on the current document.
* Params: `none`
* Returns: [`Observable<NotificationSettingsConfig>`](https://velt.dev/docs/api-reference/sdk/models/data-models#notificationsettingsconfig)

> [tab] React / Next.js
>
> **Using Hook:**
>
> ```jsx theme={null}
> const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
> // setSettingsInitialConfig will set the default settings for the notifications.
> // setSettings will update the settings for the notifications in the server.
> // settings will return the current settings for the notifications. Initially it will be null and will be updated when the settings are fetched.
> ```
>
> **Using API:**
>
> ```jsx theme={null}
> const notificationsElement = useNotificationUtils();
> notificationsElement.getSettings().subscribe((settings) => {
>   console.log('current settings are', settings);
> });
> ```

> [tab] Other Frameworks
>
> ```javascript theme={null}
> const notificationsElement = Velt.getNotificationElement();
> notificationsElement.getSettings().subscribe((settings) => {
>   console.log('current settings are', settings);
> });
> ```

# Notification Delivery

#### Batching and Delay Configuration

Configure a delay-and-batch pipeline for notification delivery. When enabled, notifications pass through a delay hold, a seen check, and optional batching before being delivered.

> [!NOTE]
>
> This configuration is set at the API Key level in the [Velt Console](https://console.velt.dev/dashboard/config/notification). It applies to all documents in the organization.

**Delivery pipeline:**

1. **Delay:** Holds the notification for `delaySeconds` before proceeding.
2. **Seen check:** If the recipient has already seen the triggering activity during the delay window, the notification is suppressed.
3. **Batch:** Collects additional activities within the batch window before flushing as a single digest.
4. **Deliver:** Sends the notification (or batched digest) to the recipient.

> [!WARNING]
>
> Webhooks and workflow triggers always fire immediately and are never subject to delay or batching.

**Document-level and user-level batching operate independently.** A notification can accumulate in both windows simultaneously; whichever window closes first (by time or `maxActivities`) triggers a flush for that scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.