Server SDK Reference

All server-side SDKs for User Model are currently under beta. Take special care when using a server-side SDK in your production app.

App Management

`createApp()`

Creates a new OneSignal app.

const app = await OnesignalClient.createApp({
  name: "My App"
})

`getApp()`

View the details of a single OneSignal app.

const app = await OnesignalClient.getApp("APP_ID")

`getApps()`

View the details of all of your current OneSignal apps.

const apps = await OneSignal.getApps()

`updateApp()`

Updates the name or configuration settings of an existing OneSignal app

void await OnesignalClient.updateApp('APP_ID', {
  ...originalApp,
  name: 'Updated name',
})

Segmentation

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.

`createSegments()`

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 { id } = await OnesignalClient.createSegment("APP_ID", {
  name: "SEGMENT_NAME",
  filters: [{ field: "last_session", relation: ">", hours_ago: "1" }],
})

`getSegments()`

Get all segments created from the dashboard and the REST API.

const { segments, total_count } = await OnesignalClient.getSegments("APP_ID")

`deleteSegments()`

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

const { success } = await OnesignalClient.deleteSegment(
  "APP_ID",
  "SEGMENT_ID",
)

Outcomes

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.

`getOutcomes()`

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

const { outcomes } = await OnesignalClient.getOutcomes(
  "APP_ID",
  "os__click.count",
) 

//outcomes =【{"id": "os__click", "value": 0, "aggregation": "count"}】

Live Activities

`updateLiveActivity()`

Updates a specified live activity.

const { id } = await OnesignalClient.updateLiveActivity(
  "APP_ID",
  "ACTIVITY_ID",
  {
    event: "update",
    name: "ACTIVITY_NAME",
    event_updates: {
      homeScore: 3,
      awayScore: 1,
    },
  },
)

// The `event_updates` shape must match struct implementing `ActivityAttributes`

User Model

`createUser()`

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 { identity, subscriptions, properties } = await OnesignalClient.createUser(appId, {
  identity: {
    external_id: "EXTERNAL_ID",
  },
  properties: {
    language: "en",
    tags: {
      role: "admin",
    },
  },
})

// The `identity` object will include the OneSignal ID

`fetchUser()`

Returns an existing user matching a given Alias.

const user = await OnesignalClient.getUser(
  appId,
  "external_id",
  testingExternalId,
)

// The `user` object includes all identities, user properties, and subscriptions for the user

`updateUser()`

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

const updateUserResult = await OnesignalClient.updateUser(
  'APP_ID',
  'label',
  'id',
  {
    properties: {
      tags: { DataTagKey: 'New Value' },
    },
  }
)

`deleteUser()`

Removes an existing user matching a given Alias.

void (await OnesignalClient.deleteUser(
  "APP_ID",
  "ALIAS_KEY",
  "ALIAS_VALUE",
))

`fetchUserIdentity()`

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

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

`identifyUserByAlias()`

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.

`getEligibleIams()`

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

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

Notifications

`createNotification()`

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)

`getNotifications()`

View the details of multiple notifications.

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

`getNotification()`

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

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

`cancelNotification()`

Stop a scheduled or currently outgoing notification.

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

`getNotificationHistory()`

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.

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

Subscriptions

`createSubscription()`

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

`updateSubscription()`

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)

`transferSubscription()`

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);

`deleteSubscription()`

Delete an existing subscription.

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

Using the REST APIs

API reference

SDKs

Server SDK Reference

App Management

`createApp()`

`getApp()`

`getApps()`

`updateApp()`

Segmentation

`createSegments()`

`getSegments()`

`deleteSegments()`

Outcomes

`getOutcomes()`

Live Activities

`updateLiveActivity()`

User Model

`createUser()`

`fetchUser()`

`updateUser()`

`deleteUser()`

`fetchUserIdentity()`

`identifyUserByAlias()`

`getEligibleIams()`

Notifications

`createNotification()`

`getNotifications()`

`getNotification()`

`cancelNotification()`

`getNotificationHistory()`

Subscriptions

`createSubscription()`

Subscription Types

`updateSubscription()`

`transferSubscription()`

`deleteSubscription()`

Using the REST APIs

API reference

SDKs

​App Management

​createApp()

​getApp()

​getApps()

​updateApp()

​Segmentation

​createSegments()

​getSegments()

​deleteSegments()

​Outcomes

​getOutcomes()

​Live Activities

​updateLiveActivity()

​User Model

​createUser()

​fetchUser()

​updateUser()

​deleteUser()

​fetchUserIdentity()

​identifyUserByAlias()

​getEligibleIams()

​Notifications

​createNotification()

​getNotifications()

​getNotification()

​cancelNotification()

​getNotificationHistory()

​Subscriptions

​createSubscription()

​Subscription Types

​updateSubscription()

​transferSubscription()

​deleteSubscription()

App Management

`createApp()`

`getApp()`

`getApps()`

`updateApp()`

Segmentation

`createSegments()`

`getSegments()`

`deleteSegments()`

Outcomes

`getOutcomes()`

Live Activities

`updateLiveActivity()`

User Model

`createUser()`

`fetchUser()`

`updateUser()`

`deleteUser()`

`fetchUserIdentity()`

`identifyUserByAlias()`

`getEligibleIams()`

Notifications

`createNotification()`

`getNotifications()`

`getNotification()`

`cancelNotification()`

`getNotificationHistory()`

Subscriptions

`createSubscription()`

Subscription Types

`updateSubscription()`

`transferSubscription()`

`deleteSubscription()`