---
title: Node.js
description: Notiflows Node.js SDK for server-side integration
---

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

```bash
npm install @notiflows/node
```

## Quick Start

```typescript
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

```typescript
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

```typescript
// 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) |

<Callout>
Use either `recipients` or `topic`, not both.
</Callout>

## Managing Users

### Upsert User

```typescript
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

```typescript
const user = await client.users.retrieve('user_123');
```

### List Users

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

### Delete User

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

## User Preferences

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

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