Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/onesignal/onesignal-node-api
OneSignal Node Client
https://github.com/onesignal/onesignal-node-api
api email in-app-messaging node nodejs notifications onesignal push push-notifications rest sms
Last synced: 5 days ago
JSON representation
OneSignal Node Client
- Host: GitHub
- URL: https://github.com/onesignal/onesignal-node-api
- Owner: OneSignal
- License: other
- Created: 2021-08-25T19:38:12.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-31T07:41:22.000Z (4 months ago)
- Last Synced: 2024-11-06T13:00:30.696Z (8 days ago)
- Topics: api, email, in-app-messaging, node, nodejs, notifications, onesignal, push, push-notifications, rest, sms
- Language: TypeScript
- Homepage:
- Size: 397 KB
- Stars: 32
- Watchers: 36
- Forks: 17
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Welcome to @onesignal/node-onesignal 👋
> OpenAPI client for node-onesignal
### 🏠 [Homepage](https://github.com/OneSignal/node-onesignal#readme)
### 🖤 [npm](https://www.npmjs.com/package/@onesignal/node-onesignal)
# Node Client SDK
The OneSignal Node client is a server OneSignal SDK for NodeJS. Integrate OneSignal with your backend events, data, and
more.
# Install
```sh
# yarn
yarn add @onesignal/node-onesignal
# npm
npm install @onesignal/node-onesignal --save
```
# Usage
```js
const OneSignal = require('@onesignal/node-onesignal');
```
```js
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](https://github.com/OpenAPITools/openapi-generator/pull/10283/files).
```js
const configuration = OneSignal.createConfiguration(configParams);
```
### Initializing the Client
```js
const client = new OneSignal.DefaultApi(configuration);
```
### Authentication
You can configure auth parameters passing them like this:
```js
const configuration = OneSignal.createConfiguration({
userAuthKey: '',
restApiKey: '',
});
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.
```js
const response = await client.createApp(newapp);
const configuration = OneSignal.createConfiguration({
userAuthKey: '',
restApiKey: response.basic_auth_key,
});
const client = new OneSignal.DefaultApi(configuration);
```
---
## API Reference
> See the full list of [API Endpoints](DefaultApi.md).
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`, `User`, 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**
```js
const app = new OneSignal.App();
// configure your application
app.name = 'app_name';
app.gcm_key = '';
app.android_gcm_sender_id = '';
const response = await client.createApp(app);
```
### Getting an app
View the details of a single OneSignal app.
**Example**
```js
const app = await client.getApp('');
```
### Getting multiple apps
View apps.
**Example**
```js
const apps = await client.getApps();
```
### Updating an app
Updates the name or configuration settings of an existing OneSignal app.
**Example**
```js
const app = new OneSignal.App();
app.name = 'modified_app_name';
const udpateAppResponse = await client.updateApp('', app);
```
### Creating a notification
Sends a notification to your users.
**Example**
```js
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"
}
const notification = await client.createNotification(notification);
```
### Creating a notification using Filters
Sends a notification to your users filtered by specific criteria.
**Example**
```js
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"
}
// Find all the users that have not spent any amount in USD on IAP.
// https://documentation.onesignal.com/reference/create-notification#send-to-users-based-on-filters
notification.filters = [
{
field: 'amount_spent',
relation: '=',
value: "0"
},
];
const notification = await client.createNotification(notification);
```
### Canceling a notification
Stop a scheduled or currently outgoing notification.
**Example**
```js
const cancelNotificationResponse = await client.cancelNotification('', '');
```
### Getting a notification
View the details of a single notification and outcomes associated with it.
**Example**
```js
await client.getNotification('', '');
```
### 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**
```js
const notifications = await client.getNotifications('', '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**
```js
const notificationHistory = await client.getNotificationHistory('');
```
### Creating a segment
Create segments visible and usable in the dashboard and API - **Required: OneSignal Paid Plan**
**Example**
```js
const segment = new OneSignal.Segment();
segment.filters = [
{ field: 'session_count', relation: '>', 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**
```js
const deleteSegmentsResponse = await client.deleteSegments('', '');
```
### Creating a player
Add a device.
**Example**
```js
const player = new OneSignal.Player();
player.device_type = 1;
player.app_id = app_id;
player.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**
```js
const player = await client.getPlayer('', '', '');
```
### 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**
```js
const players = await client.getPlayers('', '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](https://documentation.onesignal.com/reference/csv-export)
**Example**
```js
const exportPlayerResponse = await client.exportPlayer('', {
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**
```js
const updatePlayerResponse = await client.updatePlayer('', player);
```
### Updating player tags
Update an existing device's tags in one of your OneSignal apps using the External User ID.
```js
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**
```json
"tags": {
"rank": "",
"category": "",
"class": "my_new_value"
}
```
### Deleting a player
Deletes a user record.
**Example**
```js
const deletePlayerResponse = await client.deletePlayer(app.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:os__session_duration.count,os__click.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**
```js
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
```js
// Create a player first
const player = new OneSignal.Player();
player.device_type = 0;
player.app_id = '';
const playerResponse = await api.createPlayer(player);
// Prepare a request
const beginLiveActivityRequest: BeginLiveActivityRequest = {
push_token: '',
subscription_id: playerResponse.id!,
};
const activityId = ''; // any string
// Begin activity
await api.beginLiveActivity('', activityId, beginLiveActivityRequest);
```
### Update Live Activity
Updates a Live Activity event
```js
const updateLiveActivityRequest: UpdateLiveActivityRequest = {
event_updates: {
data: 'test'
},
event: "update",
name: "contents"
};
await api.updateLiveActivity('', '', updateLiveActivityRequest);
```
### End Live Activity
Stops a Live Activity event
```js
const subscriptionId = ''; // player id
await api.endLiveActivity('', '', subscriptionId);
```
### Subscription types
* iOSPush
* AndroidPush
* FireOSPush
* ChromeExtensionPush
* ChromePush
* WindowsPush
* SafariLegacyPush
* FirefoxPush
* macOSPush
* HuaweiPush
* SafariPush
* Email
* SMS
## Users
### Creating a OneSignal User
```js
const user = new OneSignal.User();
const aliasLabel = '';
const aliasId = '';
const subscriptionToken = '';
user.identity = {
[aliasLabel]: aliasId,
};
user.subscriptions = [
{
type: "iOSPush",
token: subscriptionToken,
}
];
const createdUser = await api.createUser('', user);
assert(createdUser.identity!['onesignal_id'] != null);
```
### Getting a user by `onesignal_id`
```js
const oneisgnalAliasLabel = "onesignal_id";
const onesignalAliasId = createdUser.identity!['onesignal_id'];
const fetchedUser = await api.fetchUser('', oneisgnalAliasLabel, onesignalAliasId);
```
### Getting a user by an alias
```js
const fetchedUser = await api.fetchUser('', alias_label, alias_id);
```
### Updating a user
```js
const updateUserRequest: UpdateUserRequest = {
properties: {
language: 'fr'
}
};
const updatedUser = await api.updateUser('', aliasLabel, aliasId, updateUserRequest);
```
### Deleting a user
```js
await api.deleteUser('', aliasLabel, aliasId);
```
## Subscriptions
### Creating a subscription for existing user
```js
const createSubscriptionRequestBody: CreateSubscriptionRequestBody = {
subscription: {
type: "AndroidPush",
token: '',
}
};
const response = await api.createSubscription('', '', '', createSubscriptionRequestBody);
```
### Updating a subscription
```js
const updateSubscriptionRequestBody: UpdateSubscriptionRequestBody = {
subscription: {
type: "iOSPush",
token: '',
}
};
await api.updateSubscription('', '', updateSubscriptionRequestBody);
```
### Deleting a subscription
```js
await api.deleteSubscription('', '');
```
### Transfer subscription ownership
Transfers the subscription from one user to another.
```js
// Setting the user for transfering the subscription to. User is identyfied by an IdentityObject.
const transferSubscriptionRequestBody: TransferSubscriptionRequestBody = {
identity: otherUserIdentityObject
};
const transferResponse = await api.transferSubscription('', '', transferSubscriptionRequestBody);
```
## Aliases
### Fetching aliases for a user
```js
const fetchResponse = await api.fetchAliases('', '');
```
### Fetching user identity
```js
const fetchResponse = await api.fetchUserIdentity('', '', '');
```
### Identifying user by alias
```js
const userIdentityRequestBody: UserIdentityRequestBody = {
identity: {
['']: ''
}
};
const identifyResponse = await api.identifyUserByAlias('',
'',
'',
userIdentityRequestBody);
```
### Identifying user by subscription id
```js
const userIdentityRequestBody: UserIdentityRequestBody = {
identity: {
['']: ''
}
};
const identifyResponse = await api.identifyUserBySubscriptionId('', '', userIdentityRequestBody);
```
### Deleting an alias
```js
await api.deleteAlias('', '', '', '');
```
## Author
* Website: https://onesignal.com
* Twitter: [@onesignal](https://twitter.com/onesignal)
* Github: [@OneSignal](https://github.com/OneSignal)
## 🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/OneSignal/node-onesignal/issues).
## Show your support
Give a ⭐️ if this project helped you!
## 📝 License
Copyright © 2023 [OneSignal](https://github.com/OneSignal).
This project is [MIT](https://github.com/OneSignal/node-onesignal/blob/main/LICENSE) licensed.