Welcome to @onesignal/node-onesignal

The OneSignal Node client is a server SDK for NodeJS. A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com.

Installation

# npm
npm install @onesignal/node-onesignal

# pnpm
pnpm add @onesignal/node-onesignal

# bun
bun add @onesignal/node-onesignal

# yarn
yarn add @onesignal/node-onesignal

Configuration

Every SDK requires authentication via API keys. Two key types are available:

• REST API Key — required for most endpoints (sending notifications, managing users, etc.). Found in your app's Settings > Keys & IDs.
• Organization API Key — only required for organization-level endpoints like creating or listing apps. Found in Organization Settings.

Warning: Store your API keys in environment variables or a secrets manager. Never commit them to source control.

const OneSignal = require('@onesignal/node-onesignal');

const configuration = OneSignal.createConfiguration({
    restApiKey: 'YOUR_REST_API_KEY',
    organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
});

const client = new OneSignal.DefaultApi(configuration);

Send a push notification

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
notification.included_segments = ['Subscribed Users'];

const response = await client.createNotification(notification);
console.log('Notification ID:', response.id);

Send with idempotent retries

createNotificationWithRetry generates a UUIDv4 idempotency_key when absent (a caller-provided key is respected), retries 429 / 503 / transport errors with the same key (honoring Retry-After, exponential backoff otherwise; maxRetries / baseDelayMs configurable via the options object), fails fast on other errors, and reports via wasReplayed whether the server answered from a previously completed request (Idempotent-Replayed response header). It is a DefaultApi method, so the call mirrors createNotification:

const result = await client.createNotificationWithRetry(notification);
console.log('Notification ID:', result.response.id, 'replayed:', result.wasReplayed);

Send a push notification by External ID

Target specific users with the alias label external_id (snake_case). This is different from the notification-level external_id field, which is only for idempotent requests.

You must set target_channel when sending push (or email/SMS) to alias targets.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
// Keys under include_aliases must match API alias labels exactly (e.g. external_id, not externalId).
notification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };
notification.target_channel = 'push';

const response = await client.createNotification(notification);
if (!response.id) {
  console.error('Notification was not created:', response.errors);
} else {
  console.log('Notification ID:', response.id);
}

The API may return HTTP 200 with an empty id when no matching subscribed recipients are found; always check response.id and response.errors.

Send an email

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.email_subject = 'Important Update';
notification.email_body = '<h1>Hello!</h1>

This is an HTML email.

';
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'email';

const response = await client.createNotification(notification);

Send an SMS

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Your SMS message content here' };
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'sms';
notification.sms_from = '+15551234567';

const response = await client.createNotification(notification);

Full API reference

The complete list of API endpoints and their parameters is available in the DefaultApi documentation.

For the underlying REST API, see the OneSignal API reference.