Node.js

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({
  apiKey: process.env.NOTIFLOWS_API_KEY,
  secret: process.env.NOTIFLOWS_SECRET,
});

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

Configuration

const client = new Notiflows({
  apiKey: 'pk_your_api_key',
  secret: 'sk_your_secret_key',
});

Both apiKey and secret are required. Find them in your project's Settings > API Keys.

Triggering Notiflows

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

// Send to all subscribers of a topic
await client.notiflows.run('new-comment', {
  topic: 'post_123',
  data: { commenter: 'Jane', comment: 'Great post!' },
  actor: { external_id: 'user_456' },
});

Parameters

Parameter	Type	Description
`notiflowHandle`	string	The notiflow identifier (first argument)
`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

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.retrieve('user_123');

List Users

const usersPage = await client.users.list({ limit: 20 });

Delete User

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

User Preferences

// Get preferences
const prefs = await client.users.preferences.retrieve('user_123');

// Update preferences
await client.users.preferences.update('user_123', {
  channel_types: { email: true, sms: false },
});

Topic Subscriptions

// Subscribe user to topic
await client.users.subscriptions.subscribe('user_123', {
  topic_name: 'product-updates',
});

// List user subscriptions
const subs = await client.users.subscriptions.list('user_123');

// Unsubscribe
await client.users.subscriptions.unsubscribe('product-updates', {
  user_external_id: 'user_123',
});

Topics

// List topics
const topics = await client.topics.list({ limit: 10 });

// Get topic
const topic = await client.topics.retrieve('product-updates');

// List topic subscribers
const subs = await client.topics.subscriptions.list('product-updates');

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

Notifications & Deliveries

// List notifications
const notifications = await client.notifications.list({ limit: 10 });

// Get notification
const notification = await client.notifications.retrieve('notification_id');

// List deliveries for a notification
const deliveries = await client.notifications.listDeliveries('notification_id');

// List all deliveries
const allDeliveries = await client.deliveries.list({ limit: 10 });

// Get delivery
const delivery = await client.deliveries.retrieve('delivery_id');

User Notifications & Deliveries

// List user's notifications
await client.users.notifications.list('user_123');

// List user's deliveries
await client.users.deliveries.list('user_123');

TypeScript

The SDK is fully typed:

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

On this page