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.

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.

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: '>', 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.

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.

Example

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