The Node.js SDK (@notiflows/node) allows you to trigger notiflows, manage users, and interact with the Notiflows Admin API from your Node.js backend.

Installation

npm install @notiflows/node

Quick Start

import { Notiflows } from '@notiflows/node';

const client = new Notiflows(process.env.NOTIFLOWS_SECRET_KEY);

// Trigger a notiflow
await client.notify({
  notiflow: 'welcome-email',
  recipients: [
    { external_id: 'user_123' }
  ],
  data: {
    name: 'Jane',
  },
});

Configuration

const client = new Notiflows(secretKey, {
  // Optional configuration
  baseUrl: 'https://api.notiflows.com/admin/v1',  // Custom API URL
});

Triggering Notiflows

Send notifications by triggering a notiflow:

// Send to specific recipients
await client.notify({
  notiflow: 'order-shipped',
  recipients: [
    { external_id: 'user_123' },
    { external_id: 'user_456' },
  ],
  data: {
    order_id: 'order_789',
    tracking_url: 'https://example.com/track/789',
  },
});

// Send to all subscribers of a topic
await client.notify({
  notiflow: 'new-comment',
  topic: 'post_123',
  data: {
    commenter: 'Jane',
    comment: 'Great post!',
  },
  actor: {
    external_id: 'user_456',  // The user who performed the action
  },
});

Parameters

Parameter	Type	Description
`notiflow`	string	The notiflow identifier
`recipients`	array	Array of recipient objects with `external_id`
`topic`	string	Alternative to recipients - notify all topic subscribers
`data`	object	Variables for your notification templates
`actor`	object	The user performing the action (optional)

Use either recipients or topic, not both.

Managing Users

Upsert User

Create or update a user:

await client.users.upsert('user_123', {
  email: 'jane@example.com',
  first_name: 'Jane',
  last_name: 'Doe',
  phone: '+1234567890',
  avatar: 'https://example.com/avatar.jpg',
  locale: 'en',
  timezone: 'America/New_York',
  custom_fields: {
    plan: 'premium',
    company: 'Acme Inc',
  },
});

Get User

const user = await client.users.get('user_123');

List Users

const { data, pagination } = await client.users.list({
  limit: 20,
  created_after: '2024-01-01T00:00:00Z',
});

// Pagination
if (pagination.has_more_after) {
  const nextPage = await client.users.list({
    after: pagination.end_cursor,
  });
}

Delete User

await client.users.delete('user_123');

User Preferences

Get Preferences

const preferences = await client.users.getPreferences('user_123');

Update Preferences

await client.users.updatePreferences('user_123', {
  channels: {
    email: true,
    sms: false,
  },
  notiflows: {
    'marketing-updates': {
      enabled: false,
    },
  },
});

Channel Settings

Manage user-specific channel settings (e.g., push tokens, Slack connections):

Update Channel Settings

// Set FCM token for mobile push
await client.users.updateChannelSettings('user_123', 'fcm-channel-id', {
  tokens: ['fcm-device-token-123'],
});

// Set APNs token for iOS push
await client.users.updateChannelSettings('user_123', 'apns-channel-id', {
  tokens: ['apns-device-token-456'],
});

Get Channel Settings

const settings = await client.users.getChannelSettings('user_123', 'fcm-channel-id');

Delete Channel Settings

await client.users.deleteChannelSettings('user_123', 'fcm-channel-id');

Topic Subscriptions

await client.users.subscribe('user_123', 'product-updates');

Unsubscribe User from Topic

await client.users.unsubscribe('user_123', 'product-updates');

List User Subscriptions

const subscriptions = await client.users.listSubscriptions('user_123');

Bulk Subscribe/Unsubscribe

// Subscribe multiple users to a topic
await client.topics.subscribe('product-updates', [
  'user_123',
  'user_456',
  'user_789',
]);

// Unsubscribe multiple users
await client.topics.unsubscribe('product-updates', [
  'user_123',
  'user_456',
]);

Topics

List Topics

const { data } = await client.topics.list();

Get Topic

const topic = await client.topics.get('product-updates');

List Topic Subscribers

const { data } = await client.topics.listSubscriptions('product-updates');

Delete Topic

await client.topics.delete('product-updates');

Notifications & Deliveries

List Notifications

const { data } = await client.notifications.list({
  status: 'processed',
  topic: 'order-updates',
  created_after: '2024-01-01T00:00:00Z',
});

Get Notification

const notification = await client.notifications.get('notification_id');

List Notification Deliveries

const { data } = await client.notifications.listDeliveries('notification_id');

List All Deliveries

const { data } = await client.deliveries.list({
  status: 'sent',
  channel_id: 'email-channel-id',
});

Get Delivery

const delivery = await client.deliveries.get('delivery_id');

User Notifications & Deliveries

Query notifications and deliveries for a specific user:

// List user's notifications
const { data } = await client.users.listNotifications('user_123', {
  status: 'processed',
});

// Get specific notification for user
const notification = await client.users.getNotification('user_123', 'notification_id');

// List user's deliveries
const { data } = await client.users.listDeliveries('user_123', {
  status: 'sent',
});

// Get specific delivery for user
const delivery = await client.users.getDelivery('user_123', 'delivery_id');

Error Handling

import { Notiflows, NotiflowsError } from '@notiflows/node';

try {
  await client.notify({
    notiflow: 'welcome-email',
    recipients: [{ external_id: 'user_123' }],
  });
} catch (error) {
  if (error instanceof NotiflowsError) {
    console.error('API Error:', error.code, error.message);

    if (error.code === 'validation_failed') {
      console.error('Validation errors:', error.details.fields);
    }
  }
}

TypeScript

The SDK is fully typed:

import type {
  User,
  Notification,
  Delivery,
  NotifyParams,
  UserUpsertParams,
} from '@notiflows/node';

Node.js

On this page