Skip to main content

​
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"

​
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