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 an email

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.email_subject = 'Important Update';
notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
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.