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 and webhookUrl 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
email	string	false	[e-mail].
phone	string	false	[phone]
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": "[[e-mail]](mailto:[e-mail])",
  "phone": "[phone]"
  "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.

• Node.js
• PHP

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

const novu = new Novu('<NOVU_API_KEY>');

await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
    to: {
        subscriberId: '111',
        email: '[e-mail]',
        firstName: 'John',
        lastName: 'Doe',
        phone: '[phone]',
    },
    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.

• Node.js
• PHP

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

const novu = new Novu('<NOVU_API_KEY>');

await novu.subscribers.identify('111', {
  email: '[e-mail]',
  firstName: 'John',
  lastName: 'Doe',
  phone: '[phone]',
  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.