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.
You can set it on Notifications Tool:<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:<VeltNotificationsPanel tabConfig={{
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Document',
enable: false,
},
"all": {
name: 'Custom All',
enable: true,
},
}
} />
Using APIs: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);
You can set it on Notifications Tool:<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:<VeltNotificationsPanel tabConfig={{
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Document',
enable: false,
},
"all": {
name: 'Custom All',
enable: true,
},
}
} />
Using APIs: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);
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: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
React / Next.js
Other Frameworks
Using Props:<VeltNotificationsTool considerAllNotifications={true} />
Using Props:<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.
React / Next.js
Other Frameworks
Hooks:const notificationElement = useNotificationUtils();
useEffect(() => {
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
}, [notificationElement]);
API:const notificationElement = client.getNotificationElement();
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
const notificationElement = Velt.getNotificationElement();
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
setMaxDays
Notifications older than the specified number of days will not be displayed.
Default: 15 days.
<VeltNotificationsTool maxDays={15} />
Using API:const notificationElement = useNotificationUtils();
notificationElement.setMaxDays(15);
<VeltNotificationsTool maxDays={15} />
Using API:const notificationElement = client.getNotificationElement();
notificationElement.setMaxDays(15);
<velt-notifications-tool max-days="15"></velt-notifications-tool>
Using APIs:const notificationElement = Velt.getNotificationElement();
notificationElement.setMaxDays(15);
panelOpenMode
Notificaitons 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.
React / Next.js
Other Frameworks
<VeltNotificationsTool panelOpenMode='sidebar' />
<VeltNotificationsPanel panelOpenMode='sidebar' />
<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.
React / Next.js
Other Frameworks
<VeltNotificationsPanel pageSize={5} />
<VeltNotificationsTool pageSize={5} />
<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.
Using Props:<VeltNotificationsTool readNotificationsOnForYouTab={true} />
<VeltNotificationsPanel readNotificationsOnForYouTab={true} />
Using APIs: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();
Using Props:<VeltNotificationsTool readNotificationsOnForYouTab={true} />
<VeltNotificationsPanel readNotificationsOnForYouTab={true} />
Using APIs: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();
Using Props:<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:<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>
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.
React / Next.js
Other Frameworks
Using props:<VeltNotificationsTool selfNotifications={true} />
<VeltNotificationsPanel selfNotifications={true} />
Using API:const notificationElement = useNotificationUtils();
notificationElement.enableSelfNotifications(); // Enables self notifications.
notificationElement.disableSelfNotifications(); // Disables self notifications.
Using attributes:<velt-notifications-tool self-notifications="true"></velt-notifications-tool>
<velt-notifications-panel self-notifications="true"></velt-notifications-panel>
Using API:const notificationElement = Velt.getNotificationElement();
notificationElement.enableSelfNotifications(); // Enables self notifications.
notificationElement.disableSelfNotifications(); // Disables self notifications.
Data
getNotificationsData
- Get the notifications data for the current user.
- The returned data includes notifications from up to the number of days specified by max days 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
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[]
React / Next.js
Other Frameworks
Using Hooks:// Without query
const notificationData = useNotificationsData();
// With query
const notificationsData = useNotificationsData({ type: 'forYou' });
useEffect(() => {
if (notificationsData) {
console.log(notificationsData);
}
}, [notificationsData]);
Using API: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:subscription?.unsubscribe()
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: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:
{
forYou: 4, // # of unread notifications in the "For You" tab
all: 5 // # of unread notifications in the "All" or "Document" tab
}
React / Next.js
Other Frameworks
Using Hooks:const unreadCount = useUnreadNotificationsCount();
useEffect(() => {
console.log('Unread Count', unreadCount);
}, [unreadCount]);
Using API:const notificationElement = client.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
const notificationElement = Velt.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
Event Subscription
- 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 |
React / Next.js
Other Frameworks
// 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);
});
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 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.
React / Next.js
Other Frameworks
<VeltNotificationsTool onNotificationClick={(notification) => onNotificationClickEvent(notification)} />
<VeltNotificationsPanel onNotificationClick={(notification) => onNotificationClickEvent(notification)} />
const onNotificationClickEvent = (notification) => {
console.log('onNotificationClick: ', notification);
}
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.
React / Next.js
Other Frameworks
const notificationElement = client.getNotificationElement();
notificationElement.markNotificationAsReadById("notificationId");
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.
React / Next.js
Other Frameworks
const notificationElement = useNotificationUtils()
notificationElement.openNotificationsPanel()
notificationElement.closeNotificationsPanel()
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.
React / Next.js
Other Frameworks
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' });
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
- 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.
- Make sure to first enable the settings feature in Velt Console.
enableSettings
- Enable or disable the settings feature for notifications. This allows users to configure their notification preferences.
- Params:
none
- Returns:
void
React / Next.js
Other Frameworks
Using Props:// You can enable this on either the tool or the panel
<VeltNotificationsTool settings={true} />
<VeltNotificationsPanel settings={true} />
Using APIs:const notificationElement = useNotificationUtils();
notificationElement.enableSettings(); // enables the settings feature
notificationElement.disableSettings(); // disables the settings feature
Using Props:<velt-notifications-tool settings="true"></velt-notifications-tool>
<velt-notifications-panel settings="true"></velt-notifications-panel>
Using APIs: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
React / Next.js
Other Frameworks
Using Props:// Enable organization-level settings on the tool
<VeltNotificationsTool
settings={true}
enableSettingsAtOrganizationLevel={true}
/>
// Or on the panel
<VeltNotificationsPanel
settings={true}
enableSettingsAtOrganizationLevel={true}
/>
Using APIs:const notificationElement = useNotificationUtils();
notificationElement.enableSettingsAtOrganizationLevel(); // enable org-level settings
notificationElement.disableSettingsAtOrganizationLevel(); // disable org-level settings
Using Props:<!-- 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: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
Options:
accordion: Settings displayed in expandable accordion
dropdown: Settings displayed in dropdown menu
React / Next.js
Other Frameworks
<VeltNotificationsTool settingsLayout="dropdown" />
<VeltNotificationsPanel settingsLayout="dropdown" />
<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
- This config will automatically generate the settings UI for the user to configure their notification preferences.
- Params:
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:
[
{
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',
}
]
},
]
React / Next.js
Other Frameworks
Using Hook: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: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',
}
]
},
]);
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
React / Next.js
Other Frameworks
const notificationElement = client.getNotificationElement();
notificationElement.muteAllNotifications();
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
- 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
React / Next.js
Other Frameworks
Using Hook:const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
Using API:const notificationElement = useNotificationUtils();
notificationElement.setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
const notificationElement = Velt.getNotificationElement();
notificationElement.setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
getSettings
React / Next.js
Other Frameworks
Using Hook: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:const notificationsElement = useNotificationUtils();
notificationsElement.getSettings().subscribe((settings) => {
console.log('current settings are', settings);
});
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.
This configuration is set at the API Key level in the Velt Console. It applies to all documents in the organization.
Delivery pipeline:
- Delay — Holds the notification for
delaySeconds before proceeding.
- Seen check — If the recipient has already seen the triggering activity during the delay window, the notification is suppressed.
- Batch — Collects additional activities within the batch window before flushing as a single digest.
- Deliver — Sends the notification (or batched digest) to the recipient.
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.