Backend SDKs

🚧

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.

App Management

Create an app

Creates a new OneSignal app.

const app = await OneSignal.createAppAsync()

Get an app

View the details of a single OneSignal app.

const app = await OneSignal.getAppAsync('APP_ID')

Get several apps

View the details of all of your current OneSignal apps.

const apps = await OneSignal.getAppsAsync()

Update an app

Updates the name or configuration settings of an existing OneSignal app

void await OneSignal.updateAppAsync('APP_ID')

Segmentation

Create segments

📘

Available for paid plans

A paid plan is required to create segments on your server programmatically. Users of our Free plan can continue creating segments within the OneSignal Dashboard.

Create segments visible and usable in the dashboard and API. Like creating Segments from the dashboard, you can pass in filters with multiple.AND or OR operators.

const segments: Segment[] = []
void await OneSignal.createSegmentsAsync(segments)

Delete segments

Deletes segments. Note that this doesn't delete devices or users in the given segment.

const segments: Segment[] = []
void await OneSignal.deleteSegmentsAsync(segments)

Outcomes

View outcomes

📘

Outcome Data Limitations

Outcomes are only stored on our servers for 30 days. You must export this data every month if you wish to keep it as outcomes older than 30 days are removed from our servers.

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

const outcomes = await OneSignal.getOutcomesAsync('APP_ID',
	['OUTCOME_NAME_01', 'OUTCOME_NAME_02', 'OUTCOME_NAME_03'])

Live Activities

Start a Live Activity

Starts a Live Activity.

void await OneSignal.beginLiveActivityAsync('APP_ID', 'ACTIVITY_ID', {
	pushToken: 'string',
  subscriptionId: 'string'
})
  

Update a Live Activity via Push

Updates a specified live activity.

void await OneSignal.updateLiveActivityAsync('APP_ID', 'ACTIVITY_ID', {
  name: 'headings',
  event: 'update',
	eventUpdates: { },
  dismissAt: 0
})
  

Stop a Live Activity

Stops a Live Activity.

void await OneSignal.stopLiveActivityAsync('APP_ID', 'ACTIVITY_ID', 'SUBSCRIPTION_ID')

User Model

Create a user

Creates a User, optionally Subscriptions owned by the User and Aliases. Aliases provided in the payload will be used to look up an existing User.

const user = await OneSignal.createUserAsync('APP_ID', {
  properties: {
    tags: {
      additionalProp1: {},
    },
    language: 'string',
    timezone_id: 'string',
    lat: 0,
    long: 0,
    country: 'string',
    first_active: 0,
    last_active: 0,
    amount_spent: 0,
    purchases: [
      {
        sku: 'string',
        amount: 'string',
        iso: 'string',
      },
    ],
    ip: 'string',
  },
  identity: {
    additionalProp1: {},
  },
  subscriptions: [
    {
      id: 'string',
      type: 'iOSPush',
      token: 'string',
      enabled: true,
      notification_types: 0,
      session_time: 0,
      session_count: 0,
      sdk: 'string',
      device_model: 'string',
      device_os: 'string',
      rooted: true,
      test_type: 0,
      app_version: 'string',
      net_type: 0,
      carrier: 'string',
      web_auth: 'string',
      web_p256: 'string',
    },
  ],
  subscription_options: {
    retain_previous_owner: true,
  }
})

Get user details

Returns an existing user matching a given Alias.

const user = await OneSignal.fetchUserAsync('APP_ID', 'ALIAS_LABEL', 'ALIAS_ID')

Update a user

Updates an existing user matching a given Alias. To update Data Tags, modify the tags property on the user object.

void await OneSignal.updateUserAsync('APP_ID', 'ALIAS_LABEL', 'ALIAS_ID', {
  properties: {
    tags: {
      additionalProp1: {},
    },
    language: 'string',
    timezone_id: 'string',
    lat: 0,
    long: 0,
    country: 'string',
    first_active: 0,
    last_active: 0,
    amount_spent: 0,
    purchases: [
      {
        sku: 'string',
        amount: 'string',
        iso: 'string',
      },
    ],
    ip: 'string',
  },
  refresh_device_metadata: false,
  deltas: {
    session_time: 0,
    session_count: 0,
    amount_spent: 0,
    purchases: [
      {
        sku: 'string',
        amount: 'string',
        iso: 'string',
      }
    ]
  }
})

Delete a user

Removes an existing user matching a given Alias.

void await OneSignal.deleteUserAsync('APP_ID', 'ALIAS_LABEL', 'ALIAS_ID')

List aliases

Lists all Aliases for an existing user matching a given Alias.

const aliases = await OneSignal.fetchUserIdentityAsync('APP_ID', 'SUBSCRIPTION_ID')

Add aliases

Add one or more Aliases to an existing user matching a given Alias.

void await OneSignal.identifyUserByAliasAsync('APP_ID', 'ALIAS_LABEL', 'ALIAS_ID', {
	identity: {
   	'ALIAS_LABEL_01': 'ALIAS_ID_01',
    'ALIAS_LABEL_02': 'ALIAS_ID_02',
    'ALIAS_LABEL_03': 'ALIAS_ID_03'
  }
})

If a provided Alias Label doesn't exist, it will be created automatically for you.

List in-app messages

Manifest of In-App Messages the subscription is eligible to display by the SDK.

const manifest = await OneSignal.getEligibleIamsAsync('APP_ID', 'SUBSCRIPTION_ID')

Notifications

Create a notification

Send a notification to your users.

const notification = new OneSignal.Notification()
notification.appId = 'APP_ID'
notification.name = 'NOTIFICATION_NAME'
notification.contents = {
	en: 'NOTIFICATION_MESSAGE'
}

// For Huawei devices, set the `headings` key
notification.headings = {
	en: 'NOTIFICATION_MESSAGE'
}

const { id, external_id, errors } = await OneSignal.createNotificationAsync(notification)

Get notifications

View the details of multiple notifications.

const { totalCount, offset, limit, notifications } = await OneSignal.getNotificationsAsync('APP_ID')

Get a notification

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

const notification = await OneSignal.getNotificationAsync('APP_ID', 'NOTIFICATION_ID')

Cancel a notification

Stop a scheduled or currently outgoing notification.

void await OneSignal.cancelNotificationAsync('APP_ID', 'NOTIFICATION_ID')

Get notification history

📘

Available for paid plan

Enable by navigating to OneSignal Dashboard -> Setting -> Integreations and activating Send History via OneSignal API.

View the recipients of a notification.

const recipientHistory = await OneSignal.getNotificationHistoryAsync('APP_ID', 'NOTIFICATION_ID')

All devices that received the message are returned if used within seven (7) days of the date sent; however, no history is available after seven days.
After receiving a successful response, you can

  • Poll the URL until a .csv file becomes available. Most exports complete in three minutes or less; we recommend polling URL in 10-second intervals.
  • If you prefer to receive an email, provide an email address you would like to receive an email report instead.
    Messages targeting fewer than 1,000 recipients will not have "sent" events recorded, but "clicked" events will.

Subscriptions

Create a subscription

Create a new subscription for an existing user.

const subscription: CreateSubscriptionRequestBody = {
    subscription: {
        type: '<SUBSCRIPTION_TYPE>',
        token: '<PUSH_TOKEN | EMAIL_ADDRESS | PHONE_NUMBER>',
    }
}

const response = await OneSignal.createSubscription('APP_ID', 'ALIAS_LABEL', 'ALIAS_ID', subscription)

Subscription types

  • Email
  • SMS
  • iOSPush
  • AndroidPush
  • HauweiPush
  • FireOSPush
  • WindowsPush
  • macOSPush
  • ChromeExtensionPush
  • Chrome
  • SafariLegacyPush
  • SafariPush
  • FirefoxPush

Update a subscription

Update an existing subscription.

const updatedSubscription: UpdateSubscriptionRequestBody = {
    subscription: {
        type: '<SUBSCRIPTION_TYPE>',
        token: '<PUSH_TOKEN | EMAIL_ADDRESS | PHONE_NUMBER>',
    }
}

await OneSignal.updateSubscription('APP_ID', 'SUBSCRIPTION_ID', updatedSubscription)

Transfer ownership

Transfer a subscription from one user to another.

const subscription: TransferSubscriptionRequestBody = {
    identity: otherUserIdentityObject	// ID of user to transfer to
};

const response = await OneSignal.transferSubscription('APP_ID', 'SUBSCRIPTION_ID', subscription);

Delete a subscription

Delete an existing subscription.

await OneSignal.deleteSubscription('APP_ID', 'SUBSCRIPTION_ID')

Player Model

❗️

Player Model Deprecation

Player model APIs are now deprecated and will receive no further development in the future. Player model APIs are incompatible with the new user model APIs, so if you opt to continue using player model APIs for your app, you will not be able to switch to the new APIs in the future as it may result in data corruption.

Get Players

🚧

Unavailable for large apps

Due to performance, this function is only available for apps with less than 80,000 users. Apps with more than 80,000 users can obtain a CSV export of player data.

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

const { totalCount, offset, limit, players } = await OneSignal.getPlayersAsync('APP_ID')

Add a Player

🚧

Building for iOS

iOS Must set test_type to 1 when building iOS apps under development and omit this field under production builds.

Registers a new device to one of your OneSignal apps. If a device is already registered with the given identifier, then an update will occur instead.

const { success, id } = await OneSignal.addPlayerAsync({
  app_id: 'APP_ID',
  external_user_id: 'EID',
  external_user_id_auth_hash: 'EID_AUTH_HASH',
  email_auth_hash: 'EMAIL_AUTH_HASH',
  language: 'string',
  timezone: 0,
  tags: {},
  amount_spent: 0,
  playtime: 0,
  notification_types: 0,
  test_type: 0,
  long: 0,
  lat: 0,
  country: 'string'
})

You may use the resulting Player identified by id as the player to send push notifications to later or include this player when sending to a set of devices.

Delete a Player

Delete a Player record given by Player ID from an app.

const { success: didSucceed } = await OneSignal.deletePlayergetAsync('APP_ID', 'PLAYER_ID')

Update a Player

View the details of an existing device in one of your OneSignal apps.

const { success: didSucceed } = await OneSignal.updatePlayerAsync('APP_ID', 'PLAYER_ID')

//  If you have enabled Identity Verification and `device_type` is email (11).
const { success: didSucceed } = await OneSignal.updatePlayerAsync('APP_ID', 'PLAYER_ID', 'EMAIL_AUTH_HASH')

Edit a Player

Update an existing device in one of your OneSignal apps.

const { success: didSucceed } = await OneSignal.updatePlayerAsync('APP_ID', 'PLAYER_ID', {
  app_id: 'string',
  device_type: 0,
  external_user_id: 'string',
  external_user_id_auth_hash: 'string',
  email_auth_hash: 'string',
  identifier: 'string',
  language: 'string',
  timezone: 0,
  game_version: 'string',
  device_model: 'string',
  device_os: 'string',
  ad_id: 'string',
  sdk: 'string',
  session_count: 0,
  tags: {},
  amount_spent: 0,
  created_at: 0,
  playtime: 0,
  badge_count: 0,
  last_active: 0,
  notification_types: 0,
  test_type: 0,
  long: 0,
  lat: 0,
  country: 'string',
})

Export player data

📘

Concurrent Exports

Only one concurrent export is allowed per OneSignal account. Please ensure you have successfully downloaded the CSV file before exporting another app.

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. The file is compressed using GZip and may take several minutes to generate, depending on the number of users in your app. The URL generated will be available for three days and includes random v4 UUID as part of the resource name to be unguessable.

const { csvFileUrl } = await OneSignal.exportPlayersAsync('APP_ID', {
  extra_fields: [
    'string'
  ],
  last_active_since: 'string',
  segment_name: 'string'
})

The file may take time to generate, depending on how many device records are pulled. If the file is not ready when called, a 403 error will be returned.