Subscribers
In Novu, we call the entities designed to receive notifications as Subscribers
. Each subscriber is unique and identified by a unique subscriberId.
We recommend using the internal unique id your application uses for a specific
user as the subscriberId
.
Each subscriber has the following data points:
- User Data - Data stored in the subscriber object that you can easily access in your notification templates. This contains basic info such as first name, last name, avatar, locale, email, and phone. 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, nationality, height, etc can also be stored in the
data
field using key-value pairs. - Channel Specific Credentials -
deviceTokens
required to send push notifications andwebhookUrl
for chat channel providers can also be stored.
Subscriber attributes
Field | Type | Required | Example |
---|---|---|---|
subscriberId | string | true | b0bea066-f5fe-11ed-b67e-0242ac120002 |
firstName | string | false | John |
lastName | string | false | Doe |
string | false | john.doe@domain.org. | |
phone | string | false | +13603963366 |
locale | string | false | en |
avatar | string | false | https://example.com/images/avatar.jpg |
data | object | false | {"key": "value"} |
Subscriber response schema
Novu subscriber object
{
"_id": "NOVU_GENERATED_SUBSCRIBER_ID",
"_organizationId": "NOVU_GENERATED_ORG_ID",
"_environmentId": "NOVU_GENERATED_ENV_ID",
"firstName": "John",
"lastName": "Doe",
"subscriberId": "subscriberId",
"email": "[john.doe@org.com](mailto:john.doe@org.com)",
"phone": "+98712345670"
"data": {
"custome_key_1" : "custom_value_1",
"custome_key_2" : "custom_value_2"
}
"channels": [
{
"credentials": {
"deviceTokens": [
"token1",
"token2"
]
},
"_integrationId": "NOVU_GENERATED_INTEGRATION_ID",
"providerId": "fcm"
},
{
"credentials": {
"webhookUrl": "URL"
},
"_integrationId": "NOVU_GENERATED_INTEGRATION_ID",
"providerId": "discord"
}
],
"deleted": false,
"createdAt": "2022-10-13T17:40:53.231Z",
"updatedAt": "2022-10-13T17:41:53.238Z",
"__v": 0,
"isOnline": false,
"lastOnlineAt": "2022-10-13T17:41:53.238Z",
"avatar": "AVATAR_URL",
"id": "NOVU_GENERATED_SUBSCRIBER_ID"
}
Creating a subscriber
We support creating new subscriber using two ways, Ahead of Trigger
means adding subscribers before triggering notification or Just-in-time
means sending complete subscriber data in to
field while triggering.
Just-in-time
A non-existing subscriber can be added by sending subscriber data in to
field of the trigger method. If any subscriber with provided subscriberId
does not exists, a new subscriber will be created. In this case, subscriber will be created first and then the trigger will be executed synchronously.
import { Novu } from '@novu/node';
const novu = new Novu('<NOVU_SECRET_KEY>');
await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
to: {
subscriberId: '111',
email: 'john.doe@domain.com',
firstName: 'John',
lastName: 'Doe',
phone: '+13603963366',
},
payload: {
customVariable: 'variableValue',
organization: {
logo: 'https://organization.com/logo.png',
},
},
});
You can also pass only the subscriberId
during a request, and hydrate the data directly from your database or other sources during the trigger execution. This is useful when you don’t want to store all the subscriber data in Novu.
Migration (Optional)
Create the subscriber and then trigger the notification to this subscriber. Here subscriberId
is the required field and other fields are optional.
import { Novu } from '@novu/node';
const novu = new Novu('<NOVU_SECRET_KEY>');
await novu.subscribers.identify('111', {
email: 'john.doe@domain.com',
firstName: 'John',
lastName: 'Doe',
phone: '+13603963366',
avatar: 'https://example.com/images/avatar.jpg',
locale: 'en-US',
data: { customKey1: 'customVal1', customKey2: 'customVal2' },
});
Novu will create a subscriber if one does not exist and will update the existing subscriber based on the identify
payload. You can call this function during registration or signup to make sure the subscriber data is up-to-date, if you wish to save additional attributes with a subscriber, you can pass additional custom data in the data field as key-value pairs.
Bulk Subscriber Creation
You can create subscribers in bulk (up to 500 at once) via the SDKs or API.
Export Subscribers
Currently, Novu does not support exporting subscribers. However, Get Subscribers API can be used to fetch subscribers
Steps:
mkdir export_novu_subscribers
cd export_novu_subscribers
- create
fetch_subscribers.js
file and copy export_novu_subscribers.js gist code into this file. npm init -y
npm install axios fast-csv fs
- Run
node fetch_subscribers.js
- Subscribers are exported in
subscribers.csv
file
Was this page helpful?