🚧
Backend SDKs in User Model Beta
You still can try using new User Model endpoints, we advise customers to not use these SDKs in production.

Install

# yarn
yarn add @onesignal/node-onesignal

# npm
npm install @onesignal/node-onesignal --save

Usage

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

import * as OneSignal from '@onesignal/node-onesignal';

Creating a client

Configuration

We can configure the client using the createConfiguration function. You can find more info on each configuration
parameter here.

const configuration = OneSignal.createConfiguration(configParams);

Initializing the Client

const client = new OneSignal.DefaultApi(configuration);

Authentication

You can configure auth parameters passing them like this:

const configuration = OneSignal.createConfiguration({
    userAuthKey: '<YOUR_USER_KEY_TOKEN>',
    restApiKey: '<YOUR_API_KEY>',
});

const client = new OneSignal.DefaultApi(configuration);

Advanced Usage: Creating a brand-new app

If creating a new app via the client, the response will return the app's API key via the basic_auth_key response
parameter. You can then use this to modify your configuration object and create a new client that will have both user-level and app-level authentication set up.

const response = await client.createApp(newapp);

const configuration = OneSignal.createConfiguration({
    userAuthKey: '<YOUR_USER_KEY_TOKEN>',
    restApiKey: response.basic_auth_key,
});

const client = new OneSignal.DefaultApi(configuration);

API Reference

See the full list of API Endpoints.

To make stateful changes requests should take on the following pattern:

create or get an object
make changes to that object
pass the object to the request function to make the changes

Examples of important OneSignal objects include App, Notification, Player, and Segment.

For example, see the section below on creating an app. First an app object is created via the instantiation of the App
class. Then, the app instance is modified directly. Finally, we use the client to create the app via a remote request.

Creating an app

Creates a new OneSignal app.

Example

const app = new OneSignal.App();

// configure your application
app.name = 'app_name';
app.gcm_key = '<your key here>';
app.android_gcm_sender_id = '<your id here>';

const response = await client.createApp(app);

Getting an app

View the details of a single OneSignal app.

Example

const app = await client.getApp('<app id>');

Getting multiple apps

View apps.

Example

const apps = await client.getApps();

Updating an app

Updates the name or configuration settings of an existing OneSignal app.

Example

const app = new OneSignal.App();
app.name = 'modified_app_name';

const updateAppResponse = await client.updateApp('<existing_app_id>', app);

Creating a notification

Sends a notification to your users.

Example

const notification = new OneSignal.Notification();
notification.app_id = app.id;
// Name property may be required in some case, for instance when sending an SMS.
notification.name = "test_notification_name";
notification.contents = {
  en: "Gig'em Ags"
}

// required for Huawei
notification.headings = {
  en: "Gig'em Ags"
}

// This example uses segments, but you can also use filters or target individual users
// https://documentation.onesignal.com/reference/create-notification
notification.included_segments: ["All"]

const notificationResponse = await client.createNotification(notification);

Creating a notification using Filters

Sends a notification to your users filtered by specific criteria.

Example

const notification = new OneSignal.Notification();
notification.app_id = app.id;

notification.contents = {
  en: "Gig'em Ags"
}

// required for Huawei
notification.headings = {
  en: "Gig'em Ags"
}

// This example uses filters, but you can also use segments or target individual users
// https://documentation.onesignal.com/reference/create-notification#send-to-users-based-on-filters
notification.filters = [
    {
        field: 'last_session',
        relation: '>',
        value: "1"
    },
];

const notificationResponse = await client.createNotification(notification);

Canceling a notification

Stop a scheduled or currently outgoing notification.

Example

const cancelNotificationResponse = await client.cancelNotification('<app id>', '<notification id>');

Getting a notification

View the details of a single notification and outcomes associated with it.

Example

await client.getNotification('<app id>', '<notification id>');

Getting notifications

View the details of multiple notifications.

Param	Type	Description
app_id	string	The OneSignal App ID for your app. Available in Keys & IDs.
limit	string	How many notifications to return. Max is 50. Default is 50.
offset	number	Page offset. Default is 0. Results are sorted by queued_at in descending order. `queued_at` is a representation of the time that the notification was queued at.
kind	number	Kind of notifications returned: unset - All notification types (default) `0` - Dashboard only `1` - API only `3` - Automated only

Example

const notifications = await client.getNotifications('<app id>', '50', 0, 1);

Getting notification history

View the devices sent a message - OneSignal Paid Plan Required
This method will return all devices that were sent the given notification_id of an Email or Push Notification if used
within 7 days of the date sent.

Example

const notificationHistory = await client.getNotificationHistory('<notification id>');

Creating a segment

Create segments visible and usable in the dashboard and API - Required: OneSignal Paid Plan

Example

const segment = new OneSignal.Segment();

segment.filters = [
  { field: 'session_count', relation: '&gt;', value: '1' },
  { field: 'tag', key: 'my_tag', relation: 'exists' }
]

const segment = await client.createSegments(app.id, segment);

Deleting a segment

Delete segments (not user devices) - Required: OneSignal Paid Plan
You can delete a segment under your app by calling this API. You must provide an API key in the Authorization header
that has admin access on the app.
The segment_id can be found in the URL of the segment when viewing it in the dashboard.

Example

const deleteSegmentsResponse = await client.deleteSegments('<app id>', '<segment id>');

Creating a player

Add a device.

Example

const player = new OneSignal.Player();
player.device_type = 1;
player.app_id = app_id;
player.identifier = '<identifier>';
const player = await client.createPlayer(player);

Getting a player

View the details of an existing device in one of your OneSignal apps.
The email and the hash is only required if you have enabled Identity Verification and device_type is email.

Example

const player = await client.getPlayer('<app id>', '<player id>', '<email auth hash>');

Getting players

View the details of multiple devices in one of your OneSignal apps.

⚠️ Unavailable for Apps Over 80,000 Users.

Param	Type	Description
app_id	string	The OneSignal App ID for your app. Available in Keys & IDs.
limit	string	How many devices to return. Max is 300. Default is 300
offset	number	Result offset. Default is 0. Results are sorted by id;

Example

const players = await client.getPlayers('<app id>', '300', 0);

Exporting a player

Generate a compressed CSV export of all of your current user data. This method can be used to generate a compressed CSV
export of all of your existing user data and is a better alternative to retrieving this data using the /players API endpoint.

See full CSV Export Reference

Example

const exportPlayerResponse = await client.exportPlayer('<app id>', {
  extra_fields: ['location', 'external_user_id'],
  last_active_since: 1469392779,
  segment_name: "Subscribed Users"
});

Updating a player

Update an existing device in one of your OneSignal apps.

Example

const updatePlayerResponse = await client.updatePlayer('<player id>', player);

Updating player tags

Update an existing device's tags in one of your OneSignal apps using the External User ID.

const playerToUpdate = new OneSignal.Player();

player.app_id = APP_ID;
player.device_type = 1;

playerToUpdate.external_user_id = 'your_player_external_id'; // setting the same external_user_id as before
const updatePlayerTagsRequestBody = new OneSignal.UpdatePlayerTagsRequestBody();
updatePlayerTagsRequestBody.tags = {'typescript_test_tag': 1};
const updatePlayerResponse = await api.updatePlayerTags(APP_ID, PLAYER_EXTERNAL_USER_ID, updatePlayerTagsRequestBody);

Deleting Tags

To delete a tag, include its key and set its value to blank (""). Omitting a key/value will not delete it.

For example, if you wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the
tags JSON would look like the following:

Example

"tags": {
   "rank": "",
   "category": "",
   "class": "my_new_value"
}

Deleting a player

Deletes a user record.

Example

const deletePlayerResponse = await client.deletePlayer(app.id, '<player id>')

Getting outcomes

View the details of all the outcomes associated with your app.

🚧 Requires your OneSignal App's REST API Key, available in Keys & IDs 🚧

Outcome data are accessible for 30 days before being deleted from our servers. You can export this data monthly if you need it for a more extended period.

Param	Type	Description
app_id	string	The OneSignal App ID for your app. Available in Keys & IDs.
outcome_names	string	Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the “os” prefix with two underscores. For other outcomes, please use the name specified by the user. Example:ossession_duration.count,osclick.count,CustomOutcomeName.sum
outcome_names2	string	If outcome names contain any commas, then please specify only one value at a time. Example: `outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count` where “Sales, Purchase” is the custom outcomes with a comma in the name.
outcome_time_range	string	Optional Time range for the returned data. The values can be `1h` (for the last 1 hour data), `1d` (for the last 1 day data), or `1mo` (for the last 1 month data). Default is 1h if the parameter is omitted.
outcome_platforms	string	Optional Platform id. Refer device's platform ids for values. Example: `outcome_platform=0` for iOS `outcome_platform=7`, `8` for Safari and Firefox Default is data from all platforms if the parameter is omitted.
outcome_attribution	string	Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted.

Example

const outcomes = await client.getOutcomes(app.id, 'os__click.count,os_session_duration.count,my_outcome.sum');

Begin Live Activity

Starts a Live Activity event

// Create a player first
const player = new OneSignal.Player();
player.device_type = 0;
player.app_id = '<app id>';
const playerResponse = await api.createPlayer(player);

// Prepare a request
const beginLiveActivityRequest: BeginLiveActivityRequest = {
    push_token: '<push_token>',
    subscription_id: playerResponse.id!,
};
const activityId = '<activity_id>'; // any string

// Begin activity
await api.beginLiveActivity('<app_id>', activityId, beginLiveActivityRequest);

Update Live Activity

Updates a Live Activity event

const updateLiveActivityRequest: UpdateLiveActivityRequest = {
    event_updates: {
        data: 'test'
    },
    event: "update",
    name: "contents"
};

await api.updateLiveActivity('<app_id>', '<activity_id>', updateLiveActivityRequest);

End Live Activity

Stops a Live Activity event

const subscriptionId = '<subscription_id>'; // player id
await api.endLiveActivity('<app_id>', '<activity_id>', subscriptionId);

Subscription types

iOSPush
AndroidPush
FireOSPush
ChromeExtensionPush
ChromePush
WindowsPush
SafariLegacyPush
FirefoxPush
macOSPush
HuaweiPush
SafariPush
Email
SMS

Users

Creating a OneSignal User

const user = new OneSignal.User();

const aliasLabel = '<alias_label>';
const aliasId = '<alias_id>';
const subscriptionToken = '<subscription_token>';

user.identity = {
    [aliasLabel]: aliasId,
};

user.subscriptions = [
  {
    type: "iOSPush",
    token: subscriptionToken,
  }
];

const createdUser = await api.createUser('<app_id>', user);
assert(createdUser.identity!['onesignal_id'] != null);

Getting a user by `onesignal_id`

const onesignalAliasLabel = "onesignal_id";
const onesignalAliasId = createdUser.identity!['onesignal_id'];

const fetchedUser = await api.fetchUser('<app_id>', onesignalAliasLabel, onesignalAliasId);

Getting a user by an alias

const fetchedUser = await api.fetchUser('<app_id>', alias_label, alias_id);

Updating a user

const updateUserRequest: UpdateUserRequest = {
    properties: {
        language: 'fr'
    }
};

const updatedUser = await api.updateUser('<app_id>', aliasLabel, aliasId, updateUserRequest);

Deleting a user

await api.deleteUser('<app_id>', aliasLabel, aliasId);

Subscriptions

Creating a subscription for existing user

const createSubscriptionRequestBody: CreateSubscriptionRequestBody = {
    subscription: {
        type: "AndroidPush",
        token: '<subscription_token>',
    }
};

const response = await api.createSubscription('<app_id>', '<alias_label>', '<alias_id>', createSubscriptionRequestBody);

Updating a subscription

const updateSubscriptionRequestBody: UpdateSubscriptionRequestBody = {
    subscription: {
        type: "iOSPush",
        token: '<new-subscription-token>',
    }
};

await api.updateSubscription('<app_id>', '<existing_subscription_id>', updateSubscriptionRequestBody);

Deleting a subscription

await api.deleteSubscription('<app_id>', '<subscription_id>');

Transfer subscription ownership

Transfers the subscription from one user to another.

// Setting the user for transfering the subscription to. User is identyfied by an IdentityObject.
const transferSubscriptionRequestBody: TransferSubscriptionRequestBody = {
    identity: otherUserIdentityObject
};

const transferResponse = await api.transferSubscription('<app_id>', '<subscription_id>', transferSubscriptionRequestBody);

Aliases

Fetching aliases for a user

const fetchResponse = await api.fetchAliases('<app_id>', '<subscription_id>');

Fetching user identity

const fetchResponse = await api.fetchUserIdentity('<app_id>', '<alias_label>', '<alias_id>');

Identifying user by alias

const userIdentityRequestBody: UserIdentityRequestBody = {
    identity: {
        ['<new_alias_label>']: '<new_alias_id>'
    }
};

const identifyResponse = await api.identifyUserByAlias('<app_id>', 
                                                       '<existing_alias_label>', 
                                                       '<existing_alias_id>',
                                                       userIdentityRequestBody);

Identifying user by subscription id

const userIdentityRequestBody: UserIdentityRequestBody = {
    identity: {
        ['<new_alias_label>']: '<new_alias_id>'
    }
};

const identifyResponse = await api.identifyUserBySubscriptionId('<app_id>', '<existing_subscription_id>', userIdentityRequestBody);

Deleting an alias

await api.deleteAlias('<app_id>', '<alias_label>', '<alias_id>', '<alias_label_to_delete>');

🚧Backend SDKs in User Model Beta

Install

Usage

Creating a client

Configuration

Initializing the Client

Authentication

Advanced Usage: Creating a brand-new app

API Reference

Creating an app

Getting an app

Getting multiple apps

Updating an app

Creating a notification

Creating a notification using Filters

Canceling a notification

Getting a notification

Getting notifications

Getting notification history

Creating a segment

Deleting a segment

Creating a player

Getting a player

Getting players

Exporting a player

Updating a player

Updating player tags

Deleting Tags

Deleting a player

Getting outcomes

Begin Live Activity

Update Live Activity

End Live Activity

Subscription types

Users

Creating a OneSignal User

Getting a user by onesignal_id

Getting a user by an alias

Updating a user

Deleting a user

Subscriptions

Creating a subscription for existing user

Updating a subscription

Deleting a subscription

Transfer subscription ownership

Aliases

Fetching aliases for a user

Fetching user identity

Identifying user by alias

Identifying user by subscription id

Deleting an alias

🚧
Backend SDKs in User Model Beta

Getting a user by `onesignal_id`