Skip to main content

Documentation Index

Fetch the complete documentation index at: https://setup.despia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

npm install despia-native

import despia from 'despia-native';

​
Schemes

​
Register for push (custom setups only)

Despia requests push permission and registers the device with OneSignal automatically at app launch. You do not need to call this. It is only available if you have disabled auto-registration in the Despia dashboard and want to trigger the permission prompt at a specific point in your own flow. 
// Only for custom setups with auto-registration disabled
despia('registerpush://')
Associates the device with your user. Call this on every authenticated app load, immediately after you confirm the user is logged in. This is how OneSignal knows which device to deliver a notification to when you send it. 
despia(`setonesignalplayerid://?user_id=${userId}`)
ParameterRequiredDescription
user_idYesYour user’s ID from your own database. This becomes the external_id in OneSignal.
The value you pass here is what you include in include_external_user_ids when sending notifications from your backend.

​
Check push permission status

Check whether the user has push notifications enabled on their device. Use this to show an in-app prompt directing them to their settings if they have not granted permission. 
const result = await despia('checkNativePushPermissions://', ['nativePushEnabled'])

if (result.nativePushEnabled) {
    // Push is enabled , proceed normally
} else {
    // Push is disabled , show a prompt explaining why notifications matter
    // and offer a button to open device settings
    despia('settingsapp://')
}
Return keyTypeDescription
nativePushEnabledbooleantrue if the user has granted push permission, false if denied or not yet requested
A good pattern is to check on every app load and show a non-intrusive banner when push is disabled, rather than blocking the user. settingsapp:// opens the device settings page for your app where the user can enable notifications directly.

​
Full client-side setup

import despia from 'despia-native'

const isDespia = navigator.userAgent.toLowerCase().includes('despia')

async function initNotifications(userId) {
    if (!isDespia) return

    // Link device to your user , call on every authenticated load
    despia(`setonesignalplayerid://?user_id=${userId}`)
}

// Call on every authenticated load
initNotifications(currentUser.id)

​
Backend: send a notification

Send notifications from your backend using OneSignal’s REST API. Use include_external_user_ids to target specific users by the same ID you passed to setonesignalplayerid://. 
// POST /api/notifications/send
async function sendPushNotification(userId, title, message, data = {}) {
    const response = await fetch('https://onesignal.com/api/v1/notifications', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Basic ${process.env.ONESIGNAL_REST_API_KEY}`,
        },
        body: JSON.stringify({
            app_id:                    process.env.ONESIGNAL_APP_ID,
            include_external_user_ids: [userId],
            headings:                  { en: title },
            contents:                  { en: message },
        }),
    })
    return response.json()
}

​
Send to multiple users

await sendPushNotification(
    ['user_123', 'user_456', 'user_789'],
    'New message',
    'You have a new message waiting'
)

// change include_external_user_ids to an array of user IDs

​
Send to all users

const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${process.env.ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify({
        app_id:            process.env.ONESIGNAL_APP_ID,
        included_segments: ['All'],
        headings:          { en: 'Title' },
        contents:          { en: 'Message to all users' },
    }),
})

​
Notification payload options

FieldTypeDescription
app_idstringYour OneSignal App ID
include_external_user_idsstring[]Target specific users by your user ID
included_segmentsstring[]Target a segment, e.g. ["All"], ["Active Users"]
headingsobjectTitle per language, e.g. { en: "Title" }
contentsobjectBody per language, e.g. { en: "Message" }
dataobjectCustom key-value data delivered with the notification
send_afterstringSchedule delivery, e.g. "2026-01-01T09:00:00Z"
delayed_optionstring"timezone" to deliver at a specific local time
delivery_time_of_daystringTime for timezone delivery, e.g. "9:00AM"
ios_critical_alertnumberSet to 1 to send a critical alert on iOS. Requires the Critical Alerts entitlement and must be enabled in Despia before use.

​
Critical alerts

Critical alerts bypass Do Not Disturb and silent mode on the user’s device.

​
iOS

iOS requires the Critical Alerts entitlement from Apple. Request it at developer.apple.com/contact/request/notifications-critical-alerts-entitlement. Apple reviews requests manually and approval can take several weeks. When submitting the request, you need to enable the entitlement on two bundle IDs , your core app bundle ID and your OneSignal Service Extension bundle ID. For example, if your app bundle ID is com.despia.myapp, add both:
  • com.despia.myapp
  • com.despia.myapp.OneSignalNotificationServiceExtension
Once Apple approves the request, enable critical alerts in Despia > App > Integrations > OneSignal > Critical Alerts and rebuild a new version in Despia. After the rebuild, set ios_critical_alert to 1 in your payload. 
// Backend: send a critical alert on iOS
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${process.env.ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify({
        app_id:                    process.env.ONESIGNAL_APP_ID,
        include_external_user_ids: [userId],
        headings:                  { en: 'Urgent alert' },
        contents:                  { en: 'Message body' },
        ios_critical_alert:        1,
    }),
})

​
Android

No dashboard configuration or rebuild is required. Set priority to 10 and android_channel_id to a high-importance channel in your OneSignal payload. To get your channel ID, go to OneSignal > Settings > Messaging > Android Categories and create a new category with importance set to Urgent. OneSignal will generate a channel ID for that category , copy it and use it as android_channel_id in your payload. 
// Backend: send a critical alert on Android
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${process.env.ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify({
        app_id:                    process.env.ONESIGNAL_APP_ID,
        include_external_user_ids: [userId],
        headings:                  { en: 'Urgent alert' },
        contents:                  { en: 'Message body' },
        priority:                  10,
        android_channel_id:        'YOUR_CHANNEL_ID', // from OneSignal > Settings > Messaging > Android Categories
    }),
})

​
Both platforms

To send a single critical alert that works on both Android and iOS, combine the fields in one payload. 
// Backend: send a critical alert on Android and iOS
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${process.env.ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify({
        app_id:                    process.env.ONESIGNAL_APP_ID,
        include_external_user_ids: [userId],
        headings:                  { en: 'Urgent alert' },
        contents:                  { en: 'Message body' },
        priority:                  10,
        android_channel_id:        'YOUR_CHANNEL_ID',
        ios_critical_alert:        1,
    }),
})

​
Deep linking from a notification

To navigate the WebView to a specific page when a user taps a notification, add a url key inside the data field of the OneSignal REST API payload. 
body: JSON.stringify({
    app_id:                    process.env.ONESIGNAL_APP_ID,
    include_external_user_ids: [userId],
    headings:                  { en: 'You have a new message' },
    contents:                  { en: 'Tap to view it' },
    data: {
        url: 'https://yourapp.com/messages/123'  // opened in the WebView on tap
    },
})

​
Segmentation

Beyond include_external_user_ids, OneSignal supports segments based on user behaviour. Set tags on users to create custom segments. 
// Backend: add a tag to a user
await fetch(`https://onesignal.com/api/v1/apps/${appId}/users/${externalUserId}`, {
    method: 'PUT',
    headers: { 'Authorization': `Basic ${restApiKey}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ tags: { plan: 'premium', last_purchase: '2026-01-01' } }),
})

// Send to all users with plan=premium tag
body: JSON.stringify({
    app_id:   process.env.ONESIGNAL_APP_ID,
    filters:  [{ field: 'tag', key: 'plan', relation: '=', value: 'premium' }],
    headings: { en: 'Premium member offer' },
    contents: { en: 'Exclusive deal just for you' },
})

​
Resources

NPM Package

despia-native

OneSignal Dashboard

Configure your push notification app

Create Notification API

Full OneSignal REST API reference

Support

support@despia.com