Node Client SDK

The OneSignal Node client is a server OneSignal SDK for NodeJS. Integrate OneSignal with your backend events, data, and more.

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

User

For managing operations outside of a OneSignal app (e.g: creating a OneSignal app), you will need to use your OneSignal account user auth key. Create a key provider object with a function getToken that returns your key.

const user_key_provider = {
    getToken() {
        return  "************************************************";
    }
};

App

Create a key provider object with a function getToken that returns your OneSignal app's API key.

const app_key_provider = {
    getToken() {
        return "************************************************";
    }
};

Putting it together

// configuration object
let configuration = OneSignal.createConfiguration({
    authMethods: {
        user_key: {
            tokenProvider: user_key_provider
        },
        app_key: {
            tokenProvider: app_key_provider
        }
    }
});

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.

let response = await client.createApp(newapp);
const app_key_provider = {
    getToken() {
        return response.basic_auth_key;
    }
};

configuration = OneSignal.createConfiguration({
    authMethods: {
        user_key: {
            tokenProvider: user_key_provider
        },
        app_key: {
            tokenProvider: app_key_provider
        }
    }
});

client = new OneSignal.DefaultApi(configuration);

API Reference

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

  1. create or get an object
  2. make changes to that object
  3. 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.

FunctionHTTP RequestDescription
CancelNotificationDelete /notifications/{notification_id}Stop a scheduled or currently outgoing notification
CreateAppPost /appsCreate an app
CreateNotificationPost /notificationsCreate notification
CreatePlayerPost /playersAdd a device
CreateSegmentsPost /apps/{app_id}/segmentsCreate Segments
DeletePlayerDelete /players/{player_id}Delete a user record
DeleteSegmentsDelete /apps/{app_id}/segments/{segment_id}Delete Segments
ExportPlayersPost /players/csv_export?app_id={app_id}CSV export
GetAppGet /apps/{app_id}View an app
GetAppsGet /appsView apps
GetNotificationGet /notifications/{notification_id}View notification
GetNotificationHistoryPost /notifications/{notification_id}/historyNotification History
GetNotificationsGet /notificationsView notifications
GetOutcomesGet /apps/{app_id}/outcomesView Outcomes
GetPlayerGet /players/{player_id}View device
GetPlayersGet /playersView devices
UpdateAppPut /apps/{app_id}Update an app
UpdatePlayerPut /players/{player_id}Edit device
UpdatePlayerTagsPut /apps/{app_id}/users/{external_user_id}Edit tags with external user id

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

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

Getting multiple apps

View apps.

Example

await client.getApps();

Updating an app

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

Example

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

Creating a notification

Sends a notification to your users.

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"
}
await client.createNotification(notification);

Canceling a notification

Stop a scheduled or currently outgoing notification.

Example

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.

ParamTypeDescription
app_id*stringThe OneSignal App ID for your app. Available in Keys & IDs.
limitstringHow many notifications to return. Max is 50. Default is 50.
offsetnumberPage 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.
kindnumberKind of notifications returned: unset - All notification types (default) 0 - Dashboard only 1 - API only 3 - Automated only

Example

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

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' }
]

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

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>';
await client.createPlayer(player);

Getting a player

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

Example

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.

ParamTypeDescription
app_id*stringThe OneSignal App ID for your app. Available in Keys & IDs.
limitstringHow many devices to return. Max is 300. Default is 300
offsetnumberResult offset. Default is 0. Results are sorted by id;

Example

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 current user data. It is a much faster alternative than retrieving this data using the /players API endpoint.

See full CSV Export Reference

Example

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

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.

Warning - Android SDK Data Synchronization

Tags added through the Android SDK tagging methods may not update if using the API to change or update the same tag.
For example, if you use SDK method sendTag("key", "value1") then update the tag value to "value2" with this API endpoint. You will not be able to set the value back to "value1" through the SDK, you will need to change it to something different through the SDK to be reset.

Recommendations if using this Endpoint on Android Mobile Apps:
1 - Do not use the same tag keys for SDK and API updates
2 - If you want to use the same key for both SDK and API updates, call the SDK getTags method first to update the device's tags.

This is only applicable on the Android Mobile App SDKs.

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 I 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

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

Getting outcomes

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

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

Outcome Data Limitations Outcomes are only accessible for around 30 days before deleted from our servers. You will need to export this data every month if you want to keep it.

ParamTypeDescription
app_id*stringThe OneSignal App ID for your app. Available in Keys & IDs.
outcome_namesstringRequired 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_names2stringIf 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_rangestringOptional 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_platformsstringOptional 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_attributionstringOptional 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

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

Did this page help you?