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_SECRET_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',
        },
    },
});

When triggering the workflow, you must specify all required to fields per the channels in the workflow. For example, if an email step is included in the workflow, then the to.email field must be specified. Similarly if an SMS step is included, the to.phone field must be specified.

If you are defining workflows with code, you can use the subscriberId to hydrate subscriber data directly from your database or other sources during workflow execution. This is useful when you don’t want to store all the subscriber data in Novu.

For example, you may have a welcome onboarding email that you trigger immediately after a user signs up, with the email only sent 1 hour after signup:

import { workflow } from '@novu/framework';
import { userDb } from '../db/userDb';

export const welcomeEmail = workflow('welcome-email', async ({ step, subscriber }) => {
  await step.delay('delay', () => ({ amount: 1, unit: 'hours' }));

  await step.email('send-email', async (controls) => {
    // Fetch user data from your database in real-time to
    // ensure up-to-date information
    const user = await userDb.findById(subscriber.subscriberId);

    return {
      subject: `Welcome, ${user.firstName}`,
      body: 'Welcome to our platform!',
    };
  });
});

Then, when you trigger the workflow, you can pass the subscriberId and the workflow will fetch the user data from your database in real-time:

await welcomeEmail.trigger({
  to: {
    subscriberId: '123',
    email: '[e-mail]',
  },
});

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_SECRET_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.